Clarify documentation of RIStorageServer.slot_testv_and_readv_and_writev. fixes ...

diff --git a/src/allmydata/interfaces.py b/src/allmydata/interfaces.py
index 14e52be51ce42bf3b2db70623820d3d041632df4..b1c34a79bb2efe50be8e02277f0744b76cbc87ae 100644 (file)
--- a/src/allmydata/interfaces.py
+++ b/src/allmydata/interfaces.py
@@ -159,10 +159,18 @@ class RIStorageServer(RemoteInterface):
                                         tw_vectors=TestAndWriteVectorsForShares,
                                         r_vector=ReadVector,
                                         ):
                                         tw_vectors=TestAndWriteVectorsForShares,
                                         r_vector=ReadVector,
                                         ):

-        """General-purpose test-and-set operation for mutable slots. Perform
-        a bunch of comparisons against the existing shares. If they all pass,
-        then apply a bunch of write vectors to those shares. Then use the
-        read vectors to extract data from all the shares and return the data.
+        """
+        General-purpose test-read-and-set operation for mutable slots:
+        (1) For submitted shnums, compare the test vectors against extant
+            shares, or against an empty share for shnums that do not exist.
+        (2) Use the read vectors to extract "old data" from extant shares.
+        (3) If all tests in (1) passed, then apply the write vectors
+            (possibly creating new shares).
+        (4) Return whether the tests passed, and the "old data", which does
+            not include any modifications made by the writes.
+
+        The operation does not interleave with other operations on the same
+        shareset.

 
         This method is, um, large. The goal is to allow clients to update all
         the shares associated with a mutable file in a single round trip.
 
         This method is, um, large. The goal is to allow clients to update all
         the shares associated with a mutable file in a single round trip.


@@ -187,9 +195,9 @@ class RIStorageServer(RemoteInterface):
         Each share can have a separate test vector (i.e. a list of
         comparisons to perform). If all vectors for all shares pass, then all
         writes for all shares are recorded. Each comparison is a 4-tuple of
         Each share can have a separate test vector (i.e. a list of
         comparisons to perform). If all vectors for all shares pass, then all
         writes for all shares are recorded. Each comparison is a 4-tuple of

-        (offset, length, operator, specimen), which effectively does a bool(
-        (read(offset, length)) OPERATOR specimen ) and only performs the
-        write if all these evaluate to True. Basic test-and-set uses 'eq'.
+        (offset, length, operator, specimen), which effectively does a
+        bool( (read(offset, length)) OPERATOR specimen ) and only performs
+        the write if all these evaluate to True. Basic test-and-set uses 'eq'.

         Write-if-newer uses a seqnum and (offset, length, 'lt', specimen).
         Write-if-same-or-newer uses 'le'.
 
         Write-if-newer uses a seqnum and (offset, length, 'lt', specimen).
         Write-if-same-or-newer uses 'le'.
 


@@ -199,7 +207,11 @@ class RIStorageServer(RemoteInterface):
 
         The write vector will be applied to the given share, expanding it if
         necessary. A write vector applied to a share number that did not
 
         The write vector will be applied to the given share, expanding it if
         necessary. A write vector applied to a share number that did not

-        exist previously will cause that share to be created.
+        exist previously will cause that share to be created. Write vectors
+        must not overlap (if they do, this will either cause an error or
+        apply them in an unspecified order). Duplicate write vectors, with
+        the same offset and data, are currently tolerated but are not
+        desirable.

 
         In Tahoe-LAFS v1.8.3 or later (except 1.9.0a1), if you send a write
         vector whose offset is beyond the end of the current data, the space
 
         In Tahoe-LAFS v1.8.3 or later (except 1.9.0a1), if you send a write
         vector whose offset is beyond the end of the current data, the space


@@ -232,9 +244,9 @@ class RIStorageServer(RemoteInterface):
         than the size of the data after applying all write vectors.
 
         The read vector is used to extract data from all known shares,
         than the size of the data after applying all write vectors.
 
         The read vector is used to extract data from all known shares,

-        *before* any writes have been applied. The same vector is used for
-        all shares. This captures the state that was tested by the test
-        vector.
+        *before* any writes have been applied. The same read vector is used
+        for all shares. This captures the state that was tested by the test
+        vector, for extant shares.

 
         This method returns two values: a boolean and a dict. The boolean is
         True if the write vectors were applied, False if not. The dict is
 
         This method returns two values: a boolean and a dict. The boolean is
         True if the write vectors were applied, False if not. The dict is


@@ -250,7 +262,6 @@ class RIStorageServer(RemoteInterface):
 
         Note that the nodeid here is encoded using the same base32 encoding
         used by Foolscap and allmydata.util.idlib.nodeid_b2a().
 
         Note that the nodeid here is encoded using the same base32 encoding
         used by Foolscap and allmydata.util.idlib.nodeid_b2a().

-

         """
         return TupleOf(bool, DictOf(int, ReadData))
 
         """
         return TupleOf(bool, DictOf(int, ReadData))