11.6 Engines

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 11 | Concurrency and Parallelism

11.1 | Threads
11.2 | Synchronization
11.3 | Thread-Local Storage
11.4 | Futures
11.5 | Places
11.6 | Engines
11.7 | Machine Memory Order

On this page:

engine
engine?
engine-run
engine-result
engine-kill

top contents ← prev up next →

### 11.6 Engines🔗ℹ

(require racket/engine) | package: base

The bindings documented in this section are provided by the racket/engine library, not racket/base or racket.

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-run is 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.

> procedure (engine proc) → engine?
> proc : ((any/c . -> . void?) . -> . any/c)

Returns an engine object to encapsulate a thread that runs only when allowed. The proc procedure should accept one argument, and proc is run in the engine thread when engine-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.

> procedure (engine? v) → any
> v : any/c

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

> procedure (engine-run until engine) → boolean?
> until : (or/c evt? real?)
> engine : engine?

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). If engine’s procedure disables suspends, then the engine can run arbitrarily long until it re-enables suspends.

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

> procedure (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.

> procedure (engine-kill engine) → void?
> engine : engine?

Forcibly terminates the thread associated with engine if it is still running, leaving the engine result unchanged.
top contents ← prev up next →