CAS on RawKV

Compare And Swap

This page walks you through a simple demonstration of performing compare-and-swap (CAS) in TiKV.

In RawKV, compare-and-swap (CAS) is an atomic instruction to achieve synchronization between multiple threads.

Performing CAS is an atomic equivalent of executing the following code:

prevValue = get(key);
if (prevValue == request.prevValue) {
    put(key, request.value);
}
return prevValue;

The atomicity guarantees that the new value is calculated based on the up-to-date information. If the value is updated by another thread at the same time, the write would fail.

Prerequisites

Make sure that you have installed TiUP, jshell, download tikv-client JAR files, and start a TiKV cluster according to TiKV in 5 Minutes.

Verify CAS

To verify whether CAS works, take the following steps.

Step 1: Write the code to test CAS

Save the following script to the test_raw_cas.java file.

import java.util.Optional;
import org.tikv.common.TiConfiguration;
import org.tikv.common.TiSession;
import org.tikv.raw.RawKVClient;
import org.tikv.shade.com.google.protobuf.ByteString;

TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
// enable AtomicForCAS when using RawKVClient.compareAndSet or RawKVClient.putIfAbsent
conf.setEnableAtomicForCAS(true);
TiSession session = TiSession.create(conf);
RawKVClient client = session.createRawClient();

ByteString key = ByteString.copyFromUtf8("Hello");
ByteString value = ByteString.copyFromUtf8("CAS");
ByteString newValue = ByteString.copyFromUtf8("NewValue");

// put
client.put(key, value);
System.out.println("put key=" + key.toStringUtf8() + " value=" + value.toStringUtf8());

// get
Optional<ByteString> result = client.get(key);
assert(result.isPresent());
assert("CAS".equals(result.get().toStringUtf8()));
System.out.println("get key=" + key.toStringUtf8() + " result=" + result.get().toStringUtf8());

// cas
client.compareAndSet(key, Optional.of(value), newValue);
System.out.println("cas key=" + key.toStringUtf8() + " value=" + value.toStringUtf8() + " newValue=" + newValue.toStringUtf8());

// get
result = client.get(key);
assert(result.isPresent());
assert("NewValue".equals(result.get().toStringUtf8()));
System.out.println("get key=" + key.toStringUtf8() + " result=" + result.get().toStringUtf8());

// close
client.close();
session.close();

Step 2: Run the code

jshell --class-path tikv-client-java.jar:slf4j-api.jar --startup test_raw_cas.java

The example output is as follows:

put key=Hello value=CAS
get key=Hello result=CAS
cas key=Hello value=CAS newValue=NewValue
get key=Hello result=NewValue

As in the example output, after calling compareAndSet, the value CAS is replaced by newValue.

  • To ensure the linearizability of CAS when it is used together with put, delete, batch_put, or batch_delete, you must set conf.setEnableAtomicForCAS(true).

  • To guarantee the atomicity of CAS, write operations such as put or delete in atomic mode take more resources.