Merge pull request #2472 from vishesh/doc-compare-and-clear-6.2

DocBlitz: atomic compare and clear

bindings/go/src/fdb/doc.go

@@ -203,7 +203,8 @@ operands to atomic operations in this API must be provided as appropriately
 encoded byte slices. To convert a Go type to a byte slice, see the binary
 package.
 
-The current atomic operations in this API are Add, BitAnd, BitOr, BitXor, Max, Min,
-SetVersionstampedKey, SetVersionstampedValue (all methods on Transaction).
+The current atomic operations in this API are Add, BitAnd, BitOr, BitXor,
+CompareAndClear, Max, Min, SetVersionstampedKey, SetVersionstampedValue
+(all methods on Transaction).
 */
 package fdb

documentation/sphinx/source/api-c.rst

@@ -666,6 +666,10 @@ Applications must provide error handling and an appropriate retry loop around th
 
     |atomic-xor|
 
+    ``FDB_MUTATION_TYPE_COMPARE_AND_CLEAR``
+
+    |atomic-compare-and-clear|
+
     ``FDB_MUTATION_TYPE_MAX``
 
     |atomic-max1|

documentation/sphinx/source/api-common.rst.inc

@@ -111,6 +111,9 @@
 .. |atomic-xor| replace::
     Performs a bitwise "xor" operation. If the existing value in the database is not present or shorter than ``param``, it is first extended to the length of ``param`` with zero bytes. If ``param`` is shorter than the existing value in the database, the existing value is truncated to match the length of ``param``.
 
+.. |atomic-compare-and-clear| replace::
+   Performs an atomic ``compare and clear`` operation. If the existing value in the database is equal to the given value, then given key is cleared.
+
 .. |atomic-max1| replace::
     Sets the value in the database to the larger of the existing value and ``param``. If the existing value in the database is not present or shorter than ``param``, it is first extended to the length of ``param`` with zero bytes. If ``param`` is shorter than the existing value in the database, the existing value is truncated to match the length of ``param``.
 

documentation/sphinx/source/api-python.rst

@@ -644,6 +644,10 @@ In each of the methods below, ``param`` should be a string appropriately packed
 
     |atomic-xor|
 
+.. method:: Transaction.compare_and_clear(key, param)
+
+    |atomic-compare-and-clear|
+
 .. method:: Transaction.max(key, param)
 
     |atomic-max1|

documentation/sphinx/source/api-ruby.rst

@@ -597,6 +597,10 @@ In each of the methods below, ``param`` should be a string appropriately packed
 
     |atomic-xor|
 
+.. method:: Transaction.compare_and_clear(key, param) -> nil
+
+    |atomic-compare-and-clear|
+
 .. method:: Transaction.max(key, param) -> nil
 
     |atomic-max1|

documentation/sphinx/source/developer-guide.rst

@@ -538,12 +538,23 @@ Atomic operations
 
 |atomic-ops-blurb1|
 
-Atomic operations are ideal for operating on keys that multiple clients modify frequently. For example, you can use a key as a counter and increment it with atomic :func:`add`::
+Atomic operations are ideal for operating on keys that multiple clients modify frequently. For example, you can use a key as a counter and increment/decrement it with atomic :func:`add`::
 
   @fdb.transactional
   def increment(tr, counter):
       tr.add(counter, struct.pack('<i', 1))
 
+  @fdb.transactional
+  def decrement(tr, counter):
+      tr.add(counter, struct.pack('<i', -1))
+
+When the counter value is decremented down to 0, you may want to clear the key from database. An easy way to do that is to use :func:`compare_and_clear`, which atomically compares the value against given parameter and clears it without issuing a read from client::
+
+  @fdb.transactional
+  def decrement(tr, counter):
+      tr.add(counter, struct.pack('<i', -1))
+      tr.compare_and_clear(counter, struct.pack('<i', 0))
+
 Similarly, you can use a key as a flag and toggle it with atomic :func:`xor`::
 
   @fdb.transactional