---

5.1.4 Asynchronous calls

Making asynchronous calls

Procedure: <- to-refr args … ¶

Like $, but to-refr may be near or far, and <- returns a promise instead of a result.

(define object-a (spawn ^some-object))
;; in a different vat... or the same; it doesn't matter to <-
(define a-promise (<- object-a arg1))
(define b-promise (<- object-a 'some-method arg2))

<- has a variant that does not return a promise:

Procedure: <-np to-refr args … ¶

Like <-, but return void instead of a promise.

(define object-a (spawn ^some-object))
;; in a different vat... or the same; it doesn't matter to <-np
(<-np object-a arg1)                ; returns void
(<-np object-a 'some-method arg2)   ; returns void

Procedure: <-np-extern to-refr args … ¶

Like <-np, but only operate on far objects.

This procedure can be used outside of a vat.

Handling asynchronous values

Goblins provides two primary tools for resolving and operating on promise values, on and listen-to. Neither pauses program execution, so code following their invocation is conceptually concurrent with their various handlers. These handlers therefore constitute the asynchronous logic of most Goblins programs.

Procedure: on vow [fulfilled-handler #f] [#:catch #f] [#:finally #f] [#:promise? #f] ¶

Respond to a promise, optionally with error handling. Return nothing unless promise? is #t, in which case return a promise.

• vow: Promise to which to respond.
• fulfilled-handler: Procedure called with one argument on success, the result of fulfilling vow.
• catch: Procedure called with one argument on failure, the exception object explaining why vow broke.
• finally: Procedure unconditionally called last with one argument, the result of either the fulfilled-handler or the catch handler.

As mentioned above, if #:promise? is #t, then on will itself return a promise. This promise is resolved as follows:

• If vow is fulfilled and fulfilled-handler is not provided, the promise returned will share vow’s resolution.
• If vow is fulfilled and fulfilled-handler is provided, the resolution will be whatever is returned from fulfilled-handler, unless fulfilled-handler raises an error, in which case the promise will be broken with its error-value set to this exception.
• If vow is broken and catch is not provided, the promise returned will share vow’s broken result.
• If vow is broken and catch is provided, the resolution will be whatever is returned from catch, unless catch raises an error, in which case the promise will be broken with its error-value set to this exception (which may even be the original exception).

;; in the context of some vat
(define object-a (spawn ^some-object))
;; in the context of some vat, possibly different
(on (<- object-a arg1)
    (lambda (val)
      (some-proc val))
    #:catch
    (lambda (err)
      (handle-err err))
    #:finally
    (lambda _
      (other-proc))
    #:promise? #f)      ; the default, written out for demonstration

Goblins also exposes a more primitive interface to listen for promise resolution, mostly useful if you don’t need to know the value a resolved promise and just want to know that it has resolved:

Procedure: listen-to to-refr listener [#:wants-partial? #f] ¶

Wait for to-refr, a promise, to resolve, then call listener with its value. If wants-partial? is #t, return updates rather than waiting for full promise resolution.

The value passed to listener is a list of the form ('fulfill val) on success, where val is the result of resolving to-refr; or of the form ('break problem) on failure, where problem is the cause of a failed computation.