Implement sharable row-level locks, and use them for foreign key references

to eliminate unnecessary deadlocks.  This commit adds SELECT ... FOR SHARE
paralleling SELECT ... FOR UPDATE.  The implementation uses a new SLRU
data structure (managed much like pg_subtrans) to represent multiple-
transaction-ID sets.  When more than one transaction is holding a shared
lock on a particular row, we create a MultiXactId representing that set
of transactions and store its ID in the row's XMAX.  This scheme allows
an effectively unlimited number of row locks, just as we did before,
while not costing any extra overhead except when a shared lock actually
has to be shared.   Still TODO: use the regular lock manager to control
the grant order when multiple backends are waiting for a row lock.

Alvaro Herrera and Tom Lane.

doc/src/sgml/ref/pg_resetxlog.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.9 2004/12/20 01:42:09 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.10 2005/04/28 21:47:10 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -22,6 +22,7 @@ PostgreSQL documentation
    <arg> -n </arg>
    <arg> -o <replaceable class="parameter">oid</replaceable> </arg>
    <arg> -x <replaceable class="parameter">xid</replaceable> </arg>
+   <arg> -m <replaceable class="parameter">mxid</replaceable> </arg>
    <arg> -l <replaceable class="parameter">timelineid</replaceable>,<replaceable class="parameter">fileid</replaceable>,<replaceable class="parameter">seg</replaceable> </arg>
    <arg choice="plain"><replaceable>datadir</replaceable></arg>
   </cmdsynopsis>
@@ -73,34 +74,65 @@ PostgreSQL documentation
   </para>
 
   <para>
-   The <literal>-o</>, <literal>-x</>, and <literal>-l</> switches allow
-   the next OID, next transaction ID, and WAL starting address values to
+   The <literal>-o</>, <literal>-x</>, <literal>-m</>, and <literal>-l</>
+   switches allow the next OID, next transaction ID, next multi-transaction
+   ID, and WAL starting address values to
    be set manually.  These are only needed when
    <command>pg_resetxlog</command> is unable to determine appropriate values
-   by reading <filename>pg_control</>.  A safe value for the
-   next transaction ID may be determined by looking for the numerically largest
-   file name in the directory <filename>pg_clog</> under the data directory,
-   adding one,
-   and then multiplying by 1048576.  Note that the file names are in
-   hexadecimal.  It is usually easiest to specify the switch value in
-   hexadecimal too. For example, if <filename>0011</> is the largest entry
-   in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five trailing
-   zeroes provide the proper multiplier).
-   The WAL starting address should be
-   larger than any file name currently existing in
-   the directory <filename>pg_xlog</> under the data directory.
-   These names are also in hexadecimal and have three parts.  The first
-   part is the <quote>timeline ID</> and should usually be kept the same.
-   Do not choose a value larger than 255 (<literal>0xFF</>) for the third
-   part; instead increment the second part and reset the third part to 0.
-   For example, if <filename>00000001000000320000004A</> is the
-   largest entry in <filename>pg_xlog</>, <literal>-l 0x1,0x32,0x4B</> will
-   work; but if the largest entry is
-   <filename>000000010000003A000000FF</>, choose <literal>-l 0x1,0x3B,0x0</>
-   or more.
-   There is no comparably easy way to determine a next OID that's beyond
-   the largest one in the database, but fortunately it is not critical to
-   get the next-OID setting right.
+   by reading <filename>pg_control</>.  Safe values may be determined as
+   follows:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      A safe value for the next transaction ID (<literal>-x</>)
+      may be determined by looking for the numerically largest
+      file name in the directory <filename>pg_clog</> under the data directory,
+      adding one,
+      and then multiplying by 1048576.  Note that the file names are in
+      hexadecimal.  It is usually easiest to specify the switch value in
+      hexadecimal too. For example, if <filename>0011</> is the largest entry
+      in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
+      trailing zeroes provide the proper multiplier).
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      A safe value for the next multi-transaction ID (<literal>-m</>)
+      may be determined by looking for the numerically largest
+      file name in the directory <filename>pg_multixact/offsets</> under the
+      data directory, adding one, and then multiplying by 65536.  As above,
+      the file names are in hexadecimal, so the easiest way to do this is to
+      specify the switch value in hexadecimal and add four zeroes.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The WAL starting address (<literal>-l</>) should be
+      larger than any file name currently existing in
+      the directory <filename>pg_xlog</> under the data directory.
+      These names are also in hexadecimal and have three parts.  The first
+      part is the <quote>timeline ID</> and should usually be kept the same.
+      Do not choose a value larger than 255 (<literal>0xFF</>) for the third
+      part; instead increment the second part and reset the third part to 0.
+      For example, if <filename>00000001000000320000004A</> is the
+      largest entry in <filename>pg_xlog</>, <literal>-l 0x1,0x32,0x4B</> will
+      work; but if the largest entry is
+      <filename>000000010000003A000000FF</>, choose <literal>-l 0x1,0x3B,0x0</>
+      or more.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      There is no comparably easy way to determine a next OID that's beyond
+      the largest one in the database, but fortunately it is not critical to
+      get the next-OID setting right.
+     </para>
+    </listitem>
+   </itemizedlist>
   </para>
 
   <para>