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);
int flux_kvs_commit_get_treeobj (flux_future_t *f,
const char **treeobj);
int flux_kvs_commit_get_rootref (flux_future_t *f,
const char **rootref);
int flux_kvs_commit_get_sequence (flux_future_t *f, int *seq);
Link with -lflux-core.
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_future_then(3) may be used to register a reactor callback (continuation) to be called once the response to the commit 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()
,
flux_kvs_commit_get_rootref()
, 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.
In addition to checking for success or failure,
flux_kvs_commit_get_treeobj()
, flux_kvs_commit_get_rootref()
,
and flux_kvs_commit_get_sequence()
can return information about the
root snapshot that the commit 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_rootref()
retrieves the blobref for the root.
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()
.
- 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()
returns 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.
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc
Issue Tracker: https://github.com/flux-framework/flux-core/issues