11.6 Engines (original) (raw)

11.6 Engines🔗ℹ

An engine is an abstraction that models processes that can be preempted by a timer or other external trigger. They are inspired by the work of Haynes and Friedman [Haynes84].

Engines log their behavior via a logger with the name'racket/engine. The logger is created when the module is instantiated and uses the result of (current-logger)as its parent. The library logs a 'debug-level message: when engine-runis called, when the engine timeout expires, and when the engine is stopped (either because it terminated or it reached a safe point to stop). Each log message holds a value of the struct:

(struct engine-info (msec name) #:prefab)

where the msec field holds the result of(current-inexact-milliseconds) at the moment of logging, and the name field holds the name of the procedure passed to engine.

Returns an engine object to encapsulate a thread that runs only when allowed. The proc procedure should accept one argument, andproc is run in the engine thread whenengine-run is called. If engine-run returns due to a timeout, then the engine thread is suspended until a future call to engine-run. Thus, proc only executes during the dynamic extent of a engine-run call.

The argument to proc is a procedure that takes a boolean, and it can be used to disable suspends (in case proc has critical regions where it should not be suspended). A true value passed to the procedure enables suspends, and #f disables suspends. Initially, suspends are allowed.

Returns #t if v is an engine produced byengine, #f otherwise.

Allows the thread associated with engine to execute for up to as long as until milliseconds (if until is a real number) or until is ready (if until is an event). Ifengine’s procedure disables suspends, then the engine can run arbitrarily long until it re-enables suspends.

The engine-run procedure returns #t ifengine’s procedure completes (or if it completed earlier), and the result is available via engine-result. Theengine-run procedure returns #f ifengine’s procedure does not complete before it is suspended. If engine’s procedure raises an exception, then it is re-raised byengine-run.

(engine-result engine) → any
engine : engine?

Returns the result for engine if it has completed with a value (as opposed to an exception), #f otherwise.

Forcibly terminates the thread associated with engine if it is still running, leaving the engine result unchanged.