diff --git a/manual/codes/Advanced components - Locking Manager - Examples.php b/manual/codes/Advanced components - Locking Manager - Examples.php new file mode 100644 index 000000000..22afb7c53 --- /dev/null +++ b/manual/codes/Advanced components - Locking Manager - Examples.php @@ -0,0 +1,57 @@ +At the page where the lock is requested... +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... +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 +} +?> diff --git a/manual/docs/Advanced components - Locking Manager - Examples.php b/manual/docs/Advanced components - Locking Manager - Examples.php new file mode 100644 index 000000000..fe02a525e --- /dev/null +++ b/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. diff --git a/manual/docs/Advanced components - Locking Manager - Introduction.php b/manual/docs/Advanced components - Locking Manager - Introduction.php new file mode 100644 index 000000000..52833e691 --- /dev/null +++ b/manual/docs/Advanced components - Locking Manager - Introduction.php @@ -0,0 +1,23 @@ +[Note: The term 'Transaction' doesnt refer to database transactions here but to the general meaning of this term]
+[Note: This component is in Alpha State]
+
+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.
+
+Optimistic Locking:
+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.
+
+Pessimistic Locking:
+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.
+
+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. diff --git a/manual/docs/Advanced components - Locking Manager - Maintainer.php b/manual/docs/Advanced components - Locking Manager - Maintainer.php new file mode 100644 index 000000000..9934f77d7 --- /dev/null +++ b/manual/docs/Advanced components - Locking Manager - Maintainer.php @@ -0,0 +1,2 @@ +Roman Borschel - romanb at #doctrine (freenode)
+Don't hesitate to contact me if you have questions, ideas, ect. \ No newline at end of file diff --git a/manual/docs/Advanced components - Locking Manager - Planned.php b/manual/docs/Advanced components - Locking Manager - Planned.php new file mode 100644 index 000000000..42ce24c57 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/manual/docs/Advanced components - Locking Manager - Technical Details.php b/manual/docs/Advanced components - Locking Manager - Technical Details.php new file mode 100644 index 000000000..7a4a56aca --- /dev/null +++ b/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. diff --git a/manual/documentation.php b/manual/documentation.php index 284b1c573..c8c1cfac1 100644 --- a/manual/documentation.php +++ b/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",