
get_engine_property(+Engine, +Name, -Value)

   Obtain properties of an engine, including current status

Arguments
   Engine              An engine handle
   Name                Property name (atom)
   Value               Output: property value

Type
   Engines and Threads

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 --- Engine or Name is not instantiated
     5 --- Engine is not an engine handle
     5 --- Name is not an atom
     6 --- 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
