[ Engines and Threads | Reference Manual | Alphabetic Index ]

get_engine_property(+Engine, +Name, -Value)

Obtain properties of an engine, including current status
Engine
An engine handle
Name
Property name (atom)
Value
Output: property value

Description

Obtains various properties of the given engine. The engine may be currently running or stopped (to wait for the engine to stop, use engine_join/3).

The different properties are

status

A term indicating the current engine state. Unless the engine is running, the status is the same as the one returned by the most recent engine_resume/3 or engine_join/2. A non-running engine will retain its state until it is resumed again. A status can be one of:

running
Engine is still running and cannot be used, except for engine_join/3, get_engine_property/3 and engine_post/2. Note that this status is unreliable, because an asynchronously running engine can stop running at any time.
true
Engine is stopped after success of its goals. Engine is ready to be resumed with new (additional) goals, which form a conjunction with the already succeeded goals.
false
Engine is stopped after failure of its goals. Engine is ready to be resumed with new goals. This is also the initial state of a new engine.
exception(Term)
Engine is stopped after an uncaught throw(Term). Engine is ready to be resumed with new goals.
yielded(Out)
Engine is stopped in a yield(Out,In) call. The term Out is a copy of the Out argument of the yield/2 call. The engine is ready to be resumed. When resumed, the yield/2 call will succeed with its In argument unified with a copy of the resume's Term argument.
flushio(Stream)
Engine is stopped in a flush operation of the queue Stream. Data is ready to be read from the Stream, after which the engine should be resumed. After resume, the engine will continue after the flush operation. Any term passed to the resume is ignored.
waitio(Stream)
Engine is stopped in a read operation of the empty queue Stream. Data is expected to be written to the Stream, after which the engine should be resumed. After resume, the engine will continue with its read operation. Any term passed to the resume is ignored.
exited(ExitCode)
Engine has stopped following an exit(ExitCode) where ExitCode is an integer. The engine cannot be resumed.

detached

true or false, indicating whether the engine was created with the detached(true) option.

global

The size limit of the engine's global/trail stack in KiB. This value was either given as global(KiBytes) option during engine creation, or was inherited from the creator.

local

The size limit of the engine's local/control stack in KiB. This value was either given as local(KiBytes) option during engine creation, or was inherited from the creator.

references

An integer indicating the number of entities currently holding a reference to the engine. The engine will be garbage collected once this count reaches zero.

report_to

The record handle that the engine uses to report when it is ready to be joined. This property only exists when the engine was created with the report_to(RecordHandle) option, otherwise it fails.

store

A handle for a unique 'store' object associated with the engine. Such a store is automatically created (via implicit store_create/1) the first time the property is requested. It is useful for storing nonlogical engine/thread-local information.

thread

true or false, indicating whether the engine has its own thread. The thread may have been created eagerly at engine creation, or lazily on the first engine_resume_thread/2.

In addition, the pseudo-property all can be used to retrieve a list of all current properties in the form of name(Value) terms.

Modes and Determinism

Fail Conditions

Fails if the engine does not have the given property

Exceptions

(4) instantiation fault
Engine or Name is not instantiated
(5) type error
Engine is not an engine handle
(5) type error
Name is not an atom
(6) out of range
Name is not a recognized property name

Examples

    ?- engine_create(E, []), get_engine_property(E, status, Status).
    E = $&(engine,"375am7")
    Status = false
    Yes (0.00s cpu)

    ?- engine_create(E, []),
       engine_resume(E, writeln(hello), Status1),
       get_engine_property(E, status, Status2).
    hello
    E = $&(engine,"375am7")
    Status1 = true
    Status2 = true
    Yes (0.00s cpu)

    ?- engine_create(E, [thread]),
       engine_resume_thread(E, (writeln(hello),sleep(1),writeln(done))),
       get_engine_property(E, status, Status1),
       writeln(Status1),
       engine_join(E, block, Status2).
    running
    hello
    done
    
    Status1 = running
    Status2 = true
    Yes (0.00s cpu)

    ?- engine_create(E, []),
       get_engine_property(E, global, GlobalSize),
       get_engine_property(E, thread, HasThread),
       get_engine_property(E, references, NumRefs).

    E = $&(engine,"376oe7")
    GlobalSize = 524288
    HasThread = false
    NumRefs = 1
    Yes (0.00s cpu)

    ?- engine_create(E),
       get_engine_property(E, all, Properties).
    E = $&(engine,"376oe7")
    Properties = [status(false), references(1), thread(false),
                  detached(false), local 131072, global 524288]
    Yes (0.00s cpu)

See Also

engine_create / 2, engine_resume / 3, engine_join / 3