flux_kvs_txn_create(3)

SYNOPSIS

#include <flux/core.h>

flux_kvs_txn_t *flux_kvs_txn_create (void);

void flux_kvs_txn_destroy (flux_kvs_txn_t *txn);

int flux_kvs_txn_put (flux_kvs_txn_t *txn,
                      int flags,
                      const char *key,
                      const char *value);

int flux_kvs_txn_pack (flux_kvs_txn_t *txn,
                       int flags,
                       const char *key,
                       const char *fmt,
                       ...);

int flux_kvs_txn_vpack (flux_kvs_txn_t *txn,
                        int flags,
                        const char *key,
                        const char *fmt,
                        va_list ap);

int flux_kvs_txn_mkdir (flux_kvs_txn_t *txn,
                        int flags,
                        const char *key);

int flux_kvs_txn_unlink (flux_kvs_txn_t *txn,
                         int flags,
                         const char *key);

int flux_kvs_txn_symlink (flux_kvs_txn_t *txn,
                          int flags,
                          const char *key,
                          const char *ns,
                          const char *target);

int flux_kvs_txn_put_raw (flux_kvs_txn_t *txn,
                          int flags,
                          const char *key,
                          const void *data,
                          size_t len);

int flux_kvs_txn_put_treeobj (flux_kvs_txn_t *txn,
                              int flags,
                              const char *key,
                              const char *treeobj);

Link with -lflux-core.

DESCRIPTION

The Flux Key Value Store is a general purpose distributed storage service used by Flux services.

flux_kvs_txn_create() creates a KVS transaction object that may be passed to flux_kvs_commit(3) or flux_kvs_fence(3). The transaction consists of a list of operations that are applied to the KVS together, in order. The entire transaction either succeeds or fails. After commit or fence, the object must be destroyed with flux_kvs_txn_destroy().

Each function below adds a single operation to txn. key is a hierarchical path name with period (".") used as path separator. When the transaction is committed, any existing keys or path components that are in conflict with the requested operation are overwritten. flags can modify the request as described below.

flux_kvs_txn_put() sets key to a NULL terminated string value. value may be NULL indicating that an empty value should be stored.

flux_kvs_txn_pack() sets key to a NULL terminated string encoded from a JSON object built with json_pack() style arguments (see below). flux_kvs_txn_vpack() is a variant that accepts a va_list argument.

flux_kvs_txn_mkdir() sets key to an empty directory.

flux_kvs_txn_unlink() removes key. If key is a directory, all its contents are removed as well.

flux_kvs_txn_symlink() sets key to a symbolic link pointing to a namespace ns and a target key within that namespace. Neither ns nor target must exist. The namespace ns is optional, if set to NULL the target is assumed to be in the key's current namespace.

flux_kvs_txn_put_raw() sets key to a value containing raw data referred to by data of length len.

flux_kvs_txn_put_treeobj() sets key to an RFC 11 object, encoded as a JSON string.

FLAGS

The following are valid bits in a flags mask passed as an argument to flux_kvs_txn_put() or flux_kvs_txn_put_raw().

FLUX_KVS_APPEND: Append value instead of overwriting it. If the key does not exist, it will be created with the value as the initial value.

ENCODING JSON PAYLOADS

Flux API functions that are based on Jansson's json_pack() accept the following tokens in their format string. The type in parenthesis denotes the resulting JSON type, and the type in brackets (if any) denotes the C type that is expected as the corresponding argument or arguments.

s (string)['const char *']: Convert a null terminated UTF-8 string to a JSON string.
s? (string)['const char *']: Like s, but if the argument is NULL, outputs a JSON null value.
s# (string)['const char *', 'int']: Convert a UTF-8 buffer of a given length to a JSON string.
s% (string)['const char *', 'size_t']: Like s# but the length argument is of type size_t.
+ ['const char *']: Like s, but concatenate to the previous string. Only valid after a string.
+# ['const char *', 'int']: Like s#, but concatenate to the previous string. Only valid after a string.
+% ['const char *', 'size_t']: Like +#, but the length argument is of type size_t.
n (null): Output a JSON null value. No argument is consumed.
b (boolean)['int']: Convert a C int to JSON boolean value. Zero is converted to false and non-zero to true.
i (integer)['int']: Convert a C int to JSON integer.
I (integer)['int64_t']: Convert a C int64_t to JSON integer. Note: Jansson expects a json_int_t here without committing to a size, but Flux guarantees that this is a 64-bit integer.
f (real)['double']: Convert a C double to JSON real.
o (any value)['json_t *']: Output any given JSON value as-is. If the value is added to an array or object, the reference to the value passed to o is stolen by the container.
O (any value)['json_t *']: Like o, but the argument's reference count is incremented. This is useful if you pack into an array or object and want to keep the reference for the JSON value consumed by O to yourself.
o?, O? (any value)['json_t *']: Like o and O, respectively, but if the argument is NULL, output a JSON null value.
[fmt] (array): Build an array with contents from the inner format string. fmt may contain objects and arrays, i.e. recursive value building is supported.
{fmt} (object): Build an object with contents from the inner format string fmt. The first, third, etc. format specifier represent a key, and must be a string as object keys are always strings. The second, fourth, etc. format specifier represent a value. Any value may be an object or array, i.e. recursive value building is supported.

Whitespace, : (colon) and , (comma) are ignored.

These descriptions came from the Jansson 2.9 manual.

See also: Jansson API: Building Values: http://jansson.readthedocs.io/en/2.9/apiref.html#building-values

RETURN VALUE

flux_kvs_txn_create() returns a flux_kvs_txn_t object on success, or NULL on failure with errno set appropriately.

flux_kvs_txn_put(), flux_kvs_txn_pack(), flux_kvs_txn_mkdir(), flux_kvs_txn_unlink(), flux_kvs_txn_symlink(), and flux_kvs_txn_put_raw() returns 0 on success, or -1 on failure with errno set appropriately.