In the one-to-one model, the thread that called PL_initialise()
has a Prolog engine attached. If another C thread in the system wishes
to call Prolog it must first attach an engine using PL_thread_attach_engine()
and call PL_thread_destroy_engine()
after all Prolog work is finished. This model is especially suitable
with long running threads that need to do Prolog work regularly. See section
10.6.2 for the alternative many-to-many model.
- 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_unify_thread_id(term_t
t, int i)
- Unify t with the Prolog thread identifier for thread i.
Thread identifiers are normally returned from PL_thread_self().
Returns -1 if the thread does not exist or the unification fails.
- 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. The new
thread inherits is properties from Prolog's main thread.
The flags field defines the following flags:
- PL_THREAD_NO_DEBUG
- If this flag is present, the thread starts in normal no-debug status. By
default, the debug status is inherited from the main thread.
- PL_THREAD_NOT_DETACHED
- By default the new thread is created in detached mode. With
this flag it is created normally, allowing Prolog to join the
thread.
- PL_THREAD_CUR_STREAMS
- By default the
current_input and current_output
are set to user_input and user_output of the
main thread. Using this flag, these streams are copied from the main
thread. See also the inherited_from option of thread_create/3.
typedef struct
{ size_t stack_limit; /* Total stack limit (bytes) */
size_t table_space; /* Total tabling space limit (bytes) */
char * alias; /* alias name */
int (*cancel)(int thread); /* cancel function */
intptr_t flags; /* PL_THREAD_* flags */
size_t max_queue_size; /* Max size of associated queue */
} 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
multithreading, -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.
