Index: includes/lock.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/lock.inc,v
retrieving revision 1.5
diff -u -r1.5 lock.inc
--- includes/lock.inc	16 Jul 2010 11:19:38 -0000	1.5
+++ includes/lock.inc	25 Jul 2010 23:50:12 -0000
@@ -7,7 +7,7 @@
  */
 
 /**
- * @defgroup lock Functions to coordinate long-running operations across requests.
+ * @defgroup lock Functions to coordinate long operations across requests.
  * @{
  * In most environments, multiple Drupal page requests (a.k.a. threads or
  * processes) will execute in parallel. This leads to potential conflicts or
@@ -16,15 +16,14 @@
  * hook implementations to get and process data from all active modules, and
  * then delete the current data in the database to insert the new afterwards.
  *
- * This is a cooperative, advisory lock system. Any long-running operation
- * that could potentially be attempted in parallel by multiple requests should
- * try to acquire a lock before proceeding. By obtaining a lock, one request
- * notifies any other requests that a specific operation is in progress which
- * must not be executed in parallel.
+ * To avoid this type of conflicts, Drupal has a cooperative, advisory lock
+ * system. Any long-running operation that could potentially be attempted in
+ * parallel by multiple requests should try to acquire a lock before
+ * proceeding. By obtaining a lock, one request notifies any other requests that
+ * a specific operation is in progress which must not be executed in parallel.
  *
  * To use this API, pick a unique name for the lock. A sensible choice is the
- * name of the function performing the operation. A very simple example use of
- * this API:
+ * name of the function performing the operation. Here is a simple example:
  * @code
  * function mymodule_long_operation() {
  *   if (lock_acquire('mymodule_long_operation')) {
@@ -58,6 +57,27 @@
  * this is an API intended to support alternative implementations, code using
  * this API should never rely upon specific implementation details (for example
  * no code should look for or directly modify a lock in the {semaphore} table).
+ *
+ * The following limitations in this implementation should be carefully noted:
+ * - Time: Timestamps are derived from the local system clock of the processor
+ *   the code is executing on. The orderly progression of time from this
+ *   viewpoint can be disrupted by external events such as NTP synchronization
+ *   and operator intervention. Where multiple web servers are involved in
+ *   serving the site, they will have their own independent clocks, introducing
+ *   another source of error in the time keeping process. Timeout values applied
+ *   to locks must therefore be considered approximate, and should not be relied
+ *   upon.
+ * - Uniqueness: Uniqueness of lock names is is not enforced. The impact of the
+ *   use of a common lock name will depend on what processes and resources the
+ *   lock is being used to manage. The best case is a denial of service
+ *   situation.
+ * - Sharing: There is limited support for resources shared across sites.
+ *   The locks are stored as rows in the semaphore table and, as such, they
+ *   have the same visibility as the table. If managed resources are shared
+ *   across sites then the semaphore table must be shared across sites. This
+ *   is a binary situation: either all resources are shared and the semaphore
+ *   table is shared or no resources are shared and the semaphore table is
+ *   not shared. Mixed mode operation is not supported.
  */
 
 /**