Rename locking structure names to be clearer. Add narrative to

backend flowchart.

1 files changed, 28 insertions, 18 deletions

diff --git a/src/tools/backend/index.html b/src/tools/backend/index.html
index f736439fa0..3f032e081c 100644
--- a/src/tools/backend/index.html
+++ b/src/tools/backend/index.html
@@ -25,13 +25,13 @@ structure, like
 The query is then identified as a <I>Utility</I> function or a more
 complex query.  A <I>Utility</I> query is processed by a
 query-specific function in <A HREF="../../backend/commands">
-commands.</A> A complex query, like <B>SELECT, UPDATE,</B> and
-<B>DELETE</B> requires much more handling.
+commands.</A> A complex query, like <CODE>SELECT, UPDATE,</CODE> and
+<CODE>DELETE</CODE> requires much more handling.
 <P>
 The parser takes a complex query, and creates a
 <A HREF="../../include/nodes/parsenodes.h">Query</A> structure that
 contains all the elements used by complex queries.  Query.qual holds the
-<B>WHERE</B> clause qualification, which is filled in by
+<CODE>WHERE</CODE> clause qualification, which is filled in by
 <A HREF="../../backend/parser/parse_clause.c">transformWhereClause().</A>
 Each table referenced in the query is represented by a <A
 HREF="../../include/nodes/parsenodes.h"> RangeTableEntry,</A> and they
@@ -39,19 +39,19 @@ are linked together to form the <I>range table</I> of the query, which is
 generated by <A HREF="../../backend/parser/parse_clause.c">
 makeRangeTable().</A>  Query.rtable holds the queries range table.
 <P>
-Certain queries, like <B>SELECT,</B> return columns of data.  Other
-queries, like <B>INSERT</B> and <B>UPDATE,</B> specify the columns
+Certain queries, like <CODE>SELECT,</CODE> return columns of data.  Other
+queries, like <CODE>INSERT</CODE> and <CODE>UPDATE,</CODE> specify the columns
 modified by the query.  These column references are converted to <A
 HREF="../../include/nodes/primnodes.h">Resdom</A> entries, which are
 linked together to make up the <I>target list</I> of the query. The
 target list is stored in Query.targetList, which is generated by
 <A HREF="../../backend/parser/parse_target.c">transformTargetList().</A>
 <P>
-Other query elements, like aggregates(<B>SUM()</B>), <B>GROUP BY,</B>
-<B>ORDER BY</B> are also stored in their own Query fields.
+Other query elements, like aggregates(<CODE>SUM()</CODE>), <CODE>GROUP BY,</CODE>
+<CODE>ORDER BY</CODE> are also stored in their own Query fields.
 <P>
-The next step is for the Query to be modified by any <B>VIEWS</B> or
-<B>RULES</B> that may apply to the query.  This is performed by the <A
+The next step is for the Query to be modified by any <CODE>VIEWS</CODE> or
+<CODE>RULES</CODE> that may apply to the query.  This is performed by the <A
 HREF="../../backend/rewrite">rewrite</A> system.
 <P>
 The <A HREF="../../backend/optimizer">optimizer</A> takes the Query
@@ -60,7 +60,7 @@ HREF="../..//include/nodes/plannodes.h">Plan,</A> which contains the
 operations to be performed to execute the query.  The <A
 HREF="../../backend/optimizer/path">path</A> module determines the best
 table join order and join type of each table in the RangeTable, using
-Query.qual(<B>WHERE</B> clause) to consider optimal index usage.
+Query.qual(<CODE>WHERE</CODE> clause) to consider optimal index usage.
 <P>
 The Plan is then passed to the <A
 HREF="../../backend/executor">executor</A> for execution, and the result
@@ -81,15 +81,25 @@ data/index buffer cache block
 <LI>Shared Buf Lookup Table - lookup of buffer cache block address using
 table name and block number(<A HREF="../../include/storage/buf_internals.h">
 BufferTag</A>)
-<LI><A HREF="../../include/storage/lock.h">LockTable (ctl)</A> - lock table
-structure, specifiying table, lock types, and backends holding or
-waiting on lock
-<LI>LockTable (lock hash) - lookup of LockTable structures using relation,
-database object ids
-<LI>LockTable (xid hash) - lookup of LockTable structures using
-transaction id, LockTable address
+<LI>MultiLevelLockTable (ctl) - <A
+HREF="../../include/storage/lock.h">LOCKCTL</A> control structure for
+each locking method.  Currently, only multi-level locking is used.
+<LI>MultiLevelLockTable (lock hash) - the <A
+HREF="../../include/storage/lock.h">LOCK</A> structure, looked up using
+relation, database object ids(<A
+HREF="../../include/storage/lock.h">LOCKTAG)</A>.  The lock table structure contains the
+lock modes(read, write) and circular linked list of backends (<A
+HREF="../../include/storage/proc.h">PROC</A> structure pointers) waiting
+on the lock.
+<LI>MultiLevelLockTable (xid hash) - lookup of LOCK structure address
+using transaction id, LOCK address.  It is used to quickly check if the
+current transaction already has any locks on a table, rather than having
+to search through all the held locks.  It also stores the modes
+(read/write) of the locks held by the current transaction.  The returned
+<A HREF="../../include/storage/lock.h">XIDLookupEnt</A> structure also
+contains a pointer to the backend's PROC.lockQueue.
 <LI><A HREF="../../include/storage/proc.h">Proc Header</A> - information
-about each backend, including locks held/waiting,  indexed by process id
+about each backend, including locks held/waiting, indexed by process id
 </UL>
 Each data structure is created by calling <A
 HREF="../../backend/storage/ipc/shmem.c">ShmemInitStruct(),</A> and