In this model Prolog engines live as entities that are independent from threads. If a thread needs to call Prolog it takes one of the engines from the pool and returns the engine when done. This model is suitable in the following identified cases:
- Compatibility with the single-threaded version
In the single-threaded version, foreign threads must serialise access to the one and only thread engine. Functions from this section allow sharing one engine among multiple threads.
- Many native threads with infrequent Prolog work
Prolog threads are expensive in terms of memory and time to create and destroy them. For systems that use a large number of threads that only infrequently need to call Prolog, it is better to take an engine from a pool and return it there.
- Prolog status must be handed to another thread
This situation has been identified by Uwe Lesta when creating a .NET interface for SWI-Prolog. .NET distributes work for an active internet connection over a pool of threads. If a Prolog engine contains the state for a connection, it must be possible to detach the engine from a thread and re-attach it to another thread handling the same connection.
- PL_engine_t PL_create_engine(PL_thread_attr_t *attributes)
- Create a new Prolog engine. attributes is described with
Any thread can make this call after
returns success. The returned engine is not attached to any thread and
lives until PL_destroy_engine()
is used on the returned handle.
In the single-threaded version this call always returns
NULL, indicating failure.
- int PL_destroy_engine(PL_engine_t e)
- Destroy the given engine. Destroying an engine is only allowed if the
engine is not attached to any thread or attached to the calling thread.
On success this function returns
TRUE, on failure the return value is
- int PL_set_engine(PL_engine_t engine, PL_engine_t *old)
- Make the calling thread ready to use engine. If old
NULLthe current engine associated with the calling thread is stored at the given location. If engine equals
PL_ENGINE_MAINthe initial engine is attached to the calling thread. If engine is
PL_ENGINE_CURRENTthe engine is not changed. This can be used to query the current engine. This call returns
PL_ENGINE_SETif the engine was switched successfully,
PL_ENGINE_INVALif engine is not a valid engine handle and
PL_ENGINE_INUSEif the engine is currently in use by another thread.
Engines can be changed at any time. For example, it is allowed to select an engine to initiate a Prolog goal, detach it and at a later moment execute the goal from another thread. Note, however, that the
fid_ttypes are interpreted relative to the engine for which they are created. Behaviour when passing one of these types from one engine to another is undefined.
In the single-threaded version this call only succeeds if engine refers to the main engine.