Detailed Description

Class Documentation

◆ thread_create/1

class thread_create/1

thread_create(: Goal)

Create a new Prolog detached thread using default options See thread_create/3

Definition at line 1 of file threads.yap.

◆ thread_create/2

class thread_create/2

thread_create(: Goal, - Id)

Create a new Prolog thread using default options See thread_create/3

◆ thread_create/3

class thread_create/3

thread_create(: Goal, - Id, + Options)

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

stack Set the limit in K-Bytes to which the Prolog stacks of this thread may grow If omitted, the limit of the calling thread is used See also the commandline -S option
trail Set the limit in K-Bytes to which the trail stack of this thread may grow If omitted, the limit of the calling thread is used See also the commandline option -T
alias 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_join/2 )
at_exit Define an exit hook for the thread This hook is called when the thread terminates, no matter its exit status
detached If false (default), the thread can be waited for using thread_join/2 thread_join/2 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 note that thread identifiers are freed for reuse after a detached thread finishes or a normal thread has been joined See also thread_join/2 and thread_detach/1

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_self/1

class thread_self/1

thread_self(- Id)

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

◆ thread_join/2

class thread_join/2

thread_join(+ Id, - Status)

Wait for the termination of thread with given Id Then unify the result-status of the thread with Status After this call, Id becomes invalid and all resources associated with the thread are reclaimed Note that threads with the attribute detached true cannot be joined See also current_thread/2

A thread that has been completed without thread_join/2 being called on it is partly reclaimed: the Prolog stacks are released and the C-thread is destroyed A small data-structure representing the exit-status of the thread is retained until thread_join/2 is called on the thread Defined values for Status are:

true The goal has been proven successfully
false The goal has failed
exception( Term) The thread is terminated on an exception See print_message/2 to turn system exceptions into readable messages
exited( Term) The thread is terminated on thread_exit/1 using the argument Term
thread_detach(+ Id)

Switch thread into detached-state (see detached option at thread_create/3 at runtime Id is the identifier of the thread placed in detached state

One of the possible applications is to simplify debugging Threads that are created as detached leave no traces if they crash For not-detached threads the status can be inspected using current_thread/2 Threads nobody is waiting for may be created normally and detach themselves just before completion This way they leave no traces on normal completion and their reason for failure can be inspected

◆ thread_exit/1

class thread_exit/1

thread_exit(+ Term)

Terminates the thread immediately, leaving exited( _Term_) as result-state for thread_join/2 If the thread has the attribute detached true it terminates, but its exit status cannot be retrieved using thread_join/2 making the value of Term irrelevant The Prolog stacks and C-thread are reclaimed

◆ thread_at_exit/1

class thread_at_exit/1

thread_at_exit(: Term)

Run Goal just before releasing the thread resources This is to be compared to at_halt/1 , 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 thread_property/2 using the result of thread_self/1 as thread-identifier If you want to guarantee the execution of an exit hook no matter how the thread terminates (the thread can be aborted before reaching the thread_at_exit/1 call), consider using instead the at_exit/1 option of thread_create/3