engine_create(-Engine, ++Options)

Engine

Output: an engine handle

Options

A list of option terms

Description

An 'engine' is an entity that can execute goals, but has its own independent control flow and data areas. This implies:

• backtracking in one engine does not affect another
• engines can operate in a concurrent or interleaved fashion
• communication between engines is explicit
• data transferred between engines is copied, variables cannot be shared

• loaded modules and predicates
• non-logical storage such as global variables, records, stores, shelves
• global settings (set_flag/2,3)
• streams

ECLiPSe initially starts up with a single (implicitly created) engine, which executes all code. This predicate creates additional engines.

The following Options are recognized:

thread or thread(Bool)

If true, the engine is associated with its own thread and can run concurrently with other engines. If false, the engine is passive and can only run interleaved with a parent's engine's execution (as a co-routine, using engine_resume/3). Default is false.

report_to(RecordHandle)

Whenever the engine stops running (in its own thread), and is ready to be joined, indicate this by entering the engine handle into the given record-queue. This is done by implicitly calling record_wait_append(RecordHandle,EngineHandle,...). This allows other threads to be notified when an engine is ready. RecordHandle should have been created with record_create/1, or obtained from a named record using name_to_handle/3.

detached or detached(Bool)

Destroy engine as soon as it finishes running in its own thread, instead of waiting for engine_join/3. Default is false. This option is mostly for compatibility, as ECLiPSe will automatically destroy unreferenced engines on failure and garbage collection, even when they are never joined.

global(KiBytes)

size limit of the engine's global/trail stack in KiB. Corresponds to ECLiPSe's -g command line option. Defaults to the parent's engine's default_globalsize setting (see set_flag/2).

local(KiBytes)

size limit of the engine's local/control stack in KiB. Corresponds to ECLiPSe's -l command line option. Defaults to the parent's engine's default_localsize setting (see set_flag/2).

verbose

Print messages on log_output when engine is created, shared or deallocated.

A newly created engine has status 'false', and is ready to be resumed and execute goals. An engine lives as long as its handle is accessible, or as long as it is running, whichever is longer. It is normally not necessary to destroy engines explicitly.

An engine inherits its parent engine's pseudo-random generator state.

Modes and Determinism

• engine_create(-, ++) is det

Exceptions

(4) instantiation fault

Options is not fully instantiated.

(5) type error

Options is not a list of atoms or compound terms.

(5) type error

An option contains an unexpected type.

(6) out of range

An option is not recognized.

Examples

    ?- engine_create(E, []).
    E = $&(engine,"376oe7")
    Yes (0.00s cpu)

    ?- engine_create(E, [thread]).
    E = $&(engine,"376oe7")
    Yes (0.00s cpu)

    ?- engine_create(E, [local(1000),global(10000)]).
    E = $&(engine,"376oe7")
    Yes (0.00s cpu)

See Also