flux_kvs_commit(3)¶
SYNOPSIS¶
#include <flux/core.h>
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);
DESCRIPTION¶
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
with flux_kvs_txn_destroy(3). A 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
namespace.
flux_kvs_fence() is a "collective" version of flux_kvs_commit() that
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_future_get(3), flux_kvs_commit_get_treeobj(), or
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 flux_kvs_commit()
or flux_kvs_fence().
In addition to checking for success or failure,
flux_kvs_commit_get_treeobj() and flux_kvs_commit_get_sequence()
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_lookupat(3).
flux_kvs_commit_get_sequence() retrieves the monotonic sequence number
for the root.
FLAGS¶
The following are valid bits in a flags mask passed as an argument
to flux_kvs_commit() or flux_kvs_fence().
- FLUX_KVS_NO_MERGE
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.
RETURN VALUE¶
flux_kvs_commit() and flux_kvs_fence() return a flux_future_t on
success, or NULL on failure with errno set appropriately.
ERRORS¶
- EINVAL
One of the arguments was invalid.
- ENOMEM
Out of memory.
- EPROTO
A request was malformed.
- ENOSYS
The KVS module is not loaded.
- ENOTSUP
An unknown namespace was requested.
- EOVERFLOW
flux_kvs_fence()has been called too many times and nprocs has been exceeded.