Prolog engines live as entities that are independent from threads.
They are always supported in the multi-threaded version and may be
enabled in the single threaded version by providing -DENGINES=ON
during the
cmake configuration. Multiple threads may use a pool of engines
for handling calls to Prolog. A single thread may use multiple engines
to achieve coroutining. Engines are suitable in the following
identified cases:
- 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.
- Achieving coroutines
A single thread may use engines to implement coroutining. This
is notably interesting when combined with yielding as described
in section
12.4.1.2.
- PL_engine_t PL_current_engine()
- Returns the current engine of the calling thread or
NULL if
the thread has no Prolog engine.
- PL_engine_t PL_create_engine(PL_thread_attr_t
*attributes)
- Create a new Prolog engine. attributes is described with
PL_thread_attach_engine().
Any thread can make this call after
PL_initialise()
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.
- bool 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 FALSE.
- int PL_set_engine(PL_engine_t
engine, PL_engine_t *old)
- Make the calling thread ready to use engine. If old
is non-
NULL the current engine associated with the calling
thread is stored at the given location. If engine equals
PL_ENGINE_MAIN the initial engine is attached to the
calling thread. If engine is PL_ENGINE_CURRENT
the engine is not changed. This can be used to query the current engine.
This call returns
PL_ENGINE_SET if the engine was switched successfully,
PL_ENGINE_INVAL if engine is not a valid engine
handle and
PL_ENGINE_INUSE if 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
term_t, qid_t and fid_t types 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.
The engine to which a query belongs can be requested using PL_query_engine()
In versions that do not support engines this call only succeeds if
engine refers to the main engine.
- void PL_WITH_ENGINE(PL_engine_t
e)
- This macro implements a C for-loop where the body is executed
with the engine e as current engine. The body is executed
exactly once. After completion of the body the current engine of the
calling thread is restored to old state (either the old current engine
or no engine). The user may use
break to terminate the body
early. The user may not use return. Using return
does not reset the old engine.
