mizu_default_pool() returns the pool registered as this process's default,
or NULL when none is set. mizu_set_default_pool() sets the default (or
clears it with NULL) and invisibly returns the previous one, so callers can
save and restore it. mizu_with_pool() evaluates expr with pool as the
default and restores the previous default on exit, including on error.
mizu_local_pool() sets the default until the calling frame exits (the withr
local_* pattern).
Usage
mizu_default_pool()
mizu_set_default_pool(pool)
mizu_with_pool(pool, expr)
mizu_local_pool(pool, frame = parent.frame())Arguments
- pool
a pool handle from
mizu_pool()ormizu_pool_attach(), orNULLto clear the default.- expr
an expression to evaluate with
poolas the default.- frame
the frame at whose exit the previous default is restored; defaults to the caller of
mizu_local_pool().
Value
mizu_default_pool(): the default pool handle, or NULL.
mizu_set_default_pool() and mizu_local_pool(): the previous
default (a pool handle or NULL), invisibly. mizu_with_pool(): the
value of expr.
Details
The default keeps the pool alive even after its variable is removed,
until the default is cleared or replaced. Handles from
mizu_pool_attach() are valid defaults; ownership and teardown stay
with the pool's creator.
Setting a default checks only the type. A stopped pool is accepted (liveness
is transient, so a probe would prove nothing about use time) and fails later
with the usual stopped-pool errors. The default is process-global state, and
a child process created by fork() reads it as unset.
Package authors
A function that takes an optional pool resolves it in this order: an explicit
pool argument, then mizu_current_pool() inside a task (the evaluating
worker's own pool, for nested submission), then mizu_default_pool(), then
the caller's own fallback, such as sequential evaluation or an error.
mizu_current_pool() is set by the pool around each task evaluation and
cannot be shadowed. The default pool is user-set state and never overrides
it.
Examples
p <- mizu_pool()
old <- mizu_set_default_pool(p)
# the package-author resolution idiom
f <- function(x, pool = mizu_default_pool()) {
if (is.null(pool)) {
stop("no pool: pass one, or set a default", call. = FALSE)
}
mizu_collect(mizu_submit(pool, x + 1L, x = x))
}
f(1L)
#> [1] 2
# scoped use: the previous default returns on exit
mizu_with_pool(NULL, mizu_default_pool())
#> NULL
mizu_default_pool()
#> <mizu_pool /mizu_9883_75e7ded4: controller, 1/1 workers live, 0 pending>
mizu_set_default_pool(old)
mizu_pool_stop(p)