
suspend(+Goal, +Prio, +CondList)

   Suspend the Goal and wake it with priority Prio as soon as one of the
conditions in CondList occurs.

Arguments
   Goal                A callable term.
   Prio                An integer.
   CondList            A term of the form Vars->Cond or trigger(Atom) or a list of such terms.

Type
   Advanced Control and Suspensions

Description
   The specified goal Goal is suspended (a suspension is created as with
   make_suspension/3) and attached to the trigger conditions given in CondList.
   When any of the trigger conditions arise in the future, the goal is
   going to be woken up.

   The Prio argument determines the priority with which the Goal will be
   scheduled when woken. It can be a positive number between 1 and 12,
   or zero, in which case the priority defaults to the priority setting
   of the predicate which is called in Goal. (Note that this is the scheduling
   priority which determines the order of execution; the priority under which
   the woken goal is executed may be higher, and is determined by the
   run_priority predicate property, see set_flag/3).

   CondList is a list of terms (or a single term) of the form Vars->Cond
   or trigger(Atom).  It specifies the conditions that will lead to the goal
   being woken up. It is enough for one of the specified conditions to arise
   in order for the goal to be woken.

   Vars->Cond is used to specify trigger conditions on variables.
   Vars is an arbitrary term, and the suspension will be attached to all
   the variables that occur in Vars.  These trigger conditions correspond
   to suspension lists inside of variables's attributes, and can be
   written in a variety of forms:

        Vars->SUSPLISTNAME                e.g. X->inst
        Vars->ATTRNAME:SUSPLISTNAME       e.g. X->fd:min
        Vars->ATTRNAME:ARGINDEX           e.g. X->fd:(min of fd)
        Vars->ATTRNAME:ARGLIST            e.g. X->fd:[min,max]
        Vars->LISTOFCONDS                 e.g. X->[fd:min,inst]


   There are 3 predefined suspension list names: 'inst' (for instantiation),
   'bound' (instantiation, including aliasing to another variable) and
   'constrained' (any constraining attribute modification).  These all
   belong to an attribute called 'suspend'.  Others are defined by libaries,
   and usually the attribute name is identical to the library name (e.g. fd).

   A specification of the form trigger(Atom) states that the goal should
   be woken by a symbolic trigger, ie.  by a matching invocation of the
   built-in schedule_suspensions/1.  The name of the trigger can be an
   arbitrary atom.

   A variant suspend/4 of this predicate is available.  It returns a handle
   for the created suspension, which is useful for suspending demons.

   NOTE: it is possible to create a suspension that can never be woken,
   e.g. by specifying a Vars-term without variables.



Modes and Determinism
   suspend(+, +, +) is det

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions
     6 --- CondList is ill-formed.

Examples
   
[eclipse 1]: suspend(writeln(hello), 2, X->inst).

X = X

Delayed goals:
        writeln(hello)
yes.
[eclipse 2]: suspend(writeln(hello), 2, X->inst),
        writeln(one),
        X=1,            % causes waking
        writeln(two).
one
hello
two

X = 1
yes.
[eclipse 3]: suspend(writeln(X), 2, [X,Y]->bound), X=Y.
X

X = X
Y = X
yes.
[eclipse 4]: suspend(writeln(world), 2, trigger(hello)), trigger(hello).
world

yes.


See Also
   suspend / 4, make_suspension / 3, insert_suspension / 3, attach_suspensions / 2, schedule_suspensions / 1, meta_attribute / 2, set_flag / 3
