flux_future_t *flux_future_and_then (flux_future_t *f, flux_continuation_f cb, void *arg); flux_future_t *flux_future_or_then (flux_future_t *f, flux_continuation_f cb, void *arg);
int flux_future_continue (flux_future_t *prev, flux_future_t *f); void flux_future_continue_error (flux_future_t *prev, int errnum, const char *errstr);
int flux_future_fulfill_next (flux_future_t *f, void *result, flux_free_f free_fn);
flux_future_get(3) for general functions that operate on futures,
flux_future_create(3) for a description of the
base type. This page covers functions for the sequential composition of
futures, i.e. chains of dependent futures.
flux_future_and_then(3) is similar to
returns a future that may later be "continued" from the continuation
cb. The provided continuation callback
cb is only
executed when the future argument
f is fulfilled successfully. On
error, the error from
f is automatically propagated to the "next"
future in the chain (returned by the function).
flux_future_and_then() is useful when a series of asynchronous
operations, each returning a
flux_future_t, depend on the result
of a previous operation. That is,
flux_future_and_then() returns a
placeholder future for an eventual future that can't be created until
cb is run. The returned future can then be
used as a synchronization handle or even passed to another
flux_future_and_then() in the chain. By default, the next future
in the chain will be fulfilled immediately using the result of the
previous future after return from the callback
cb. Most callbacks,
however, should use either
flux_future_continue_error(3) to pass an intermediate future
to use in fulfillment of the next future in the chain.
flux_future_or_then(3) is like
the continuation callback
cb is run when the future
f is fulfilled
with an error. This function is useful for recovery or other error
handling (other than the default behavior of propagating an error
down the chain to the final result). The
callback offers a chance to successfully fulfill the "next" future
in the chain, even when the "previous" future was fulfilled with
flux_future_and_then() the continuation
cb function for
flux_future_or_then() should call
the result of the previous future will be propagated immediately
to the next future in the chain.
flux_future_continue(3) continues the next future embedded in
the eventual result of the provided future
f. This allows a future
that was not created until the context of the callback to continue
a sequential chain of futures created earlier. After the call to
flux_future_continue(3) completes, the future
prev may safely be
flux_future_continue(3) may be called with
NULL if the caller desires the next future in the chain to
not be fulfilled, in order to disable the automatic fulfillment
that normally occurs for non-continued futures after the callback
flux_future_continue_error(3) is like
but immediately fulfills the next future in the chain with an error and
an optional error string. Once
completes, the future
prev may safely be destroyed.
flux_future_fulfill_next(3) is like
fulfills the next future in the chain instead of the current future (which
is presumably already fulfilled). This call is useful when a chained future
is being used for post-processing a result from intermediate future-based
calls, as it allows the next future to be fulfilled with a custom result,
instead of with the value of another future as in
flux_future_or_then() return a
on success, or NULL on error. If both functions are called on the same
future, the returned
flux_future_t from each will be the same object.
flux_future_continue() returns 0 on success, or -1 on error with errno
flux_future_fulfill_next() returns 0 on success, or -1 with errno set
EINVAL if the target future does not have a next future to fulfill.
- Out of memory.
- Invalid argument.
- The requested object is not found.