12.3.93 SP_set_memalloc_hooks() [preinit]

Synopsis

     #include <sicstus/sicstus.h>
     
     typedef int
     SP_InitAllocHook(size_t alignment,
                      void *cookie);
     typedef void
     SP_DeinitAllocHook(void *cookie);
     typedef void *
     SP_AllocHook(size_t size,
     	     size_t *actual_sizep,
     	     void *cookie);
     typedef int
     SP_FreeHook(void *ptr,
     	    size_t size,
     	    int force,
     	    void *cookie);
     int
     SP_set_memalloc_hooks(int hint,
     		      SP_InitAllocHook *init_alloc_hook,
     		      SP_DeinitAllocHook *deinit_alloc_hook,
     		      SP_AllocHook *alloc_hook,
     		      SP_FreeHook *free_hook,
     		      void *cookie);

Defines the Prolog memory manager's bottom layer. Must be called before SP_initialize().

Arguments

hint

One of

0 (zero)

This is the usual case and the other arguments are interpreted as described below.

SP_SET_MEMALLOC_HOOKS_HINT_USE_MALLOC

The SICStus memory manager will by bypassed and instead the C library malloc() et al. will be used for all allocations. This is useful, e.g. in combination with tools like valgrind.

In this case all the other arguments must be NULL.

When this option is used some memory statistics, e.g. statistics/[0,2], may be unavailable or misleading.

On some systems, SP_SET_MEMALLOC_HOOKS_HINT_USE_MALLOC will be used automatically when the SICStus runtime detects that it is being run within valgrind (http://www.valgrind.org/). This behavior can be disabled by explicitly setting the system property (or environment variable) SP_USE_MALLOC to no (see System Properties and Environment Variables). This feature is currently (4.0.8) available on x86 and x86_64 Linux.

Please note: SICStus can only use malloc() on platforms where it is guaranteed to return sufficiently aligned memory (2 * sizeof(void*)). This is true at least on Linux, Mac OS X and Windows (on Windows _aligned_malloc() is used instead of malloc()). On platforms where alignment cannot be ensured SICStus will not be able to allocate memory and initialization will fail if SP_SET_MEMALLOC_HOOKS_HINT_USE_MALLOC is used.

Please note: When SP_SET_MEMALLOC_HOOKS_HINT_USE_MALLOC is used SP_deinitialize() may not be able to reclaim all memory. This is mainly a problem when SICstus is embedded into some other application that continues to run after calling SP_deinitialize(). This limitations also means that leak detecton tools like valgrind will report large amounts of leaked memory.

Since 4.0.5.

init_alloc_hook

is called initially. alignment is guaranteed to be a power of 2, and is used by alloc_hook. earliest_start (inclusive) and latest_end (exclusive) are the bounds within which address-constrained memory blocks must fit. Both are aligned according to alignment and non-zero. The function can do whatever initialization that this layer of memory management wants to do. It should return non-zero if it succeeds, zero if the memory manager bottom layer could not be initialized, in which case initialization of the SICStus runtime will fail.

deinit_alloc_hook

is called by SP_deinitialize() when the Prolog engine shuts down. The function can do any necessary cleaning up.

alloc_hook

must allocate and return a pointer to a piece of memory that contains at least size bytes aligned at a multiple of alignment. The actual size of the piece of memory should be returned in *actual_sizep. Should return NULL if it cannot allocate a suitable piece of memory. Note that the memory returned need not be aligned as long as there is room for an aligned block of at least size bytes.

free_hook

is called with a pointer to a piece of memory to be freed and its size as returned by alloc_hook. If force is non-zero, free_hook must accept the piece of memory; otherwise, it only accepts it if it is able to return it to the operating system. free_hook should return non-zero iff it accepts the piece of memory. Otherwise, the upper layer will keep using the memory as if it were not freed.

cookie

can be used for any state needed by the memory hook functions. The value passed to SP_set_memalloc_hooks() is passed to each hook function. One possible use is to keep track of multiple SICStus runtimes within the same process.

Return Value

Non-zero on success, Zero on error, e.g. if called after SP_initialize().

Description

The default bottom layers look at the system properties PROLOGINITSIZE, PROLOGINCSIZE, PROLOGKEEPSIZE and PROLOGMAXSIZE. They are useful for customizing the default memory manager. If you redefine the bottom layer, you can choose to ignore these system properties.

See Also

Initializing the Prolog Engine. System Properties and Environment Variables.