[romanb] Added a first documentation for the Locking Manager component

manual/codes/Advanced components - Locking Manager - Examples.php

@@ -0,0 +1,57 @@
+At the page where the lock is requested...
+<?php
+
+// Get a locking manager instance
+$lockingMngr = new Doctrine_Locking_Manager_Pessimistic();
+
+try
+{
+    // Ensure that old locks which timed out are released before we try to acquire our lock
+    $lockingMngr->releaseAgedLocks(300); // 300 seconds = 5 minutes timeout
+
+    // Try to get the lock on a record
+    $gotLock = $lockingMngr->getLock(
+                       $myRecordToLock, // The record to lock. This can be any Doctrine_Record
+                       'Bart Simpson'   // The unique identifier of the user who is trying to get the lock
+               );
+
+    if($gotLock)
+    {
+        echo "Got lock!";
+        // ... proceed
+    }
+    else
+    {
+        echo "Sorry, someone else is currently working on this record";
+    }
+}
+catch(Doctrine_Locking_Exception $dle)
+{
+    echo $dle->getMessage();
+    // handle the error
+}
+
+?>
+
+At the page where the transaction finishes...
+<?php
+// Get a locking manager instance
+$lockingMngr = new Doctrine_Locking_Manager_Pessimistic();
+
+try
+{
+    if($lockingMngr->releaseLock($myRecordToUnlock, 'Bart Simpson'))
+    {
+        echo "Lock released";
+    }
+    else
+    {
+        echo "Record was not locked. No locks released.";
+    }
+}
+catch(Doctrine_Locking_Exception $dle)
+{
+    echo $dle->getMessage();
+    // handle the error
+}
+?>

manual/docs/Advanced components - Locking Manager - Examples.php

@@ -0,0 +1 @@
+The following code snippet demonstrates the use of Doctrine's pessimistic offline locking capabilities.

manual/docs/Advanced components - Locking Manager - Introduction.php

@@ -0,0 +1,23 @@
+[<b>Note</b>: The term 'Transaction' doesnt refer to database transactions here but to the general meaning of this term]<br />
+[<b>Note</b>: This component is in <b>Alpha State</b>]<br />
+<br />
+Locking is a mechanism to control concurrency. The two most well known locking strategies
+are optimistic and pessimistic locking. The following is a short description of these
+two strategies from which only pessimistic locking is currently supported by Doctrine.<br />
+<br />
+<b>Optimistic Locking:</b><br />
+The state/version of the object(s) is noted when the transaction begins.
+When the transaction finishes the noted state/version of the participating objects is compared
+to the current state/version. When the states/versions differ the objects have been modified 
+by another transaction and the current transaction should fail.
+This approach is called 'optimistic' because it is assumed that it is unlikely that several users
+will participate in transactions on the same objects at the same time.<br />
+<br />
+<b>Pessimistic Locking:</b><br />
+The objects that need to participate in the transaction are locked at the moment
+the user starts the transaction. No other user can start a transaction that operates on these objects
+while the locks are active. This ensures that the user who starts the transaction can be sure that
+noone else modifies the same objects until he has finished his work.<br />
+<br />
+Doctrine's pessimistic offline locking capabilities can be used to control concurrency during actions or procedures
+that take several HTTP request and response cycles and/or a lot of time to complete.

manual/docs/Advanced components - Locking Manager - Maintainer.php

@@ -0,0 +1,2 @@
+Roman Borschel - romanb at #doctrine (freenode)<br />
+Don't hesitate to contact me if you have questions, ideas, ect.

manual/docs/Advanced components - Locking Manager - Planned.php

@@ -0,0 +1,2 @@
+- Possibility to release locks of a specific Record type (i.e. releasing all locks on 'User'
+objects).

manual/docs/Advanced components - Locking Manager - Technical Details.php

@@ -0,0 +1,5 @@
+The pessimistic offline locking manager stores the locks in the database (therefore 'offline').
+The required locking table is automatically created when you try to instantiate an instance
+of the manager and the ATTR_CREATE_TABLES is set to TRUE.
+This behaviour may change in the future to provide a centralised and consistent table creation
+procedure for installation purposes.

manual/documentation.php

@@ -241,8 +241,10 @@ $menu = array("Getting started" =>
 
                       "Locking Manager" => array(
                                         "Introduction",
-                                        "Pessimistic locking",
+                                        "Examples",
-                                        "Examples"),
+                                        "Planned",
+                                        "Technical Details",
+                                        "Maintainer"),
                       /**
                       "Debugger" => array(
                                         "Introduction",