flux_kvs_copy(3)

SYNOPSIS

#include <flux/core.h>

flux_future_t *flux_kvs_copy (flux_t *h,
                              const char *srckey,
                              const char *dstkey,
                              int commit_flags);

flux_future_t *flux_kvs_move (flux_t *h,
                              const char *srckey,
                              const char *dstkey,
                              int commit_flags);

Link with -lflux-core.

DESCRIPTION

flux_kvs_copy() sends a request via handle h to the KVS service to look up the directory entry of srckey. Upon receipt of the response, it then sends another request to commit a duplicate at dstkey. commit_flags are passed through to the commit operation. See the FLAGS section of flux_kvs_commit(3).

The net effect is that all content below srckey is copied to dstkey. Due to the hash tree organization of the KVS name space, only the directory entry needs to be duplicated to create a new, fully independent deep copy of the original data.

flux_kvs_move() first performs a flux_kvs_copy(), then sends a commit request to unlink srckey. commit_flags are passed through to the commit within flux_kvs_copy(), and to the commit which performs the unlink.

flux_kvs_copy() and flux_kvs_move() are capable of working across namespaces. See flux_kvs_commit(3) for info on how to select a namespace other than the default.

CAVEATS

flux_kvs_copy() and flux_kvs_commit() are implemented as aggregates of multiple KVS operations. As such they do not have the "all or nothing" guarantee of a being carried out within a single KVS transaction.

In the unlikely event that the copy phase of a flux_kvs_move() succeeds but the unlink phase fails, flux_kvs_move() may return failure without cleaning up the new copy. Since the copy phase already validated that the unlink target key exists by copying from it, the source of such a failure would be a transient error such as out of memory or communication failure.

RETURN VALUE

flux_kvs_copy() and flux_kvs_move() 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.

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc