flux_future_t *flux_kvs_commit (flux_t *h, const char *ns, int flags, flux_kvs_txn_t *txn);
flux_future_t *flux_kvs_fence (flux_t *h, const char *ns, int flags, const char *name, int nprocs, flux_kvs_txn_t *txn);
int flux_kvs_commit_get_treeobj (flux_future_t *f, const char **treeobj);
int flux_kvs_commit_get_sequence (flux_future_t *f, int *seq);
flux_kvs_commit() sends a request via handle h to the KVS service
to commit a transaction txn. txn is created with
flux_kvs_txn_create(3) and after commit completion, is destroyed
flux_future_t object is returned,
which acts as handle for synchronization and container for the
response. The txn will operate in the namespace specified by ns.
If ns is NULL,
flux_kvs_commit() will operate on the default
namespace, or if set, the namespace from the FLUX_KVS_NAMESPACE
environment variable. Note that all transactions operate on the same
flux_kvs_fence() is a "collective" version of
supports multiple callers. Each caller uses the same flags, name,
and nprocs arguments. Once nprocs requests are received by the KVS
service for the named operation, the transactions are combined and committed
together as one transaction. name must be unique across the Flux session
and should not be reused, even after the fence is complete.
flux_future_then(3) may be used to register a reactor callback
(continuation) to be called once the response to the commit/fence
request has been received.
flux_future_wait_for(3) may be used to
block until the response has been received. Both accept an optional timeout.
flux_kvs_commit_get_sequence() can decode the response. A return of
0 indicates success and the entire transaction was committed. A
return of -1 indicates failure, none of the transaction was committed.
All can be used on the
flux_future_t returned by
In addition to checking for success or failure,
can return information about the root snapshot that the commit or
fence has completed its transaction on.
flux_kvs_commit_get_treeobj() obtains the root hash in the form of
an RFC 11 dirref treeobj, suitable to be passed to
flux_kvs_commit_get_sequence() retrieves the monotonic sequence number
for the root.
The following are valid bits in a flags mask passed as an argument
- The KVS service may merge contemporaneous commit transactions as an optimization. However, if the combined transactions modify the same key, a watch on that key may only be notified of the last-in value. This flag can be used to disable that optimization for this transaction.
flux_kvs_fence() return a
success, or NULL on failure with errno set appropriately.
- One of the arguments was invalid.
- Out of memory.
- A request was malformed.
- The KVS module is not loaded.
- An unknown namespace was requested.
flux_kvs_fence()has been called too many times and nprocs has been exceeded.
flux_future_get(3), flux_kvs_txn_create(3), flux_kvs_set_namespace(3)