5.2.2 Rolling your own vats

Goblins comes with a built-in vat implementation that is general-purpose and useful in most situations. However, using Goblins with a foreign event loop (such as a GUI widget toolkit or game engine) calls for a specialized vat that knows how to hook into it. The API described below is considered unstable and likely to change in future releases of Goblins, so be prepared to update custom vat code at a later date.

The make-vat constructor is used to make specialized vats. Below is some pseudocode that illustrates the basic pattern:

> (define (make-custom-vat)
    (define thread #f)
    (define (start churn)
      (define (loop)
        (churn (dequeue-msg))
        (loop))
      (set! thread (call-with-new-thread loop)))
    (define (halt)
      (cancel-thread thread))
    (define (send msg return?)
      (if return?
          (enqueue-msg-and-wait-for-result msg)
          (enqueue-msg msg)))
    (make-vat #:start start
              #:halt halt
              #:send send))

How to implement enqueue-msg, enqueue-msg-and-wait-for-result, and dequeue-msg depends on the integration target and is left as an exercise for the implementer.

Vat implementations must provide three hook procedures to make-vat:

• start: This procedure starts the vat message processor in the desired foreign event loop. It accepts a churn procedure as its only argument. The churn procedure accepts a message object and processes it using the vat’s underlying actormap.
• halt: This procedure stops vat message processing. It is a thunk, meaning that it accepts zero arguments.
• send: This procedure receives a message to process within the vat. It accepts two arguments: a message and a boolean flag indicating if the result of processing the message needs to be returned to the caller. When the return flag is #f, vat implementations can simply queue the message for processing and move on. When it is #t, however, the vat must arrange to wait and retrieve the eventual result of processing the message.

Custom vat implementations must enqueue and dequeue messages in a thread-safe manner because incoming messages from other vats may be, and likely are, running in a different thread.

The vat-start! procedure initiates the processing of messages sent to the vat.

> (define custom-vat (make-custom-vat))
> (vat-start! custom-vat)

Once a custom vat has been started, it can be used as usual:

> (define alice
    (with-vat custom-vat
     (spawn ^greeter "Alice")))