From 0bca42c9be0fdeed393fe17e9cb2bd549c1b7271 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Thu, 3 May 2018 10:10:08 -0400 Subject: [PATCH] doc/flux_future_get(3): add flux_future_reset() Add a description for flux_future_reset() to the flux_future_get(3) man page. --- doc/man3/Makefile.am | 2 ++ doc/man3/flux_future_get.adoc | 25 +++++++++++++++++-------- doc/test/spell.en.pws | 1 + 3 files changed, 20 insertions(+), 8 deletions(-) diff --git a/doc/man3/Makefile.am b/doc/man3/Makefile.am index 45aa87a468ea..4dc3598506b3 100644 --- a/doc/man3/Makefile.am +++ b/doc/man3/Makefile.am @@ -116,6 +116,7 @@ MAN3_FILES_SECONDARY = \ flux_log_set_appname.3 \ flux_log_set_procid.3 \ flux_future_wait_for.3 \ + flux_future_reset.3 \ flux_future_destroy.3 \ flux_future_get.3 \ flux_future_fulfill.3 \ @@ -238,6 +239,7 @@ flux_content_store_get.3: flux_content_load.3 flux_vlog.3: flux_log.3 flux_log_set_appname.3: flux_log.3 flux_log_set_procid.3: flux_log.3 +flux_future_reset.3: flux_future_get.3 flux_future_destroy.3: flux_future_get.3 flux_future_wait_for.3: flux_future_get.3 flux_future_then.3: flux_future_get.3 diff --git a/doc/man3/flux_future_get.adoc b/doc/man3/flux_future_get.adoc index 40562cdacfe9..1f7e539885ba 100644 --- a/doc/man3/flux_future_get.adoc +++ b/doc/man3/flux_future_get.adoc @@ -5,7 +5,7 @@ flux_future_get(3) NAME ---- -flux_future_get, flux_future_then, flux_future_wait_for, flux_future_destroy - synchronize an activity +flux_future_get, flux_future_then, flux_future_wait_for, flux_future_reset, flux_future_destroy - synchronize an activity SYNOPSIS @@ -21,6 +21,8 @@ SYNOPSIS int flux_future_wait_for (flux_future_t *f, double timeout); + void flux_future_reset (flux_future_t *f); + void flux_future_destroy (flux_future_t *f); @@ -58,13 +60,13 @@ derived from that). The continuation will normally use `flux_future_get()` or a class-specific access function to obtain the result from the future container without -blocking. `flux_future_then()` may only be called once on a given future. -It is not an error to set up a continuation on a future that has already -been fulfilled. If _timeout_ is non-negative, the future must be fulfilled -within the specified amount of time or the timeout fulfills it with an error -(errno set to ETIMEDOUT). The reactor must be run or re-entered in order -for the timer and the future activity to make progress. It is safe to -destroy the future from within the continuation callback. +blocking. The continuation may call `flux_future_destroy()` or +`flux_future_reset()`. It is not an error to set up a continuation on +a future that has already been fulfilled. If _timeout_ is non-negative, +the future must be fulfilled within the specified amount of time or the +timeout fulfills it with an error (errno set to ETIMEDOUT). The reactor +must be run or re-entered in order for the timer and the future activity +to make progress. `flux_future_wait_for()` blocks until the future is fulfilled, or _timeout_ (if non-negative) expires. This function may be called multiple times, @@ -76,6 +78,13 @@ is zero, in which case the function times out immediately if the future has not already been fulfilled. While `flux_future_wait_for()` is executing, unrelated reactor watchers and message handlers are not active. +`flux_future_reset()` unfulfills a future, invalidating any result stored +in the container, and preparing it to be fulfilled once again. If a +continuation was registered, it remains in effect for the next fulfillment, +however any timeout will have been cleared by the current fulfillment +and must be re-established by following the `flux_future_reset()` with +another `flux_future_then()`, if desired. + `flux_future_destroy()` destroys a future, including any result contained within. diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws index 6fce3a043c0f..c93f787cb465 100644 --- a/doc/test/spell.en.pws +++ b/doc/test/spell.en.pws @@ -422,3 +422,4 @@ resizing HOSTLIST hostlist hostnames +unfulfills