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.