kv_create_version_consistency()

#include <kvstore.h>

kv_error_t
kv_create_version_consistency(kv_consistency_t **consistency,
                              const kv_version_t *version,
                              kv_timeout_t timeout_ms)

Creates a consistency policy which ensures that the environment on a replica node is at least as current as denoted by the specified version. The version is created by providing a Value portion of a Key/Value pair to kv_get_version(), or is obtained from the result set provided to kv_result_get_version() or kv_result_get_previous_version(). Versions are also returned in the new_version parameter of the kv_put_with_options() function.

The version of a Key-Value pair represents a point in the serialized transaction schedule created by the master. In other words, the version is like a bookmark, representing a particular transaction commit in the replication stream. The replica ensures that the commit identified by the version has been executed before allowing the transaction on the replica to proceed.

For example, suppose the application is a web application. Each request to the web server consists of an update operation followed by read operations (say from the same client). The read operations naturally expect to see the data from the updates executed by the same request. However, the read operations might have been routed to a replica node that did not execute the update.

In such a case, the update request would generate a version, which would be resubmitted by the browser, and then passed with subsequent read requests to the KV Store. The read request may be directed by the KV Store's load balancer to any one of the available replicas. If the replica servicing the request is already current (with regards to the version token), it will immediately execute the transaction and satisfy the request. If not, the transaction will stall until the replica replay has caught up and the change is available at that node.

You release the memory allocated for the consistency structure using kv_release_consistency().

Parameters

consistency

The consistency parameter references memory into which a pointer to the allocated consistency policy is copied.
version

The version parameter identifies the version that must be seen at the replica in order to consider it current. This value is created by providing a Value portion of a Key/Value pair to kv_get_version(), or is obtained from the result set provided to kv_result_get_version() or kv_result_get_previous_version().
timeout_ms

The timeout_ms parameter describes how long a replica may wait for the desired consistency to be achieved before giving up.

To satisfied the consistency policy, the KVStore client driver implements a read operation by choosing a node (usually a replica) from the proper replication group, and sending it a request. If the replica cannot guarantee the desired Consistency within the Consistency timeout, it replies to the request with a failure indication. If there is still time remaining within the operation timeout, the client driver picks another node and tries the request again (transparent to the application).

KVStore operations which accept a consistency policy also accept a separate operation timeout. It makes sense to think of the operation timeout as the maximum amount of time the application is willing to wait for the operation to complete. On the other hand, the consistency timeout is like a performance hint to the implementation, suggesting that it can generally expect a healthy replica to become consistent within the given amount of time, and that if it does not, then it is probably more likely worth the overhead of abandoning the request attempt and retrying with a different replica. Note that for the consistency timeout to be meaningful, it must be smaller than the operation timeout.

Choosing a value for the operation timeout depends on the needs of the application. Finding a good consistency timeout value is more likely to depend on observations made of real system performance.