mizu_collect_all_async() and mizu_collect_any_async() are the async
counterparts of mizu_collect_all() and mizu_collect_any(). Each returns
immediately with one promises::promise() for the whole collection, and no
per-task promise is allocated. On each wake the pool checks for newly
finished tasks, and when the collection completes, the result is assembled
once as in the blocking version and the promise resolves.
Usage
mizu_collect_all_async(tasks, timeout = Inf)
mizu_collect_any_async(tasks, timeout = Inf)
mizu_collect_async(task, timeout = Inf)
# S3 method for class 'mizu_task'
as.promise(x)
# S3 method for class 'mizu_task'
is.promising(x)
# S3 method for class 'mizu_map'
as.promise(x)
# S3 method for class 'mizu_map'
is.promising(x)Arguments
- tasks
a non-empty list of task handles from
mizu_submit()on the same pool handle.- timeout
seconds after which the promise rejects with the
mizu_timeoutclassed error; nothing is consumed.Inf(the default) waits indefinitely.- task
a task handle from
mizu_submit().- x
for the
as.promisemethods: a task handle, or a map handle frommizu_map()/mizu_map_run().
Value
A promises::promise(): mizu_collect_async() resolves the
task's value; collect-all resolves a plain list of the task values
in the order of tasks (names carried); collect-any resolves
list(index, value).
Details
mizu_collect_async() is the single-task form, the async counterpart of
mizu_collect(). It returns immediately with a promises::promise() that
resolves with the task's value and rejects with the same classed condition a
blocking collect would raise. There is one promise per task. While the task
is pending the promise is cached, so a repeated call, or as.promise() on
the handle (which promises::then() calls), returns the same promise, and
timeout applies only to the call that created it. Once settled the task is
collected, and a further call errors (one consumer per result, below). A
timeout rejects with the mizu_timeout classed error and consumes nothing,
so the task can be collected with a blocking call again.
The behavior mirrors the blocking functions. Collect-all resolves in input
order with names carried over, and the first erroring handle by position
rejects with index (only that handle is consumed, the rest stay
collectible). Collect-any resolves list(index, value) for the first
terminal task, and a raised outcome rejects with the index field. A timeout
rejects with the mizu_timeout classed error and consumes nothing. When a
collection finishes, whether resolved, rejected, or timed out, every handle
in it is released, and handles whose results were not consumed can be
collected with a blocking call again.
A task result belongs to exactly one consumer. A task with a promise
attached, or one that is part of a pending collection, refuses
mizu_collect(), mizu_collect_any() and mizu_collect_all() with an error
naming the pending consumer, and a task enrolled in a collection likewise
refuses a promise. mizu_cancel() is still allowed and is the destructive
option: the cancel publishes, the result is gone for every consumer, and the
pending promise rejects with mizu_error_cancelled. A timeout is the
non-destructive counterpart. It only detaches the promise, and the task keeps
running with its result still collectible. (A channel message instead belongs
to whoever takes it first; see mizu_recv_async().)
Requires the later and promises packages.
Examples
if (FALSE) { # interactive() && requireNamespace("promises", quietly = TRUE)
library(promises)
p <- mizu_pool(2L)
t <- mizu_submit(p, sum(runif(10)))
mizu_collect_async(t, timeout = 5) %...>% print()
ts <- list(
total = mizu_submit(p, sum(x), x = runif(10)),
label = mizu_submit(p, "done")
)
mizu_collect_all_async(ts) %...>% print()
later::run_now()
mizu_pool_stop(p)
}