EVOLUTION-MANAGER
Edit File: with_promise_domain.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Promise domains</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for with_promise_domain {promises}"><tr><td>with_promise_domain {promises}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Promise domains</h2> <h3>Description</h3> <p>Promise domains are used to temporarily set up custom environments that intercept and influence the registration of callbacks. Create new promise domain objects using <code>new_promise_domain</code>, and temporarily activate a promise domain object (for the duration of evaluating a given expression) using <code>with_promise_domain</code>. </p> <h3>Usage</h3> <pre> with_promise_domain(domain, expr, replace = FALSE) new_promise_domain( wrapOnFulfilled = identity, wrapOnRejected = identity, wrapSync = force, onError = force, ..., wrapOnFinally = NULL ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>domain</code></td> <td> <p>A promise domain object to install while <code>expr</code> is evaluated.</p> </td></tr> <tr valign="top"><td><code>expr</code></td> <td> <p>Any R expression, to be evaluated under the influence of <code>domain</code>.</p> </td></tr> <tr valign="top"><td><code>replace</code></td> <td> <p>If <code>FALSE</code>, then the effect of the <code>domain</code> will be added to the effect of any currently active promise domain(s). If <code>TRUE</code>, then the current promise domain(s) will be ignored for the duration of the <code>with_promise_domain</code> call.</p> </td></tr> <tr valign="top"><td><code>wrapOnFulfilled</code></td> <td> <p>A function that takes a single argument: a function that was passed as an <code>onFulfilled</code> argument to <code><a href="then.html">then()</a></code>. The <code>wrapOnFulfilled</code> function should return a function that is suitable for <code>onFulfilled</code> duty.</p> </td></tr> <tr valign="top"><td><code>wrapOnRejected</code></td> <td> <p>A function that takes a single argument: a function that was passed as an <code>onRejected</code> argument to <code><a href="then.html">then()</a></code>. The <code>wrapOnRejected</code> function should return a function that is suitable for <code>onRejected</code> duty.</p> </td></tr> <tr valign="top"><td><code>wrapSync</code></td> <td> <p>A function that takes a single argument: a (lazily evaluated) expression that the function should <code><a href="../../base/html/force.html">force()</a></code>. This expression represents the <code>expr</code> argument passed to <code><a href="with_promise_domain.html">with_promise_domain()</a></code>; <code>wrapSync</code> allows the domain to manipulate the environment before/after <code>expr</code> is evaluated.</p> </td></tr> <tr valign="top"><td><code>onError</code></td> <td> <p>A function that takes a single argument: an error. <code>onError</code> will be called whenever an exception occurs in a domain (that isn't caught by a <code>tryCatch</code>). Providing an <code>onError</code> callback doesn't cause errors to be caught, necessarily; instead, <code>onError</code> callbacks behave like calling handlers.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>Arbitrary named values that will become elements of the promise domain object, and can be accessed as items in an environment (i.e. using <code>[[</code> or <code>$</code>).</p> </td></tr> <tr valign="top"><td><code>wrapOnFinally</code></td> <td> <p>A function that takes a single argument: a function that was passed as an <code>onFinally</code> argument to <code><a href="then.html">then()</a></code>. The <code>wrapOnFinally</code> function should return a function that is suitable for <code>onFinally</code> duty. If <code>wrapOnFinally</code> is <code>NULL</code> (the default), then the domain will use both <code>wrapOnFulfilled</code> and <code>wrapOnRejected</code> to wrap the <code>onFinally</code>. If it's important to distinguish between normal fulfillment/rejection handlers and finally handlers, then be sure to provide <code>wrapOnFinally</code>, even if it's just <code><a href="../../base/html/identity.html">base::identity()</a></code>.</p> </td></tr> </table> <h3>Details</h3> <p>While <code>with_promise_domain</code> is on the call stack, any calls to <code><a href="then.html">then()</a></code> (or higher level functions or operators, like <code><a href="then.html">catch()</a></code> or the various <a href="pipes.html">pipes</a>) will belong to the promise domain. In addition, when a <code>then</code> callback that belongs to a promise domain is invoked, then any new calls to <code>then</code> will also belong to that promise domain. In other words, a promise domain "infects" not only the immediate calls to <code>then</code>, but also to "nested" calls to <code>then</code>. </p> <p>For more background, read the <a href="https://gist.github.com/jcheng5/b1c87bb416f6153643cd0470ac756231">original design doc</a>. </p> <p>For examples, see the source code of the Shiny package, which uses promise domains extensively to manage graphics devices and reactivity. </p> <hr /><div style="text-align: center;">[Package <em>promises</em> version 1.1.1 <a href="00Index.html">Index</a>]</div> </body></html>