Multi-threading (alpha code)

The features described in this section are only enabled on Unix systems providing POSIX threads and if the system is configured using the enable-mt option. SWI-Prolog multi-theading support is experimental and in some areas not safe.

SWI-Prolog multithreading is based on standard C-language multithreading support. It is not like ParLog or other paralel implementations of the Prolog language. Prolog threads have their own stacks and only share the Prolog heap: predicates, records, flags and other global non-backtrackable data. SWI-Prolog thread support is designed with the following goals in mind.

thread_create3:Goal, -Id, +Options Create a new Prolog thread (and underlying C-thread) and start it by executing Goal. If the thread is created succesfully, the thread-identifier of the created thread is unified to Id. Options is a list of options. Currently defined options are:

localK-Bytes Set the limit to which the local stack of this thread may grow. If omited, the limit of the calling thread is used. See also the -L commandline option. globalK-Bytes Set the limit to which the global stack of this thread may grow. If omited, the limit of the calling thread is used. See also the -G commandline option. trailK-Bytes Set the limit to which the trail stack of this thread may grow. If omited, the limit of the calling thread is used. See also the -T commandline option. argumentK-Bytes Set the limit to which the argument stack of this thread may grow. If omited, the limit of the calling thread is used. See also the -A commandline option. aliasAliasName Associate an `alias-name' with the thread. This named may be used to refer to the thread and remains valid until the thread is joined (see thread_join2). detachedBool If false (default), the thread can be waited for using thread_join2. thread_join2 must be called on this thread to reclaim the all resources associated to the thread. If true, the system will reclaim all associated resources automatically after the thread finishes. Please not that thread identifiers are freed for reuse after a detached thread finishes or a normal thread has been joined.

The Goal argument is copied to the new Prolog engine. This implies further instantiation of this term in either thread does not have consequences for the other thread: Prolog threads do not share data from their stacks.

thread_self1-Id Get the Prolog thread identifier of the running thread. If the thread has an alias, the alias-name is returned.

current_thread2?Id, ?Status Enumerates identifiers and status of all currently known threads. Calling current_thread2 does not influence any thread. See also thread_join2. For threads that have an alias-name, this name is returned in Id instead of the numerical thread identifier. Status is one of:

running The thread is running. This is the initial status of a thread. Please note that threats waiting for something are considered running too. false The Goal of the thread has been completed and failed. true The Goal of the thread has been completed and succeeded. exitedTerm The Goal of the thread has been terminated using thread_exit1 with Term as argument. exceptionTerm The Goal of the thread has been terminated due to an uncaught exception (see throw1 and catch3).

thread_join2+Id, -Status Wait for the termination of thread with given Id. Then unify the result-status (see thread_exit1) of the thread with Status. After this call, Id becomes invalid and all resources associated with the thread are reclaimed. See also current_thread2.

A thread that has been completed without thread_join2 being called on it is partly reclaimed: the Prolog stacks are released and the C-thread is destroyed. A small data-structure represening the exit-status of the thread is retained until thread_join2 is called on the thread.

thread_exit1+Term Terminates the thread immediately, leaving exitedTerm as result-state. The Prolog stacks and C-thread are reclaimed.

thread_at_exit1:Goal Run Goal after the execution of this thread has terminated. This is to be compared to at_halt1, but only for the current thread. These hooks are ran regardless of why the execution of the thread has been completed. As these hooks are run, the return-code is already available through current_thread2.