Create a standard function pg_sleep() to sleep for a specified amount of time.

Replace the former ad-hoc implementation used in the regression tests.
Joachim Wieland

doc/src/sgml/func.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.301 2005/12/28 01:29:58 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.302 2006/01/11 20:12:38 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -6170,6 +6170,56 @@ SELECT TIMESTAMP 'now';  -- incorrect for use with DEFAULT
      </para>
     </tip>
   </sect2>
+
+  <sect2 id="functions-datetime-delay">
+   <title>Delaying Execution</title>
+
+   <indexterm>
+    <primary>pg_sleep</primary>
+   </indexterm>
+   <indexterm>
+    <primary>sleep</primary>
+   </indexterm>
+   <indexterm>
+    <primary>delay</primary>
+   </indexterm>
+
+   <para>
+    The following function is available to delay execution of the server
+    process:
+<synopsis>
+pg_sleep(<replaceable>seconds</replaceable>)
+</synopsis>
+
+    <function>pg_sleep</function> makes the current session's process
+    sleep until <replaceable>seconds</replaceable> seconds have
+    elapsed.  <replaceable>seconds</replaceable> is a value of type
+    <type>double precision</>, so fractional-second delays can be specified.
+    For example:
+
+<programlisting>
+SELECT pg_sleep(1.5);
+</programlisting>
+   </para>
+
+   <note>
+     <para>
+      The effective resolution of the sleep interval is platform-specific;
+      0.01 seconds is a common value.  The sleep delay will be at least as long
+      as specified. It may be longer depending on factors such as server load.
+     </para>
+   </note>
+
+   <warning>
+     <para>
+      Make sure that your session does not hold more locks than necessary
+      when calling <function>pg_sleep</function>.  Otherwise other sessions
+      might have to wait for your sleeping process, slowing down the entire
+      system.
+     </para>
+   </warning>
+  </sect2>
+
  </sect1>