
engine_create(-Engine, ++Options)

   Create a new ECLiPSe engine

Arguments
   Engine              Output: an engine handle
   Options             A list of option terms

Type
   Engines and Threads

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 --- Options is not fully instantiated.
     5 --- Options is not a list of atoms or compound terms.
     5 --- An option contains an unexpected type.
     6 --- 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
