Rename fields of lock and lockholder structures to something a tad less

confusing, and clean up documentation.

src/backend/storage/lmgr/README

-$Header: /cvsroot/pgsql/src/backend/storage/lmgr/README,v 1.4 2000/12/22 00:51:54 tgl Exp $
+$Header: /cvsroot/pgsql/src/backend/storage/lmgr/README,v 1.5 2001/01/16 06:11:34 tgl Exp $
 
 There are two fundamental lock structures: the per-lockable-object LOCK
 struct, and the per-lock-holder HOLDER struct.  A LOCK object exists
@@ -44,51 +44,52 @@ tag -
 	only a single table (see Gray's paper on 2 phase locking if
 	you are puzzled about how multi-level lock tables work).
 
-mask -
-    This field indicates what types of locks are currently held on the
+grantMask -
+    This bitmask indicates what types of locks are currently held on the
     given lockable object.  It is used (against the lock table's conflict
-    table) to determine if the new lock request will conflict with existing
+    table) to determine if a new lock request will conflict with existing
     lock types held.  Conficts are determined by bitwise AND operations
-    between the mask and the conflict table entry for the given lock type
-    to be set.  The current representation is that each bit (1 through 5)
-    is set when that lock type (WRITE, READ, WRITE INTENT, READ INTENT, EXTEND)
-    has been acquired for the lock.
+    between the grantMask and the conflict table entry for the requested
+    lock type.  Bit i of grantMask is 1 if and only if granted[i] > 0.
+
+waitMask -
+    This bitmask shows the types of locks being waited for.  Bit i of waitMask
+    is 1 if and only if requested[i] > granted[i].
 
 waitProcs -
     This is a shared memory queue of all process structures corresponding to
     a backend that is waiting (sleeping) until another backend releases this
     lock.  The process structure holds the information needed to determine
-    if it should be woken up when this lock is released.  If, for example,
-    we are releasing a read lock and the process is sleeping trying to acquire
-    a read lock then there is no point in waking it since the lock being
-    released isn't what caused it to sleep in the first place.  There will
-    be more on this below (when I get to releasing locks and waking sleeping
-    process routines).
+    if it should be woken up when this lock is released.
 
-nHolding -
+nRequested -
     Keeps a count of how many times this lock has been attempted to be
     acquired.  The count includes attempts by processes which were put
     to sleep due to conflicts.  It also counts the same backend twice
     if, for example, a backend process first acquires a read and then
-    acquires a write.
+    acquires a write, or acquires a read lock twice.
 
-holders -
+requested -
     Keeps a count of how many locks of each type have been attempted.  Only
-    elements 1 through MAX_LOCK_TYPES are used as they correspond to the lock
-    type defined constants (WRITE through EXTEND).  Summing the values of
-    holders should come out equal to nHolding.
+    elements 1 through MAX_LOCKMODES-1 are used as they correspond to the lock
+    type defined constants.  Summing the values of requested[] should come out
+    equal to nRequested.
 
-nActive -
-    Keeps a count of how many times this lock has been succesfully acquired.
+nGranted -
+    Keeps count of how many times this lock has been successfully acquired.
     This count does not include attempts that are waiting due to conflicts,
     but can count the same backend twice (e.g. a read then a write -- since
-    its the same transaction this won't cause a conflict)
+    its the same transaction this won't cause a conflict).
+
+granted -
+    Keeps count of how many locks of each type are currently held.  Once again
+    only elements 1 through MAX_LOCKMODES-1 are used (0 is not).  Also, like
+    requested, summing the values of granted should total to the value
+    of nGranted.
 
-activeHolders -
-    Keeps a count of how locks of each type are currently held.  Once again
-    only elements 1 through MAX_LOCK_TYPES are used (0 is not).  Also, like
-    holders, summing the values of activeHolders should total to the value
-    of nActive.
+We should always have 0 <= nGranted <= nRequested, and
+0 <= granted[i] <= requested[i] for each i.  If the request counts go to
+zero, the lock object is no longer needed and can be freed.
 
 ---------------------------------------------------------------------------
 
@@ -116,14 +117,12 @@ tag -
     are always session locks, and we also use session locks for multi-
     transaction operations like VACUUM.
 
-holders -
+holding -
     The number of successfully acquired locks of each type for this holder.
-    (CAUTION: the semantics are not the same as the LOCK's holder[], which
-    counts both acquired and pending requests.  Probably a different name
-    should be used...)
+    This should be <= the corresponding granted[] value of the lock object!
 
 nHolding -
-    Sum of the holders[] array.
+    Sum of the holding[] array.
 
 queue -
     List link for shared memory queue of all the HOLDER objects for the

src/backend/storage/lmgr/proc.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/storage/lmgr/proc.c,v 1.92 2001/01/14 05:08:16 tgl Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/storage/lmgr/proc.c,v 1.93 2001/01/16 06:11:34 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -48,7 +48,7 @@
  *		This is so that we can support more backends. (system-wide semaphore
  *		sets run out pretty fast.)				  -ay 4/95
  *
- * $Header: /cvsroot/pgsql/src/backend/storage/lmgr/proc.c,v 1.92 2001/01/14 05:08:16 tgl Exp $
+ * $Header: /cvsroot/pgsql/src/backend/storage/lmgr/proc.c,v 1.93 2001/01/16 06:11:34 tgl Exp $
  */
 #include "postgres.h"
 
@@ -230,7 +230,7 @@ InitProcess(void)
 		}
 
 		/* this cannot be initialized until after the buffer pool */
-		SHMQueueInit(&(MyProc->lockQueue));
+		SHMQueueInit(&(MyProc->holderQueue));
 	}
 
 	/*
@@ -311,8 +311,8 @@ ZeroProcSemaphore(PROC *proc)
  * Locktable lock must be held by caller.
  *
  * NB: this does not remove the process' holder object, nor the lock object,
- * even though their holder counts might now have gone to zero.  That will
- * happen during a subsequent LockReleaseAll call, which we expect will happen
+ * even though their counts might now have gone to zero.  That will happen
+ * during a subsequent LockReleaseAll call, which we expect will happen
  * during transaction cleanup.  (Removal of a proc from its wait queue by
  * this routine can only happen if we are aborting the transaction.)
  */
@@ -331,14 +331,14 @@ RemoveFromWaitQueue(PROC *proc)
 	SHMQueueDelete(&(proc->links));
 	waitLock->waitProcs.size--;
 
-	/* Undo increments of holder counts by waiting process */
-	Assert(waitLock->nHolding > 0);
-	Assert(waitLock->nHolding > proc->waitLock->nActive);
-	waitLock->nHolding--;
-	Assert(waitLock->holders[lockmode] > 0);
-	waitLock->holders[lockmode]--;
+	/* Undo increments of request counts by waiting process */
+	Assert(waitLock->nRequested > 0);
+	Assert(waitLock->nRequested > proc->waitLock->nGranted);
+	waitLock->nRequested--;
+	Assert(waitLock->requested[lockmode] > 0);
+	waitLock->requested[lockmode]--;
 	/* don't forget to clear waitMask bit if appropriate */
-	if (waitLock->activeHolders[lockmode] == waitLock->holders[lockmode])
+	if (waitLock->granted[lockmode] == waitLock->requested[lockmode])
 		waitLock->waitMask &= ~(1 << lockmode);
 
 	/* Clean up the proc's own state */
@@ -546,7 +546,7 @@ ProcSleep(LOCKMETHODCTL *lockctl,
 	int			waitMask = lock->waitMask;
 	PROC	   *proc;
 	int			i;
-	int			aheadHolders[MAX_LOCKMODES];
+	int			aheadGranted[MAX_LOCKMODES];
 	bool		selfConflict = (lockctl->conflictTab[lockmode] & myMask),
 				prevSame = false;
 #ifndef __BEOS__
@@ -559,7 +559,7 @@ ProcSleep(LOCKMETHODCTL *lockctl,
 	MyProc->waitLock = lock;
 	MyProc->waitHolder = holder;
 	MyProc->waitLockMode = lockmode;
-	/* We assume the caller set up MyProc->holdLock */
+	/* We assume the caller set up MyProc->heldLocks */
 
 	proc = (PROC *) MAKE_PTR(waitQueue->links.prev);
 
@@ -567,57 +567,61 @@ ProcSleep(LOCKMETHODCTL *lockctl,
 	if (!(lockctl->conflictTab[lockmode] & waitMask))
 		goto ins;
 
+	/* otherwise, determine where we should go into the queue */
 	for (i = 1; i < MAX_LOCKMODES; i++)
-		aheadHolders[i] = lock->activeHolders[i];
-	(aheadHolders[lockmode])++;
+		aheadGranted[i] = lock->granted[i];
+	(aheadGranted[lockmode])++;
 
 	for (i = 0; i < waitQueue->size; i++)
 	{
-		/* am I waiting for him ? */
-		if (lockctl->conflictTab[lockmode] & proc->holdLock)
+		LOCKMODE	procWaitMode = proc->waitLockMode;
+
+		/* must I wait for him ? */
+		if (lockctl->conflictTab[lockmode] & proc->heldLocks)
 		{
 			/* is he waiting for me ? */
-			if (lockctl->conflictTab[proc->waitLockMode] & MyProc->holdLock)
+			if (lockctl->conflictTab[procWaitMode] & MyProc->heldLocks)
 			{
 				/* Yes, report deadlock failure */
 				MyProc->errType = STATUS_ERROR;
 				goto rt;
 			}
-			/* being waiting for him - go past */
+			/* I must go after him in queue - so continue loop */
 		}
-		/* if he waits for me */
-		else if (lockctl->conflictTab[proc->waitLockMode] & MyProc->holdLock)
+		/* if he waits for me, go before him in queue */
+		else if (lockctl->conflictTab[procWaitMode] & MyProc->heldLocks)
 			break;
 		/* if conflicting locks requested */
-		else if (lockctl->conflictTab[proc->waitLockMode] & myMask)
+		else if (lockctl->conflictTab[procWaitMode] & myMask)
 		{
 
 			/*
 			 * If I request non self-conflicting lock and there are others
-			 * requesting the same lock just before me - stay here.
+			 * requesting the same lock just before this guy - stop here.
 			 */
 			if (!selfConflict && prevSame)
 				break;
 		}
 
 		/*
-		 * Last attempt to don't move any more: if we don't conflict with
-		 * rest waiters in queue.
+		 * Last attempt to not move any further to the back of the queue:
+		 * if we don't conflict with remaining waiters, stop here.
 		 */
 		else if (!(lockctl->conflictTab[lockmode] & waitMask))
 			break;
 
-		prevSame = (proc->waitLockMode == lockmode);
-		(aheadHolders[proc->waitLockMode])++;
-		if (aheadHolders[proc->waitLockMode] == lock->holders[proc->waitLockMode])
-			waitMask &= ~(1 << proc->waitLockMode);
+		/* Move past this guy, and update state accordingly */
+		prevSame = (procWaitMode == lockmode);
+		(aheadGranted[procWaitMode])++;
+		if (aheadGranted[procWaitMode] == lock->requested[procWaitMode])
+			waitMask &= ~(1 << procWaitMode);
 		proc = (PROC *) MAKE_PTR(proc->links.prev);
 	}
 
 ins:;
 	/* -------------------
-	 * Insert self into queue.  These operations are atomic (because
-	 * of the spinlock).
+	 * Insert self into queue, ahead of the given proc.
+	 * These operations are atomic (because of the spinlock).
 	 * -------------------
 	 */
 	SHMQueueInsertTL(&(proc->links), &(MyProc->links));
@@ -838,7 +842,7 @@ nextProc:
 void
 ProcAddLock(SHM_QUEUE *elem)
 {
-	SHMQueueInsertTL(&MyProc->lockQueue, elem);
+	SHMQueueInsertTL(&MyProc->holderQueue, elem);
 }
 
 /* --------------------

src/include/storage/lock.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2000, PostgreSQL, Inc
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: lock.h,v 1.40 2000/12/22 00:51:54 tgl Exp $
+ * $Id: lock.h,v 1.41 2001/01/16 06:11:34 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -150,26 +150,28 @@ typedef struct LOCKTAG
  * Per-locked-object lock information:
  *
  * tag -- uniquely identifies the object being locked
- * mask -- union of the conflict masks of all lock types
- *		currently held on this object.
- * waitProcs -- queue of processes waiting for this lock
- * holders -- count of each lock type currently held on the
- *		lock.
- * nHolding -- total locks of all types.
+ * grantMask -- bitmask for all lock types currently granted on this object.
+ * waitMask -- bitmask for all lock types currently awaited on this object.
+ * waitProcs -- queue of processes waiting for this lock.
+ * requested -- count of each lock type currently requested on the lock
+ *		(includes requests already granted!!).
+ * nRequested -- total requested locks of all types.
+ * granted -- count of each lock type currently granted on the lock.
+ * nGranted -- total granted locks of all types.
  */
 typedef struct LOCK
 {
 	/* hash key */
-	LOCKTAG		tag;
+	LOCKTAG		tag;			/* unique identifier of lockable object */
 
 	/* data */
-	int			mask;
-	int			waitMask;
-	PROC_QUEUE	waitProcs;
-	int			holders[MAX_LOCKMODES];
-	int			nHolding;
-	int			activeHolders[MAX_LOCKMODES];
-	int			nActive;
+	int			grantMask;		/* bitmask for lock types already granted */
+	int			waitMask;		/* bitmask for lock types awaited */
+	PROC_QUEUE	waitProcs;		/* list of PROC objects waiting on lock */
+	int			requested[MAX_LOCKMODES]; /* counts of requested locks */
+	int			nRequested;		/* total of requested[] array */
+	int			granted[MAX_LOCKMODES];	/* counts of granted locks */
+	int			nGranted;		/* total of granted[] array */
 } LOCK;
 
 #define SHMEM_LOCKTAB_KEYSIZE  sizeof(LOCKTAG)
@@ -193,6 +195,12 @@ typedef struct LOCK
  * Currently, session holders are used for user locks and for cross-xact
  * locks obtained for VACUUM.  We assume that a session lock never conflicts
  * with per-transaction locks obtained by the same backend.
+ *
+ * The holding[] array counts the granted locks (of each type) represented
+ * by this holder.  Note that there will be a holder object, possibly with
+ * zero holding[], for any lock that the process is currently waiting on.
+ * Otherwise, holder objects whose counts have gone to zero are recycled
+ * as soon as convenient.
  */
 typedef struct HOLDERTAG
 {
@@ -204,12 +212,12 @@ typedef struct HOLDERTAG
 typedef struct HOLDER
 {
 	/* tag */
-	HOLDERTAG	tag;
+	HOLDERTAG	tag;			/* unique identifier of holder object */
 
 	/* data */
-	int			holders[MAX_LOCKMODES];
-	int			nHolding;
-	SHM_QUEUE	queue;
+	int			holding[MAX_LOCKMODES];	/* count of locks currently held */
+	int			nHolding;		/* total of holding[] array */
+	SHM_QUEUE	queue;			/* list link for process' list of holders */
 } HOLDER;
 
 #define SHMEM_HOLDERTAB_KEYSIZE  sizeof(HOLDERTAG)
@@ -241,7 +249,7 @@ extern bool LockReleaseAll(LOCKMETHOD lockmethod, PROC *proc,
 						   bool allxids, TransactionId xid);
 extern int LockResolveConflicts(LOCKMETHOD lockmethod, LOCKMODE lockmode,
 								LOCK *lock, HOLDER *holder, PROC *proc,
-								int *myHolders);
+								int *myHolding);
 extern void GrantLock(LOCK *lock, HOLDER *holder, LOCKMODE lockmode);
 extern int	LockShmemSize(int maxBackends);
 extern bool DeadLockCheck(PROC *thisProc, LOCK *findlock);

src/include/storage/proc.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2000, PostgreSQL, Inc
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: proc.h,v 1.34 2001/01/14 05:08:16 tgl Exp $
+ * $Id: proc.h,v 1.35 2001/01/16 06:11:34 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -27,13 +27,20 @@ typedef struct
 } SEMA;
 
 /*
- * Each backend has:
+ * Each backend has a PROC struct in shared memory.  There is also a list
+ * of currently-unused PROC structs that will be reallocated to new backends
+ * (a fairly pointless optimization, but it's there anyway).
+ *
+ * links: list link for any list the PROC is in.  When waiting for a lock,
+ * the PROC is linked into that lock's waitProcs queue.  A recycled PROC
+ * is linked into ProcGlobal's freeProcs list.
  */
 struct proc
 {
 	/* proc->links MUST BE THE FIRST ELEMENT OF STRUCT (see ProcWakeup()) */
 
-	SHM_QUEUE	links;			/* proc can be waiting for one event(lock) */
+	SHM_QUEUE	links;			/* list link if process is in a list */
+
 	SEMA		sem;			/* ONE semaphore to sleep on */
 	int			errType;		/* error code tells why we woke up */
 
@@ -48,16 +55,17 @@ struct proc
 
 	/* Info about lock the process is currently waiting for, if any */
 	LOCK	   *waitLock;		/* Lock object we're sleeping on ... */
-	HOLDER	   *waitHolder;		/* Per-holder info for our lock */
+	HOLDER	   *waitHolder;		/* Per-holder info for awaited lock */
 	LOCKMODE	waitLockMode;	/* type of lock we're waiting for */
-	LOCKMASK	holdLock;		/* bitmask for lock types already held */
+	LOCKMASK	heldLocks;		/* bitmask for lock types already held on
+								 * this lock object by this backend */
 
 	int			pid;			/* This backend's process id */
 	Oid			databaseId;		/* OID of database this backend is using */
 
 	short		sLocks[MAX_SPINS];		/* Spin lock stats */
-	SHM_QUEUE	lockQueue;		/* locks associated with current
-								 * transaction */
+	SHM_QUEUE	holderQueue;	/* list of HOLDER objects for locks held or
+								 * awaited by this backend */
 };
 
 /* NOTE: "typedef struct proc PROC" appears in storage/lock.h. */