This module defines simple to use predicates for running goals concurrently. Where the core multi-threaded API is targeted at communicating long-living threads, the predicates here are defined to run goals concurrently without having to deal with thread creation and maintenance explicitely.
Note that these predicates run goals concurrently and therefore these goals need to be thread-safe. As the predicates in this module also abort branches of the computation that are no longer needed, predicates that have side-effect must act properly. In a nutshell, this has the following consequences:
Execution succeeds if all goals have succeeded. If one goal fails or throws an exception, other workers are abandoned as soon as possible and the entire computation fails or re-throws the exception. Note that if multiple goals fail or raise an error it is not defined which error or failure is reported.
On successful completion, variable bindings are returned. Note however that threads have independent stacks and therefore the goal is copied to the worker thread and the result is copied back to the caller of concurrent/3.
Choosing the right number of threads is not always obvious. Here are some scenarios:
| N | Number of worker-threads to create. Using 1, no threads are created. If N is larger than the number of Goals we create exactly as many threads as there are Goals. |
| Goals | List of callable terms. |
| Options | Passed to thread_create/3 for creating the workers. Only options changing the stack-sizes can be used. In particular, do not pass the detached or alias options. |
(Generator,Test). This predicate
creates a thread providing solutions for Generator that are
handed to a pool of threads that run Test for the different
instantiations provided by Generator concurrently. The
predicate is logically equivalent to a simple conjunction except for two
aspects: (1) terms are copied from Generator to the
test Test threads while answers are copied back to the
calling thread and (2) answers may be produced out of order.
If the evaluation of some Test raises an exception, concurrent_and/2,3 is terminated with this exception. If the caller commits after a given answer or raises an exception while concurrent_and/2,3 is active with pending choice points, all involved resources are reclaimed.
Options:
This predicate was proposed by Jan Burse as
balance((Generator,Test)).
cpu_count. If
this flag is absent or 1 or List has less than two elements,
this predicate calls the corresponding maplist/N version using a wrapper
based on once/1. Note
that all goals are executed as if wrapped in
once/1 and therefore
these predicates are semidet.
Note that the the overhead of this predicate is considerable and therefore Goal must be fairly expensive before one reaches a speedup.
For example, if it is unclear whether it is better to search a graph breadth-first or depth-first we can use:
search_graph(Grap, Path) :-
first_solution(Path, [ breadth_first(Graph, Path),
depth_first(Graph, Path)
],
[]).
Options include thread stack-sizes passed to
thread_create, as well as the options on_fail and on_error
that specify what to do if a solver fails or triggers an error. By
default execution of all solvers is terminated and the result is
returned. Sometimes one may wish to continue. One such scenario is if
one of the solvers may run out of resources or one of the solvers is
known to be incomplete.
stop (default), terminate all threads and stop with the
failure. If continue, keep waiting.stop(Reason) exception
into Goal. Interrupts can be nested, i.e., it is allowed to
run a call_in_thread/2
while the target thread is processing such an interrupt.
This predicate is primarily intended for debugging and inspection tasks.