Promise domains are used to temporarily set up custom environments that
intercept and influence the registration of callbacks. Create new promise
domain objects using new_promise_domain
, and temporarily activate a promise
domain object (for the duration of evaluating a given expression) using
with_promise_domain
.
with_promise_domain(domain, expr, replace = FALSE)new_promise_domain(
wrapOnFulfilled = identity,
wrapOnRejected = identity,
wrapSync = force,
onError = force,
...,
wrapOnFinally = NULL
)
A promise domain object to install while expr
is evaluated.
Any R expression, to be evaluated under the influence of
domain
.
If FALSE
, then the effect of the domain
will be added
to the effect of any currently active promise domain(s). If TRUE
, then
the current promise domain(s) will be ignored for the duration of the
with_promise_domain
call.
A function that takes a single argument: a function
that was passed as an onFulfilled
argument to then()
. The
wrapOnFulfilled
function should return a function that is suitable for
onFulfilled
duty.
A function that takes a single argument: a function
that was passed as an onRejected
argument to then()
. The
wrapOnRejected
function should return a function that is suitable for
onRejected
duty.
A function that takes a single argument: a (lazily evaluated)
expression that the function should force()
. This expression represents
the expr
argument passed to with_promise_domain()
; wrapSync
allows
the domain to manipulate the environment before/after expr
is evaluated.
A function that takes a single argument: an error. onError
will be called whenever an exception occurs in a domain (that isn't caught
by a tryCatch
). Providing an onError
callback doesn't cause errors to
be caught, necessarily; instead, onError
callbacks behave like calling
handlers.
Arbitrary named values that will become elements of the promise
domain object, and can be accessed as items in an environment (i.e. using
[[
or $
).
A function that takes a single argument: a function
that was passed as an onFinally
argument to then()
. The
wrapOnFinally
function should return a function that is suitable for
onFinally
duty. If wrapOnFinally
is NULL
(the default), then the
domain will use both wrapOnFulfilled
and wrapOnRejected
to wrap the
onFinally
. If it's important to distinguish between normal
fulfillment/rejection handlers and finally handlers, then be sure to
provide wrapOnFinally
, even if it's just base::identity()
.
While with_promise_domain
is on the call stack, any calls to then()
(or
higher level functions or operators, like catch()
or the various pipes)
will belong to the promise domain. In addition, when a then
callback that
belongs to a promise domain is invoked, then any new calls to then
will
also belong to that promise domain. In other words, a promise domain
"infects" not only the immediate calls to then
, but also to "nested" calls
to then
.
For more background, read the original design doc.
For examples, see the source code of the Shiny package, which uses promise domains extensively to manage graphics devices and reactivity.