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:

  1. prevValue = get(key);
  2. if (prevValue == request.prevValue) {
  3.     put(key, request.value);
  4. }
  5. 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, downloaded tikv-client JAR files, and started a TiKV cluster according to TiKV in 5 Minutes.

Verify CAS

To verify whether CAS works, you can take the following steps.

Step 1: Write the code to test CAS

Save the following script to the test_raw_cas.java file.

  1. import java.util.Optional;
  2. import org.tikv.common.TiConfiguration;
  3. import org.tikv.common.TiSession;
  4. import org.tikv.raw.RawKVClient;
  5. import org.tikv.shade.com.google.protobuf.ByteString;
  7. TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
  8. // enable AtomicForCAS when using RawKVClient.compareAndSet or RawKVClient.putIfAbsent
  9. conf.setEnableAtomicForCAS(true);
  10. TiSession session = TiSession.create(conf);
  11. RawKVClient client = session.createRawClient();
  13. ByteString key = ByteString.copyFromUtf8("Hello");
  14. ByteString value = ByteString.copyFromUtf8("CAS");
  15. ByteString newValue = ByteString.copyFromUtf8("NewValue");
  17. // put
  18. client.put(key, value);
  19. System.out.println("put key=" + key.toStringUtf8() + " value=" + value.toStringUtf8());
  21. // get
  22. Optional<ByteString> result = client.get(key);
  23. assert(result.isPresent());
  24. assert("CAS".equals(result.get().toStringUtf8()));
  25. System.out.println("get key=" + key.toStringUtf8() + " result=" + result.get().toStringUtf8());
  27. // cas
  28. client.compareAndSet(key, Optional.of(value), newValue);
  29. System.out.println("cas key=" + key.toStringUtf8() + " value=" + value.toStringUtf8() + " newValue=" + newValue.toStringUtf8());
  31. // get
  32. result = client.get(key);
  33. assert(result.isPresent());
  34. assert("NewValue".equals(result.get().toStringUtf8()));
  35. System.out.println("get key=" + key.toStringUtf8() + " result=" + result.get().toStringUtf8());
  37. // close
  38. client.close();
  39. session.close();

Step 2: Run the code

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

The example output is as follows:

  1. put key=Hello value=CAS
  2. get key=Hello result=CAS
  3. cas key=Hello value=CAS newValue=NewValue
  4. 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.