threaded_once_1_2.rst

.. rst-class:: align-right

built-in predicate

.. index:: pair: threaded_once/1-2; Built-in predicate

threaded_once/1-2

Description

threaded_once(Goal)
threaded_once(Goal, Tag)

Proves Goal asynchronously using a new thread. Only the first goal solution is found. The argument can be a message sending goal. This call always succeeds. The result (success, failure, or exception) is sent back to the message queue of the object containing the call (:term:`this`).

The threaded_once/2 variant returns a threaded call identifier tag that can be used with the :ref:`threaded_exit/2 <predicates_threaded_exit_1_2>` and :ref:`predicates_threaded_cancel_1` predicates. Tags shall be regarded as opaque terms; users shall not rely on its type.

Note

This predicate requires a :term:`backend Prolog compiler` providing compatible multi-threading primitives. The value of the read-only :ref:`threads <flag_threads>` flag is set to supported when that is the case.

Meta-predicate template

threaded_once(0)
threaded_once(0, *)

Modes and number of proofs

threaded_once(@callable) - one
threaded_once(@callable, --nonvar) - one

Errors

Goal is a variable:

instantiation_error

Goal is neither a variable nor a callable term:

type_error(callable, Goal)

Tag is not a variable:

uninstantiation_error(Tag)

Examples

Prove Goal asynchronously in a new thread:

threaded_once(Goal)

Prove ::Message asynchronously in a new thread:

threaded_once(::Message)

Prove Object::Message asynchronously in a new thread:

threaded_once(Object::Message)

.. seealso::

   :ref:`predicates_threaded_call_1_2`,
   :ref:`predicates_threaded_exit_1_2`,
   :ref:`predicates_threaded_ignore_1`,
   :ref:`predicates_threaded_peek_1_2`,
   :ref:`predicates_threaded_cancel_1`,
   :ref:`predicates_threaded_1`,
   :ref:`directives_synchronized_1`