ReadOnly: update the documentation about readonly locks

[sahlberg/ctdb.git] / doc / readonlyrecords.txt

diff --git a/doc/readonlyrecords.txt b/doc/readonlyrecords.txt
index 6641b81dd5b5ef2f0bb7e97ff763e7119342c629..c07d5830bebb39d52ff0ec81e71611a50f8132af 100644 (file)
--- a/doc/readonlyrecords.txt
+++ b/doc/readonlyrecords.txt
@@ -47,8 +47,8 @@ Client-side implementation must be possible with only minor conditionals added t
 Implementation
 ==============
 
 Implementation
 ==============
 

-Three new flags are allocated in the ctdb/ltdb record header.
-HAVE_DELEGATIONS, HAVE_READONLY_LOCK and REVOKING_READONLY
+Four new flags are allocated in the ctdb/ltdb record header.
+HAVE_DELEGATIONS, HAVE_READONLY_LOCK, REVOKING_READONLY and REVOKE_COMPLETE

 
 HAVE_DELEGATIONS is a flag that can only be set on the node that is currently the DMASTER for the record. When set, this
 flag indicates that there are Read-Only locks delegated to other nodes in the cluster for this record.
 
 HAVE_DELEGATIONS is a flag that can only be set on the node that is currently the DMASTER for the record. When set, this
 flag indicates that there are Read-Only locks delegated to other nodes in the cluster for this record.


@@ -64,6 +64,24 @@ When the delegations are about to be revoked, the REVOKING_READONLY flag is set
 Once all delegations are revoked, both flags are cleared at the same time.
 While REVOKING_READONLY is set, any requests for the record, either normal request or request for readonly will be deferred.
 Deferred requests are linked to a list of deferred requests for the hash of the record until the time that the revokation is completed.
 Once all delegations are revoked, both flags are cleared at the same time.
 While REVOKING_READONLY is set, any requests for the record, either normal request or request for readonly will be deferred.
 Deferred requests are linked to a list of deferred requests for the hash of the record until the time that the revokation is completed.

+This flags is set by the main ctdb daemon when it starts revoking this record.
+
+REVOKE_COMPLETE
+The actual revoke of records is done by a child process, spawned from the ctdb amin daemon when it starts the process to revoke the records.
+Once the child process has finished revoking all delegations, it will set the flag REVOKE_COMPLETE for this record to signal to the master daemon that the record has been successfully revoked.
+At this stage the child process will also trigger an event in the main daemon that revoke is complete, and that the main dameon should start re-processing all deferred calls.
+
+
+
+Once the revoke process is completed. There will be at least one deferred call to access this record, the initical call to for an exclusive fetch_lock() that triggered the revoke process to be started.
+In addition to nthis deferred call there may also be additional requests that have also become deferred while the revoke was in process. These can be either exclusive fetch_locks() or they can be other calls to request a new readonly lock on the record.
+Once the revoke is completed, the main daemon will reprocess all exclusive fetch_lock() requests immediately and respond to the clients.
+But any requests for readadonly locks will be deferred for an additional period of time before they are re-processed.
+This is to allow the client that needs a fetch_lock() to update the record to get some time to access and work on the record without having to compete with the possibly very many requests to get new readonly delegations created.
+
+
+
+

 
 
 The ctdbdb structure is expanded so that it contains one extra TDB database for each normal, non-persistent datbase.
 
 
 The ctdbdb structure is expanded so that it contains one extra TDB database for each normal, non-persistent datbase.