Title: | Isolate Functions for Remote Execution |
---|---|
Description: | Sending functions to remote processes can be wasteful of resources because they carry their environments with them. With the carrier package, it is easy to create functions that are isolated from their environment. These isolated functions, also called crates, print at the console with their total size and can be easily tested locally before being sent to a remote. |
Authors: | Lionel Henry [aut, cre], Posit Software, PBC [cph, fnd] |
Maintainer: | Lionel Henry <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.1.1.9000 |
Built: | 2024-12-26 04:57:56 UTC |
Source: | https://github.com/r-lib/carrier |
crate()
creates functions in a self-contained environment
(technically, a child of the base environment). This has two
advantages:
They can easily be executed in another process.
Their effects are reproducible. You can run them locally with the same results as on a different process.
Creating self-contained functions requires some care, see section below.
crate(.fn, ...)
crate(.fn, ...)
.fn |
A fresh formula or function. "Fresh" here means that
they should be declared in the call to |
... |
Arguments to declare in the environment of |
They should call package functions with an explicit ::
namespace. This includes packages in the default search path with
the exception of the base package. For instance var()
from the
stats package must be called with its namespace prefix:
stats::var(x)
.
They should declare any data they depend on. You can declare data
by supplying additional arguments or by unquoting objects with !!
.
# You can create functions using the ordinary notation: crate(function(x) stats::var(x)) # Or the formula notation: crate(~ stats::var(.x)) # Declare data by supplying named arguments. You can test you have # declared all necessary data by calling your crated function: na_rm <- TRUE fn <- crate(~ stats::var(.x, na.rm = na_rm)) try(fn(1:10)) # For small data it is handy to unquote instead. Unquoting inlines # objects inside the function. This is less verbose if your # function depends on many small objects: fn <- crate(~ stats::var(.x, na.rm = !!na_rm)) fn(1:10) # One downside is that the individual sizes of unquoted objects # won't be shown in the crate printout: fn # The function or formula you pass to crate() should defined inside # the crate() call, i.e. you can't pass an already defined # function: fn <- function(x) toupper(x) try(crate(fn)) # If you really need to crate an existing function, you can # explicitly set its environment to the crate environment with the # set_env() function from rlang: crate(rlang::set_env(fn))
# You can create functions using the ordinary notation: crate(function(x) stats::var(x)) # Or the formula notation: crate(~ stats::var(.x)) # Declare data by supplying named arguments. You can test you have # declared all necessary data by calling your crated function: na_rm <- TRUE fn <- crate(~ stats::var(.x, na.rm = na_rm)) try(fn(1:10)) # For small data it is handy to unquote instead. Unquoting inlines # objects inside the function. This is less verbose if your # function depends on many small objects: fn <- crate(~ stats::var(.x, na.rm = !!na_rm)) fn(1:10) # One downside is that the individual sizes of unquoted objects # won't be shown in the crate printout: fn # The function or formula you pass to crate() should defined inside # the crate() call, i.e. you can't pass an already defined # function: fn <- function(x) toupper(x) try(crate(fn)) # If you really need to crate an existing function, you can # explicitly set its environment to the crate environment with the # set_env() function from rlang: crate(rlang::set_env(fn))
Is an object a crate?
is_crate(x)
is_crate(x)
x |
An object to test. |