| Title: | Contexts for evaluating R expressions |
|---|---|
| Description: | Contexts for evaluating R expressions. |
| Authors: | Rich FitzJohn [aut, cre], Imperial College of Science, Technology and Medicine [cph] |
| Maintainer: | Rich FitzJohn <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.5.0 |
| Built: | 2024-09-17 03:11:05 UTC |
| Source: | https://github.com/mrc-ide/context |
Prepare many expressions
bulk_prepare_expression(X, FUN, DOTS, do_call, use_names, envir, db)bulk_prepare_expression(X, FUN, DOTS, do_call, use_names, envir, db)
X |
Something to iterate over; a vector, list or data.frame (in the case of a data.frame, iteration will be row-by-row) |
FUN |
A function to apply to each element (or row) of
|
DOTS |
Additional arguments to apply with each elements of
|
do_call |
Treat each element of |
use_names |
When preparing a data.frame, retain column names
as argument names when using |
envir |
An environment to find variables local to the expression |
db |
A database to store locals |
Save bulk tasks
bulk_task_save( X, FUN, context, DOTS = NULL, do_call = FALSE, use_names = TRUE, envir = parent.frame(), depends_on = NULL )bulk_task_save( X, FUN, context, DOTS = NULL, do_call = FALSE, use_names = TRUE, envir = parent.frame(), depends_on = NULL )
X |
Something to iterate over; a vector, list or data.frame (in the case of a data.frame, iteration will be row-by-row) |
FUN |
A function to apply to each element (or row) of
|
context |
A context |
DOTS |
Additional arguments to apply with each elements of
|
do_call |
Treat each element of |
use_names |
When preparing a data.frame, retain column names
as argument names when using |
envir |
An environment to find variables local to the expression |
depends_on |
Optional task ids that this task depends on. To have all tasks depend on the same id(s) provide a vector. TO provide different dependencies for each task provide a list of lists. For example list(list("abcde", "12345"), list(), list("12345")) |
List saved contexts
context_list(db, named = FALSE, error = TRUE) context_info(db, error = TRUE)context_list(db, named = FALSE, error = TRUE) context_info(db, error = TRUE)
db |
Something for which a context database can be created;
this can the the path to the context, a |
named |
Logical, indicating if the context name should be used to name the output vector. |
error |
Throw an error if the context database cannot be connected constructed (e.g., if the path given does not exist). |
Rich FitzJohn
Load a context
context_load(ctx, envir = .GlobalEnv, refresh = FALSE)context_load(ctx, envir = .GlobalEnv, refresh = FALSE)
ctx |
A context object, as read by |
envir |
The environment to source files into |
refresh |
Refresh the context, even when it has been loaded already? Note that this may not always behave as expected because items not created by sourcing an R file will still be there from previous runs, and packages loaded will not be reloaded in a new order. |
Send an entry to the context log. This is designed primarily for use with packages that build off of context, so that they can log in a consistent way.
context_log(topic, value)context_log(topic, value)
topic |
Up to 9 character text string with the log topic |
value |
Character string with the log entry |
Read a context
context_read(identifier, root, db = NULL)context_read(identifier, root, db = NULL)
identifier |
Either the id or name of a context (see
|
root |
Something interpretable as the context root; either |
db |
Optionally, a database (if known already) |
Find the context root. Designed for internal use
context_root_get(root, db = NULL)context_root_get(root, db = NULL)
root |
An object; either a character string (interpreted as a
path), a |
db |
Optionally, a copy of the storr database (if already opened). Do not specify this unless you definitely have the correct database in hand. |
Save a context
context_save( path, packages = NULL, sources = NULL, package_sources = NULL, envir = NULL, storage_type = NULL, storage_args = NULL, name = NULL, root_id = NULL )context_save( path, packages = NULL, sources = NULL, package_sources = NULL, envir = NULL, storage_type = NULL, storage_args = NULL, name = NULL, root_id = NULL )
path |
Path to save the context in |
packages |
Optional character vector of packages to save into
the context. Alternatively, can be a list with elements
|
sources |
Character vector of source files to read in. These should define functions and (perhaps) other "global" objects, but should not do any serious computation. |
package_sources |
Optional information about where to find
non-CRAN packages, created by |
envir |
The current environment. This is used to copy
local variables around. For |
storage_type |
Character vector indicating the storage type
to use. Options are |
storage_args |
Arguments passed through to the storage driver |
name |
An optional name for the context. This will be
printed with the context in some situations (such as
|
root_id |
Force a context root id. This is intended for
advanced use only. By setting the root id, two contexts
created with storage in different file locations ( |
Return the last loaded context
last_loaded_context(error = TRUE)last_loaded_context(error = TRUE)
error |
Throw an error if no context has been loaded |
Start a sub-cluster, using the parallel package. This will
be available via either the return value of this function, the
parallel_cluster function or by using cl = NULL with
any of the parallel package functions. The cluster will be
started so that it is ready to use the context.
parallel_cluster_start(n, ctx) parallel_cluster_stop() parallel_cluster()parallel_cluster_start(n, ctx) parallel_cluster_stop() parallel_cluster()
n |
The number of nodes. No attempt at guessing this number is made as that is terribly error prone. If you're using this function you should know how many resources you have available. |
ctx |
The context to initialise on each cluster node. |
Prepare expression for evaluation in context
prepare_expression(expr, envir, db, function_value = NULL)prepare_expression(expr, envir, db, function_value = NULL)
expr |
A quoted expression consisting of a single function call. |
envir |
An environment to find variables local to the expression |
db |
A database to store locals |
function_value |
Optionally, the value of a function
where the expression should involve an anonymous function. In
this case the function in |
The function_value argument here is used where expr is
going to take a function that is not addressable by name; in
that case we take a function itself (as "function_value"),
serialise it and replace the function call with the hash. The
function will be serialised into the calling environment on
deserialisation.
This includes the remote possibility of a collision, but with the size of the keyspace used for hashes hopefully it's negligible.
Because of the approach used here, expr can contain
anything; I'd suggest not saving the contents of the function
itself, but something like NULL will work just fine:
as.call(list(NULL, quote(a))) # NULL(a)
Restore locals created by prepare_expression.
restore_locals(dat, parent, db)restore_locals(dat, parent, db)
dat |
An expression that has been through
|
parent |
The parent environment to restore locals to |
db |
The database used to prepare the expression |
Find the context id associated with a task
task_context_id(ids, db)task_context_id(ids, db)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
Delete a task, including its results.
task_delete(ids, root)task_delete(ids, root)
ids |
Vector of task ids |
root |
A context root (not just the db as in
|
TRUE if a task was actually deleted.
Task dependencies
task_deps(ids, db, named = FALSE)task_deps(ids, db, named = FALSE)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
named |
Name the output with the task ids? |
List tasks and test if they exist
task_exists(ids, db) task_list(db)task_exists(ids, db) task_list(db)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
Fetch expression for a task
task_expr(id, db, locals = FALSE)task_expr(id, db, locals = FALSE)
id |
Single task identifier |
db |
Something that can be converted to a context db object (a database, root or context). |
locals |
Return locals bound to the expression (as an attribute "locals") |
Fetch function name for a task
task_function_name(ids, db)task_function_name(ids, db)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
Return the log of a task, if enabled.
task_log(id, root, parse = TRUE)task_log(id, root, parse = TRUE)
id |
Single task identifier |
root |
A context root (not just the db as in
|
parse |
Parse the log output into a |
The returned object is of class task_log, which has a print
method that will nicely display. Output is grouped into phases.
Reset tasks
task_reset(id, context)task_reset(id, context)
id |
A vector of task identifiers |
context |
A context object |
Fetch result from completed task.
task_result(id, db, allow_incomplete = FALSE)task_result(id, db, allow_incomplete = FALSE)
id |
Single task identifier |
db |
Something that can be converted to a context db object (a database, root or context). |
allow_incomplete |
Should we avoid throwing an error if a task is not completed? Used internally, and not generally needed. |
Run a task
task_run(id, context, filename = NULL)task_run(id, context, filename = NULL)
id |
A task identifier |
context |
A context object |
filename |
Filename to log all output to. This will sink the message stream as well as the output stream, so if specified (i.e., is non-NULL) then this function will apparently print no output to the console, which will make debugging more difficult when run interactively. However, when run non-interactively, especially on remote servers, this will allow collection of diagnostics that facilitate debugging. |
Run a task in a separate process, using [callr::r]. Unlike [context::task_run] this does not return the value, and is called for the side effect of writing to the context.
task_run_external(root, identifier, task_id, path_log)task_run_external(root, identifier, task_id, path_log)
root |
Something interpretable as the context root; either |
identifier |
Either the id or name of a context (see
|
task_id |
A task identifier |
path_log |
Path to log file |
Save and reload tasks. Tasks consist of an expression bound to a
context.
task_save(expr, context, envir = parent.frame(), depends_on = NULL)task_save(expr, context, envir = parent.frame(), depends_on = NULL)
expr |
An expression to save |
context |
A |
envir |
Passed through to |
depends_on |
Optional vector of task ids that this task depends on |
An identifier that can be used to retrieve or run the task later. This is simply a short string.
Task status
task_status(ids, db, named = FALSE)task_status(ids, db, named = FALSE)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
named |
Name the output with the task ids? |
Fetch times taken to queue, run, and since running a task.
task_times(ids, db, unit_elapsed = "secs", sorted = TRUE)task_times(ids, db, unit_elapsed = "secs", sorted = TRUE)
ids |
Vector of task ids |
db |
Something that can be converted to a context db object (a database, root or context). |
unit_elapsed |
Elapsed time unit. The default is "secs".
This is passed to the |
sorted |
Sort the output in terms of submitted time? If
|
Rich FitzJohn