flux_kvs_lookup(3)¶
SYNOPSIS¶
#include <flux/core.h>
flux_future_t *flux_kvs_lookup (flux_t *h, const char *ns, int flags,
const char *key);
flux_future_t *flux_kvs_lookupat (flux_t *h, int flags,
const char *key, const char *treeobj);
int flux_kvs_lookup_get (flux_future_t *f, const char **value);
int flux_kvs_lookup_get_unpack (flux_future_t *f, const char *fmt, ...);
int flux_kvs_lookup_get_raw (flux_future_t *f,
const void **data, int *len);
int flux_kvs_lookup_get_dir (flux_future_t *f,
const flux_kvsdir_t **dir);
int flux_kvs_lookup_get_treeobj (flux_future_t *f, const char **treeobj);
int flux_kvs_lookup_get_symlink (flux_future_t *f, const char **ns,
const char **target);
const char *flux_kvs_lookup_get_key (flux_future_t *f);
int flux_kvs_lookup_cancel (flux_future_t *f);
DESCRIPTION¶
The Flux Key Value Store is a general purpose distributed storage service used by Flux services.
flux_kvs_lookup()
sends a request to the KVS service to look up
key in namespace ns. It returns a flux_future_t
object which
acts as handle for synchronization and container for the result. The
namespace ns is optional. If set to NULL, flux_kvs_lookup()
uses
the default namespace, or if set, the namespace from the
FLUX_KVS_NAMESPACE environment variable. flags modifies the request
as described below.
flux_kvs_lookupat()
is identical to flux_kvs_lookup()
except
treeobj is a serialized RFC 11 object that references a particular
static set of content within the KVS, effectively a snapshot.
See flux_kvs_lookup_get_treeobj()
below.
All the functions below are variations on a common theme. First they
complete the lookup RPC by blocking on the response, if not already received.
Then they interpret the result in different ways. They may be called more
than once on the same future, and they may be intermixed to probe a result
or interpret it in different ways. Results remain valid until
flux_future_destroy()
is called.
flux_kvs_lookup_get()
interprets the result as a value. If the value
has length greater than zero, a NULL is appended and it is assigned
to value, otherwise NULL is assigned to value.
flux_kvs_lookup_get_unpack()
interprets the result as a value, which
it decodes as JSON according to variable arguments in Jansson
json_unpack()
format.
flux_kvs_lookup_get_raw()
interprets the result as a value. If the value
has length greater than zero, the value and its length are assigned to
buf and len, respectively. Otherwise NULL and zero are assigned.
flux_kvs_lookup_get_dir()
interprets the result as a directory,
e.g. in response to a lookup with the FLUX_KVS_READDIR flag set.
The directory object is assigned to dir.
flux_kvs_lookup_get_treeobj()
interprets the result as any RFC 11 object.
The object in JSON-encoded form is assigned to treeobj. Since all
lookup requests return an RFC 11 object of one type or another, this
function should work on all.
flux_kvs_lookup_get_symlink()
interprets the result as a symlink target,
e.g. in response to a lookup with the FLUX_KVS_READLINK flag set.
The result is parsed and symlink namespace is assigned to ns and
the symlink target is assigned to target. If a namespace was not assigned
to the symlink, ns is set to NULL.
flux_kvs_lookup_get_key()
accesses the key argument from the original
lookup.
flux_kvs_lookup_cancel()
cancels a stream of lookup responses
requested with FLUX_KVS_WATCH or a waiting lookup response with
FLUX_KVS_WAITCREATE. See FLAGS below for additional information.
These functions may be used asynchronously. See flux_future_then(3) for details.
FLAGS¶
The following are valid bits in a flags mask passed as an argument
to flux_kvs_lookup()
or flux_kvs_lookupat()
.
- FLUX_KVS_READDIR
Look up a directory, not a value. The lookup fails if the key does not refer to a directory object.
- FLUX_KVS_READLINK
If key is a symlink, read the link value. The lookup fails if the key does not refer to a symlink object.
- FLUX_KVS_TREEOBJ
All KVS lookups return an RFC 11 tree object. This flag requests that they be returned without conversion. That is, a "valref" will not be converted to a "val" object, and a "dirref" will not be converted to a "dir" object. This is useful for obtaining a snapshot reference that can be passed to
flux_kvs_lookupat()
.- FLUX_KVS_WATCH
After the initial response, continue to send responses to the lookup request each time key is mentioned verbatim in a committed transaction. After receiving a response,
flux_future_reset()
should be used to consume a response and prepare for the next one. Responses continue until the namespace is removed, the key is removed, the lookup is canceled withflux_kvs_lookup_cancel()
, or an error occurs. After callingflux_kvs_lookup_cancel()
, callers should wait for the future to be fulfilled with an ENODATA error to ensure the cancel request has been received and processed.- FLUX_KVS_WATCH_UNIQ
Specified along with FLUX_KVS_WATCH, this flag will alter watch behavior to only respond when key is mentioned verbatim in a committed transaction and the value of the key has changed.
- FLUX_KVS_WATCH_APPEND
Specified along with FLUX_KVS_WATCH, this flag will alter watch behavior to only respond when key is mentioned verbatim in a committed transaction and the key has been appended to. The response will only contain the additional appended data. Note that only data length is considered for appends and no guarantee is made that prior data hasn't been overwritten.
- FLUX_KVS_WATCH_FULL
Specified along with FLUX_KVS_WATCH, this flag will alter watch behavior to respond when the value of the key being watched has changed. Unlike FLUX_KVS_WATCH_UNIQ, the key being watched need not be mentioned in a transaction. This may occur under several scenarios, such as a parent directory being altered.
- FLUX_KVS_WAITCREATE
If a KVS key does not exist, wait for it to exist before returning. This flag can be specified with or without FLUX_KVS_WATCH. The lookup can be canceled with
flux_kvs_lookup_cancel()
. After callingflux_kvs_lookup_cancel()
, callers should wait for the future to be fulfilled with an ENODATA error to ensure the cancel request has been received and processed.
RETURN VALUE¶
flux_kvs_lookup()
and flux_kvs_lookupat()
return a
flux_future_t
on success, or NULL on failure with errno set appropriately.
flux_kvs_lookup_get()
, flux_kvs_lookup_get_unpack()
,
flux_kvs_lookup_get_raw()
, flux_kvs_lookup_get_dir()
,
flux_kvs_lookup_get_treeobj()
, flux_kvs_lookup_get_symlink()
,
and flux_kvs_lookup_cancel()
return 0 on success, or -1 on failure with
errno set appropriately.
flux_kvs_lookup_get_key()
returns key on success, or NULL with errno
set to EINVAL if its future argument did not come from a KVS lookup.
ERRORS¶
- EINVAL
One of the arguments was invalid, or FLUX_KVS_READLINK was used but the key does not refer to a symlink.
- ENOMEM
Out of memory.
- ENOENT
An unknown key was requested.
- ENOTDIR
FLUX_KVS_READDIR flag was set and key does NOT point to a directory.
- EISDIR
FLUX_KVS_READDIR flag was NOT set and key points to a directory.
- EPROTO
A request or response was malformed.
- EFBIG; ENOSYS
The KVS module is not loaded.
- ENOTSUP
An unknown namespace was requested or namespace was deleted.
- ENODATA
A stream of responses requested with FLUX_KVS_WATCH was terminated with
flux_kvs_lookup_cancel()
.- EPERM
The user does not have instance owner capability, and a lookup was attempted against a KVS namespace owned by another user.
RESOURCES¶
Flux: http://flux-framework.org
RFC 11: Key Value Store Tree Object Format v1: https://flux-framework.readthedocs.io/projects/flux-rfc/en/latest/spec_11.html