5.1.3 Asynchronous invocation

(<- near-object arg ...)
;=> <local-promise>

Like $, but called asynchronously and returns a promise, which may be handled with on. Unlike $, <- is not limited to only near objects; interaction with far actors are permitted as well.

(<-np [actor-refr live-refr?] [arg any/c] ...)

Like <- but does not return (or require the overhead of) a promise. <-np is effectively an optimization; where promises are not needed, using <-np over <- is a good idea.

(on vow
    [fulfilled-handler]
    [#:catch broken-handler]
    [#:finally finally-handler]
    [#:promise? #f])

Sets up promise handlers for vow, which is typically a live-refr? to a promise but may be anything.

fulfilled-handler, broken-handler, and finally-handler all, if specified, may be either a procedure (the most common case) which is run when vow becomes resolved, or a reference to an actor that should be messaged when the promise is resolved with the same arguments that would be passed to an equivalent procedure. As their names suggest, fulfilled-handler will run if a promise is fulfilled and takes one argument, the fulfilled value. broken-handler will run if a promise is broken and takes one argument, the error value. finally-handler will run when a promise is resolved, no matter the outcome and is called with no arguments.

If #:promise? is set to #t, then on will itself return a promise. The promise will be 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 broken-handler 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 broken-handler is provided, the resolution will be whatever is returned from broken-handler, unless broken-handler 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).