---

5.1.3 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.

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 the result of vow if it is fulfilled.
• catch: Procedure invoked on an error; passed one argument, the exception object.
• finally: Procedure invoked on success or failure after the appropriate 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 broken and catch is not provided, the promise returned will share vow’s broken result.
• 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 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

You can also wait for the resolution of a promise without necessarily responding:

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

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