[ Advanced Control and Suspensions | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# get_suspension_data(?Susp, +Name, -Value)

Access properties of suspended goals.

Susp
  A suspension or variable.
Name
  An atom.
Value
  A variable.

## Description

This built-in is used to access the contents of the abstract suspension data type. If applied to an already executed (dead) suspension it fails, unless the state information is requested.

The accessible properties of a suspension are:

        Name            Type        Value
        -------------------------------------------------------------
        goal            Term        Suspended goal
        module          Atom        Context module
        qualified_goal  Atom:Term   Lookup module and goal
        priority        Integer     Waking priority
        invoc           Integer     Invocation number (debugging)
        state           Integer     0 (sleeping), 1 (scheduled), 2 (dead)

Note that a suspension is not a standard logical data structure and can only be manipulated in a restricted way. In particular, a suspension cannot be printed (e.g. using writeq/1,2) and then read back, giving a term identical to the one that was printed.

### Modes and Determinism

- get_suspension_data(?, +, -) is semidet

### Fail Conditions

Fails if Susp is uninstantiated or if the suspension is already dead and Name is not 'state'

### Exceptions

(4) instantiation fault
  Name is not instantiated.
(5) type error
  Susp is not a suspension.
(5) type error
  Name is instantiated but not an atom.
(6) out of range
  Name is not the name of a suspension property.

## Examples

        [eclipse 4]: make_suspension(writeln(hello), 5, S),
            get_suspension_data(S, priority, P),
            get_suspension_data(S, goal, G),
            get_suspension_data(S, module, M),
            get_suspension_data(S, qualified_goal, QG),
            get_suspension_data(S, invoc, I),
            get_suspension_data(S, state, Z).

        P = 5
        G = writeln(hello)
        M = eclipse
        QG = eclipse : writeln(hello)
        I = 0
        S = 'SUSP-_162-susp'
        Z = 0
        Delayed goals:
            writeln(hello)
        yes.

        [eclipse 2]: suspend(writeln(hello), 3, X->inst, S),
            get_suspension_data(S, state, Z0),
            call_priority((X=1,true,get_suspension_data(S, state, Z1)), 2),
            get_suspension_data(S, state, Z2).
        hello

        Z0 = 0
        X = 1
        Z1 = 1
        S = 'SUSP-_161-dead'
        Z2 = 2
        yes.

## See Also

delayed_goals / 1, kill_suspension / 1, make_suspension / 3, get_priority / 1, call_priority / 2, suspend / 3, suspensions / 1, current_suspension / 1, set_suspension_data / 3