[ 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.

Fail Conditions

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

Resatisfiable

No.

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