3 Low-level interface
(require marketplace) |
At its heart, the interface between each process and its containing VM is based on handler functions exchanging event and action structures with the VM. Both events and actions are simple Racket structures.
This low-level interface between a VM and a process is analogous to the system call interface of a Unix-like operating system. The High-level interface corresponds to the C library interface of a Unix-like operating system.
3.1 Handler Functions
Each handler function is always associated with a particular endpoint, registered with the VM via endpoint/endpoint:/add-endpoint. A handler function for a given process with state type State has type:
That is, given an EndpointEvent followed by the process’s current state, the handler should reply with a Transition containing a new process state and a collection of Actions.
type
Handler : (All (State) (TrapK State))
type
type
3.2 Topics and Roles
type
Topic : Any
struct
(struct role (orientation topic interest-type) #:prefab) orientation : Orientation topic : Topic interest-type : InterestType
type
TODO: Role
type
Orientation : (U 'publisher 'subscriber)
type
InterestType : (U 'participant 'observer 'everything)
3.3 Endpoint Events
type
EndpointEvent : (U PresenceEvent AbsenceEvent MessageEvent)
type
type
type
struct
(struct presence-event (role) #:prefab) role : Role
The presence-event-role describes the arriving peer, or more precisely, describes the shared interest between ourselves and the new peer. In particular, the role-orientation of the presence-event-role is the orientation that the peer supplied in its add-endpoint structure.
The absence-event-role describes the departing peer, analogously to presence-event-role.
struct
(struct message-event (role message) #:prefab) role : Role message : Message
3.4 Actions
type
Action : (All (State) (U (PreAction State) (yield State) (at-meta-level State)))
type
PreAction : (All (State) (U (add-endpoint State) delete-endpoint send-message (spawn State) quit))
struct
(struct at-meta-level (preaction) #:prefab) preaction : (PreAction State)
type
AtMetaLevel : (All (State) (at-meta-level State))
3.4.1 Endpoints and Messages
struct
(struct add-endpoint (pre-eid role handler) #:prefab) pre-eid : Any role : Role handler : (Handler State)
type
AddEndpoint : (All (State) (add-endpoint State))
The name of the new endpoint will be the pre-eid; it must be unique within the current process, but otherwise can be any value at all. If the endpoint’s name matches an existing endpoint, and the new role is the same as the existing endpoint’s role, the handler function is replaced in the existing endpoint.
To delete an endpoint, perform a delete-endpoint action built with the name of the endpoint to delete.
If no specific reason is needed, it is conventional to supply #f as the delete-endpoint-reason.
struct
(struct send-message (body orientation) #:prefab) body : Message orientation : Orientation
type
3.4.2 Process Management
struct
(struct spawn (spec k debug-name) #:prefab) spec : process-spec k : (Option (PID -> (InterruptK State))) debug-name : Any
struct
(struct process-spec (boot) #:prefab) boot : (PID -> CoTransition)
type
CoTransition :
(All (Result) (All (State) (Transition State) -> Result) -> Result)
type
Spawn : (All (State) (spawn State))
type
The spawn-spec describes the new process to be created. Its process-spec-boot field is a function taking the PID of the new process and returning a "cotransition". Cotransitions use a second-order encoding of existential types to guarantee that the VM remains oblivious to the specific process state type of the new process. The downside of this approach is its syntactic and type complexity: see spawn: for an easier-to-use, higher-level approach.
If no specific reason is needed, it is conventional to supply #f as the quit-reason.
type
PID : Number