[ Advanced Control and Suspensions | Reference Manual | Alphabetic Index ]

# insert_suspension(?Term, +Susp, +Index)

Insert the suspension Susp into the Index'th suspension list of the current module's attribute for all attributed variables that occur in Term.

Term
  Any Prolog term.
Susp
  A suspension.
Index
  An integer.

## Description

This predicate is used to insert a suspension into a suspension list in an attribute of one or more attributed variables. Since Prolog does not allow to insert new elements into a list in constant time, ECLiPSe provides this predicate. It finds all attributed variables occurring in the term Term and for each of them, it locates the attribute which corresponds to the current module. This attribute must be a structure, otherwise an error is raised, which means that the attribute has to be initialised before calling insert_suspension/3. The Index'th argument of the attribute structure is interpreted as a suspension list and the suspension Susp is inserted at the beginning of this list.

### Modes and Determinism

- insert_suspension(?, +, +) is det

### Modules

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

### Exceptions

(4) instantiation fault
  Susp or Index is not instantiated.
(5) type error
  Susp is not a suspension.
(5) type error
  Index is not an integer.
(6) out of range
  The attribute of a variable in Term is a structure whose arity is less than Index.
(270) undefined variable attribute
  The current module has no declared variable attribute.
(271) bad format of the variable attribute
  The attribute of a variable in Term is uninstantiated or it is not a structure.
(271) bad format of the variable attribute
  The suspension list in the attribute of a variable in Term is neither a list nor a free variable, or it contains an element which is not a suspension.

## Examples

    [eclipse 1]: meta_attribute(eclipse,[]).
    Yes (0.01s cpu)

    [eclipse 2]: Att = att(_, hello), init_suspension_list(1, Att),
            add_attribute(X, Att), make_suspension(true, 1, S),
    	insert_suspension(X, S, 1).

    Att = att(['SUSP-_306-susp'], hello)
    X = X
    S = 'SUSP-_306-susp'

    Delayed goals:
            true
    Yes (0.00s cpu)

## See Also

insert_suspension / 4, make_suspension / 3, meta_attribute / 2, enter_suspension_list / 3