Interpreter API requirements

Interpreter API requirements

Michael Haberler, 4/2014

Preliminary

This document Interpreter control flow explained is suggested reading before reading this document - it explains the current API and control flow.

Terminology

• Embedding: a piece of software which supports this API to the outside world, and may host arbitrary interpreter code. An interpreter embedding entails the code calling the interpreter API (mostly as it stands now), plus an improved canon layer. Technically this will be a demon supporting several remote interfaces, an enhanced canon layer, and a standard interface to a contained interpreter.

Scope

This document addresses requirements for interpreter embedding, as well as for future canon support.

Interpreter API requirements

Remote Operation

• Any operation sent to, and any output, status or error result MUST be accessible remotely (i.e. without assuming shared memory or the same host).

Multiple instance support

• Using code MUST be able to start several interpreter instances, and switch between them.

• Switching between instances means deactivating the current instance, and activating another instance. Deactivating means: no output on canon, state is frozen as is.

• There MUST be the notion of a currently active interpreter instance.

• Interpreters MUST have a unique ID (eg a string).

• It MUST be possible to run, pause, abort, and step the currently active instance.

• It MUST be possible to sync any instance from the current machine state.

• It SHOULD be possible to sync any instance from another instance.

Selectable canon output type

• It MUST be possible to runtime-select on of several possible canon output types, which are:

  • canon commands to drive a machine

  • canon commands to generate a stream of graphics primitives for preview

  • canon output for informational/debugging purposes (like the current saicanon output).

Selectable canon output channels

• It MUST be possible to send output of different canon types through different channels.

• Canon output channels SHOULD support several consuming entities in parallel.

Canon output flow control

• Canon output channels MUST support flow control.

• If an output queue reaches a highwater mark, the interpreter instance MUST suspend until some low water mark has been reached.

Interpreter state reporting

• An interpreter instance MUST be able to publish its current state to an arbitrary number of state subscribers.

Interpreter command interface

• The API to send commands to the interpreter shall in the minimum encompass:

  • send a string for execution

  • send a file for execution

  • abort an interpreter run

  • select a canon output type and channel

Interface between interpreter and embedding

• It MUST be possible to integrate an interpreter which has an existing read-eval-print loop.

• The interpreter MUST run in its own thread (or process).

• There MUST be an API which supports blocking external interaction (e.g. asking a UI for values), with the interpreter being the active part.

• The canon layer SHOULD be switchable between several output formats and channels (for purposes of driving the machine, preview display, or debug output)

Source coordinates

• There SHOULD be an interpreter- and language agnostic way to denote a source context (file/string/line number/offset).

• A source context MUST be uniquely denoted by a single scalar value (ie a 64bit quantity).

• There SHOULD be a way to 'run from line', i.e. start output generation only once a certain source context is reached.