get_engine_property(+Engine, +Name, -Value)

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.

Modes and Determinism

• get_engine_property(+, +, -) is semidet

Fail Conditions

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