6.6 Multi-threaded mixed C and Prolog applications

All foreign-code linked to the multi-threading version of SWI-Prolog should be thread-safe (reentrant) or guarded in Prolog using with_mutex/2 from simultaneous access from multiple Prolog threads. If you want to write mixed multi-threaded C and Prolog application you should first familiarise yourself with writing multi-threaded applications in C (C++).

If you are using SWI-Prolog as an embedded engine in a multi-threaded application you can access the Prolog engine from multiple threads by creating an engine in each thread from which you call Prolog. Without creating an engine, a thread can only use functions that do not use the term_t type (for example PL_new_atom()).

Please note that the interface below will only work if threading in your application is based on the same thread-library as used to compile SWI-Prolog.

int PL_thread_self()

Returns the integer Prolog identifier of the engine or -1 if the calling thread has no Prolog engine. This function is also provided in the single-threaded version of SWI-Prolog, where it returns -2.

int PL_thread_attach_engine(const PL_thread_attr_t *attr)

Creates a new Prolog engine in the calling thread. If the calling thread already has an engine the reference count of the engine is incremented. The attr argument can be NULL to create a thread with default attributes. Otherwise it is a pointer to a structure with the definition below. For any field with value `0', the default is used. The cancel field may be filled with a pointer to a function that is called when PL_cleanup() terminates the running Prolog engines. If this function is not present or returns FALSE pthread_cancel() is used.

typedef struct { unsigned long local_size; /* Stack sizes (K-bytes) */ unsigned long global_size; unsigned long trail_size; unsigned long argument_size; char * alias; /* alias name */ int (*cancel)(int thread); } PL_thread_attr_t;

The structure may be destroyed after PL_thread_attach_engine() has returned. On success it returns the Prolog identifier for the thread (as returned by PL_thread_self()). If an error occurs, -1 is returned. If this Prolog is not compiled for multi-threading, -2 is returned.

int PL_thread_destroy_engine()

Destroy the Prolog engine in the calling thread. Only takes effect if PL_thread_destroy_engine() is called as many times as PL_thread_attach_engine() in this thread. Returns TRUE on success and FALSE if the calling thread has no engine or this Prolog does not support threads.

Please note that construction and destruction of engines are relatively expensive operations. Only destroy an engine if performance is not critical and memory is a critical resource.

int PL_thread_at_exit(void (*function)(void *), void *closure, int global)

Register a handle to be called as the Prolog engine is destroyed. The handler function is called with one void * argument holding closure. If global is TRUE, the handler is installed for all threads. Globally installed handlers are executed after the thread-local handlers. If the handler is installed local for the current thread only (global == FALSE) it is stored in the same FIFO queue as used by thread_at_exit/1.