[ 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

- get_engine_property(+, +, -) is semidet

### 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