kv_get_version()

#include <kvstore.h>

const kv_version_t *
kv_get_version(const kv_value_t *value) 

Creates a version structure, which refers to a specific version of a key-value pair. Note that the kv_version_t structure returned by this function is owned by the kv_value_t structure from which is was obtained. As such, you should not explicitly release the version structure returned by this function; it will be automatically released when the value structure is released.

When a key-value pair is initially inserted in the KV Store, and each time it is updated, it is assigned a unique version token. The version is associated with the version portion of the key-value pair. The version is important for two reasons:

• When an update or delete is to be performed, it may be important to only perform the update or delete if the last known value has not changed. For example, if an integer field in a previously known value is to be incremented, it is important that the previous value has not changed in the KV Store since it was obtained by the client. This can be guaranteed by passing the version of the previously known value to the if_version parameter of the kv_put_with_options() or kv_delete_with_options() functions. If the version specified does not match the current version of the value in the KV Store, these functions will not perform the update or delete operation and will return an indication of failure. Optionally, they will also return the current version and/or value so the client can retry the operation or take a different action.

• When a client reads a value that was previously written, it may be important to ensure that the KV Store node servicing the read operation has been updated with the information previously written. This can be accomplished by using a version-based consistency policy with the read operation. See kv_create_version_consistency() for more information.

  Be aware that the system may infrequently assign a new version to a key-value pair; for example, when migrating data for better resource usage. Therefore, when using kv_put_with_options() or kv_delete_with_options(), do not assume that the version will remain constant until it is changed by the application.

Parameters

• value

  The value parameter is the value structure from which you want to extract version information.

See Also

• Key/Value Pair Management Functions