Waking conditions for suspensions

The usual purpose of a suspension is to represent a suspended goal which is waiting for a particular event to occur. When this event occurs, the suspension is passed to the waking scheduler which puts it at the appropriate place in the priority queue of woken goals and as soon as it becomes first in the queue, the suspension is executed.

The event which causes a suspension to be woken is usually related to one or more variables, for example variable instantiation, or a modification of a variable's attribute. However, it is also possible to trigger suspension with symbolic events not related to any variable.

Suspensions which should be woken by the same event are grouped together in a suspension list. This is a normal Prolog list which contains suspensions. Suspension lists are either stored in an attribute of an attributed variable or attached to a symbolic trigger.

Attaching Suspensions to Variables

Suspensions are attached to variables by means of the attribute mechanism. For this purpose, a variable attribute needs to have one or more slots reserved for suspension lists. Suspensions can then be inserted into one or several of those lists using

insert_suspension(Vars, Susp, Index)

Insert the suspension Susp into the Index'th suspension list of all attributed variables occurring in Vars. The current module specifies which of the attributes will be taken.

insert_suspension(Vars, Susp, Index, Module)

Similar to insert_suspension/3, but it inserts the suspension into the attribute specified by Module.

For instance,

insert_suspension(Vars, Susp, inst of suspend, suspend)

inserts the suspension into the inst list of the (system-predefined) suspend attribute of all variables that occur in Vars, and

insert_suspension(Vars, Susp, max of fd, fd)

would insert the suspension into the max list of the finite-domain attribute of all variables in Vars.

Note that both predicates find all attributed variables which occur in the general term Vars and for each of them, locate the attribute which corresponds to the current module or the Module argument respectively. This attribute must be a structure, otherwise an error is raised, which means that the attribute has to be initialised before calling insert_suspension/4,3. Finally, the Index'th argument of the attribute is interpreted as a suspension list and the suspension Susp is inserted at the beginning of this list. A more user-friendly interface to access suspension lists is provided by the suspend/3 predicate.

User-defined Suspension Lists

Many important attributes and suspension lists are either provided by the suspend-attribute or by libraries like the Finite Domain library lib(fd). For those suspension lists, initialisation and waking is taken care of.

For the implementation of user-defined suspension lists, the following low-level primitives are provided:

init_suspension_list(+Position, +Attribute)

Initialises argument Position of Attribute to an empty suspension list.

merge_suspension_lists(+Pos1, +Attr1, +Pos2, +Attr2)

Destructively appends the first suspension list (argument Pos1 of Attr1) to the end of the second (argument Pos2 of Attr2).

enter_suspension_list(+Pos, +Attr, +Susp)

Adds the suspension Susp to the suspension list in the argument position Pos of Attr. The suspension list can be pre-existing, or the argument could be uninstantiated, in which case a new suspension list will be created.

schedule_suspensions(+Position, +Attribute)

Takes the suspension list on argument position Position within Attribute, and schedule them for execution. As a side effect, the suspension list within Attribute is updated, ie. suspensions which are no longer useful are removed destructively. See section 17.5 for more details on waking.

Attaching Suspensions to Global Triggers

A single suspension or a list of suspensions can be attached to a symbolic trigger by using attach_suspensions(+Trigger, +Susps). A symbolic trigger can have an arbitrary name (an atom). To "pull the trigger" schedule_suspensions(+Trigger) is used which will submit all attached suspensions to the waking scheduler.

Postponed Goals

There is one system-defined trigger called postponed. It is provided as a way to postpone the triggering of a goal as much as possible. This trigger is pulled just before the end of certain encapsulated executions, like

• end of toplevel execution
• inside all-solution predicates (findall/3, setof/3)
• inside min_max/2 and minimize/2

A suspension should be attached to the postponed trigger only when

• it might not have any other waking conditions left
• and it might at the same time have other waking conditions left that could make it fail during further execution
• and one does not want to execute it now, e.g. because it is known to succeed or re-suspend

An example is a goal that used to wait for modifications of the upper bound of an interval variable. If the variable gets instantiated to its upper bound, there is no need to wake the goal (since the bound has not changed), but the variable (and with it the waking condition) disappears and the goal may be left orphaned.