Node:Initializing the Prolog Engine, Next:, Previous:User-defined Main Programs, Up:User-defined Main Programs


Initializing the Prolog Engine

The Prolog Engine is initialized by calling SP_initialize(). This must be done before any interface functions are called, except SP_force_interactive, SP_set_memalloc_hooks, SP_set_wcx_hooks, SP_set_user_stream_post_hook and SP_set_user_stream_hook. The function will allocate data areas used by Prolog, initialize command line arguments so that they can be accessed by the argv Prolog flag, and load the Runtime Library. It is called like this: 

int SP_initialize(int argc, char **argv, char *boot_path)

boot_path should be the name of a directory, equivalent to $SP_PATH/bin. If boot_path is NULL, SP_initialize() will look up the value of the environment variable SP_PATH and look for the file $SP_PATH/bin/sprt.sav which contains the Runtime Library.

It returns SP_SUCCESS if initialization was successful, and SP_ERROR otherwise. If initialization was successful, further calls to SP_initialize() will be no-ops (and return SP_SUCCESS).

To unload the SICStus emulator, SP_deinitalize() can be called. 

void SP_deinitialize(void)

SP_deinitialize() will make a best effort to restore the system to the state it was in at the time of calling SP_initialize(). This involves unloading foreign resources, shutting down the emulator by calling halt/0, and deallocate memory used by Prolog. SP_deinitialize() is idempotent as well, i.e. it is a no-op unless SICStus has actually been initialized.

You may also call SP_force_interactive() before calling SP_initialize(). This will force the I/O built-in predicates to treat the standard input stream as a terminal, even if it does not appear to be a terminal. Same as the -i option in development systems. (see Start). 

void SP_force_interactive(void)

You may also call SP_set_memalloc_hooks() before calling SP_initialize(). This will define the bottom layer of Prolog's memory manager, in case your application has special requirements. 

typedef void *(SP_AllocHook)(unsigned int size,
                             unsigned int align,
                             unsigned int *actual_sizep);
typedef void *(SP_ReAllocHook)(void *ptr,
                               unsigned int oldsize,
                               unsigned int newsize,
                               unsigned int align,
                               unsigned int *actual_sizep);
typedef int (SP_FreeHook)(void *ptr,
                          unsigned int size);

void SP_set_memalloc_hooks(int usage,
                           SP_AllocHook *init_alloc_hook,
                           SP_AllocHook *alloc_hook,
                           SP_ReAllocHook *realloc_hook,
                           SP_FreeHook *free_hook)

The effect of SP_set_memalloc_hooks is controlled by the value of usage, which should be one of:

MM_USE_MALLOC
The bottom layer will be based on malloc()/free(). The other arguments are ignored. Same as the -m option in development systems. (see Start).
MM_USE_SBRK
The bottom layer will be based on sbrk(). The default for UNIX development systems; not available for Windows. The other arguments are ignored.

This option seems to work well in practice but standard UNIX documents sbrk() as incompatible with malloc() etc and it is not safe to use if more than one thread allocates memory. These concerns are the reason this option is no longer the default for run-time systems.

MM_USE_SPARSE
The bottom layer will be based on VirtualAlloc()/VirtualFree(). The default for Windows; not available for UNIX. The other arguments are ignored.
MM_USE_DEFAULT
The bottom layer will use on some safe default. Currently MM_USE_MALLOC on UNIX and MM_USE_SPARSE on Windows. The default for run-time systems.
MM_USE_OTHER
The bottom layer will be based on the other arguments. Their meaning is explained below. See The Application Builder, for an example.

In the latter case, the other arguments should be functions as specified below. Pointer arguments and values should be aligned pointers.

alloc_hook
must allocate and return a pointer to a piece of memory that has at least size bytes aligned at align in it. align is guaranteed to be a power of 2. The actual size of the piece of memory should be returned in *actual_sizep. Should return NULL if it cannot allocate any more memory.
init_alloc_hook
is a special case of alloc_hook. It will be called initially whereas alloc_hook will be called subsequently. It can do whatever initialization that this layer of memory management wants to do.
realloc_hook
is called with a piece of memory to be resized and possibly moved. ptr is the pointer, oldsize its current size. The function must allocate and return a pointer to a piece of memory that has at least newsize bytes aligned at align in it, and that has the same contents as the old block up to the lesser of oldsize and newsize. align is guaranteed to be a power of 2. The actual size of the piece of memory should be returned in *actual_sizep. Should return NULL if it cannot allocate any more memory, or if it cannot reclaim the old block in a meaningful way. In that case, Prolog will use the other functions. The realloc_hook argument is currently ignored but may be used in future versions of SICStus.
free_hook
is called with a pointer to the piece of memory to be freed and its size. Should return non-zero iff the function was able to free this piece of memory. Otherwise, Prolog will keep using the memory as if it were not freed.

The default bottom layers look at the environment variables PROLOGINITSIZE, PROLOGINCSIZE, PROLOGKEEPSIZE and PROLOGMAXSIZE. They are useful to customize the default memory manager. If users redefine the bottom layer, they can choose to ignore these environment variables. See Environment Variables.

Node:Initializing the Prolog engine, Next:, Previous:Setting up the interface, Up:How to use the interface


Initializing the Prolog engine

The Visual Basic interface must be explicitly initialized: you must call PrologInit() before calling any other interface function. The PrologInit function loads and initializes the interface. It returns 1 if the initialization was successful, and -1 otherwise.