[ Engines and Threads | Reference Manual | Alphabetic Index ]

# engine_create(-Engine, ++Options)

Create a new ECLiPSe engine

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

On the other hand, engines share (or can share) the following:

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

Engines can be created, instructed to execute ECLiPSe code, and their status and results queried. The programming paradigm is that of an engine as a co-routine, which is either running or stopped. An engine is set running using a resume-operation, and will then run until it comes to a stop (which can be for several reasons, encoded in the engine status).

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

engine_resume / 3, engine_resume_thread / 2, engine_join / 3, get_engine_property / 3, set_flag / 2