7.7 Predicates for Multi-Threading

The predicates described in this section do not address tabling or dynamic code. With only a few minor deviations the provisional working standard described in [31] is supported. As a result, these predicates are substantially the same as those in SWI, YAP, and other Prologs.

thread_create(+Goal,ThreadId,+OptionsList)

thread
When called from thread $T$, this predicate creates a new XSB thread $T_{new}$ to execute Goal. When goal either succeeds, throws an unhandled error, or fails, $T_{new}$ exits, but thread_create/2 will succeed immediately, binding ThreadId to the XSB thread id of $T_{new}$. Goal must be callable, but need not be fully instantiated. No bindings from Goal are passed back from $T$ to $T_{new}$, so communication between $T_{new}$ and $T$ must be through tables, asserted code, message queues or other side effects.

OptionList allows optional parameters in the configuration for the initial size of XSB stacks, for aliases, and to indicate whether $T_{new}$ is to be created as detached. Note that XSB threads allow automatic stack allocation, so that the size options may be most useful for (32-bit) applications with very large numbers of threads. In this case, setting initial stack sizes to be small may allow more threads to be created on a given hardware platform. Also note that only XSB stacks are affected, the stack size of the underlying Pthread remains unaltered.

• glsize(N): create thread with global (heap) plus local stack size initially set to N kbytes. If not specified, the default size is used. The default size can be set at the command line (cf. Section 3.7), and altered at run time by the XSB flag thread_glsize (cf. Section 6.11).
• tcpsize(N): create thread with trail plus choice point stack size initially set to N kbytes. If not specified, the default size is used (cf. Section 3.7). The default size can be set at the command line (cf. Section 3.7), and altered at run time by the XSB flag thread_tcpsize (cf. Section 6.11).
• complsize(N): create thread with completion stack size initially set to N kbytes. If not specified, the default size is used (cf. Section 3.7). The default size can be set at the command line (cf. Section 3.7), and altered at run time by the XSB flag thread_complsize (cf. Section 6.11).
• pdlsize(N): create thread with N kbytes of unification stack. If not specified, the default size is used (cf. Section 3.7). The default size can be set at the command line (cf. Section 3.7), and altered at run time by the XSB flag thread_pdlsize (cf. Section 6.11).
• detached(Boolean): if Boolean is true, creates detached thread. If Boolean is false, the thread created will be joinable, while if no option is given the default will be used. In Version 3.0 threads are created joinable by default, but this default can be altered at run time by the XSB flag thread_default (cf. Section 6.11).
• alias(Alias): Allow thread ThreadId to be referred to via Alias in all standard thread predicates. Alias remains active for ThreadId until it is joined.

Error Cases

• Goal is a variable
  • instantiation_error.
• Goal is not callable
  • type_error(callable,Goal).
• ThreadId is not a variable
  • type_error(variable,ThreadId)
• OptionList is a partial list or contains an option that is a variable
  • instantiation_error
• OptionList is neither a list nor a partial list
  • type_error(list,OptionsList)
• OptionList contains an option, Option not described above
  • domain_error(thread_option,Option)
• An element of OptionsList is alias(A) and A is already associated with an existing thread, queue, mutex or stream
  • permission_error(create,alias, A)
• An element of OptionsList is alias(A) and A is not an atom
  • type_error(atom,A)
• No more system threads are available (EAGAIN)
  • resource_error(system threads)

thread_create(+Goal,-ThreadId)

thread
Acts as thread_create(Goal,ThreadId,[]).

thread_join(+Threads_or_aliases,-ExitDesignators)

thread
When thread_join/2 is called by thread $T$, Threads_or_aliases must be instantiated to either 1) an XSB thread id or alias; or 2) a list where each element is an XSB thread id or an alias; ExitDesignators must be uninstantiated. The action of the predicate is to suspend $T$ until all of the threads denoted by Threads_or_aliases have exited. At this time, any remaining resources for the threads in ThreadIds will have been reclaimed. Upon success ExitDesignators is either a the thread status of the associated thread (see page ) or a list of such elements.

Error Cases

• Thread_or_Aliases is not instantiated
  • instantiation_error
• Threads_or_aliases is not a list of XSB thread ids or aliases
  • domain_error(listof(thread_or_alias),ThreadIds)
• ExitDesignators is not a variable
  • type_error(variable,ExitDesignatorst)
• ThreadId does not correspond to a valid thread
  • existence_error(valid_thread,ThreadId)
• ThreadId does not correspond to a joinable thread (i.e. ThreadId is detached).
  • permission_error(join,non_joinable_thread,ThreadId)

thread_exit(+ExitTerm)

thread
Exits a thread $T$ with ExitTerm after releasing any mutexes held by $T$, freeing any thread-specific memory allocated for $T$ (we hope). ExitTerm will be used if the caller of $T$ joins to $T$, but will be ignored in other cases. There is no need to call this routine on normal termination of a thread as it is called implicitly on success or (final) failure of a thread's goal.

Error Cases

• ExitCode is a variable
  • instantiation_error

thread_self(?ThreadId_or_Alias)

thread
If ThreadId is an atom, unifies ThreadId_or_Alias with an alias of the calling thread. Otherwise, unifies ThreadId_or_Alias with the XSB thread id of the calling thread. There are no error conditions.

thread_detach(+Thread_or_Alias)

thread
Detaches a joinable thread denoted by Thread_or_Alias so that all resources will be reclaimed upon its exit. The thread denoted by ThreadId will no longer be joinable, once it is detached. If Thread_or_Alias has already exited, all resources used by Thread_or_Alias are removed from the system.

Error Cases

• Thread_or_Alias is a variable
  • instantiation_error
• Thread_or_Alias is not a thread id or alias
  • domain_error(thread_or_alias,Thread_or_Alias)
• Thread_or_Alias does not correspond to a valid thread
  • existence_error(valid_thread,Thread_or_alias)
• Thread_or_Alias is active but not joinable
  • permission_error(thread_detach,thread,Thread_or_Alias)

thread_cancel(+ThreadId)

thread
Cancels the XSB thread denoted by ThreadId. The cancellation does not use Pthread cancellation mechanisms, rather it uses XSB's interrupt mechanism to set ThreadId's interrupt vector. When this interrupt vector is checked, ThreadId will throw a thread cancellation error, which can be caught within ThreadId like any other error. Usually, this means that ThreadId will abort and exit. Note that the high-level upon which thread cancellation is implemented allows for simplicity and portability of thread cancellation ^7.4.

The main XSB thread cannot be cancelled; apart from that any thread can cancel any other thread.

Error Cases

• ThreadId is not instantiated
  • instantiation_error
• ThreadId does not correspond to valid thread
  • existence_error(valid_thread,ThreadId)
• ThreadId denotes the main thread.
  • permission_error(cancel,main_thread,ThreadId)

thread_yield

thread
Make the calling thread ready to be run after other threads of the same priority. This predicate relies on the real-time extensions to Pthreads specified in POSIX 1b, and may not be available on all platforms.

Error Cases

• The current platform does not support POSIX real-time extensions
  • misc_error

usleep(+Microseconds)

thread
Causes the calling thread to sleep approximately Microseconds before resuming.

Error Cases

• Microseconds is a variable
  • instantiation_error.
• Microseconds is not an integer
  • type_error(integer, Microseconds).