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