Documentation for test_shm_mq.

Commit 4db3744f1f43554b03d8193da4645a0a5326eb18 added this contrib
module but neglected to document it.  Oops.

doc/src/sgml/contrib.sgml

@@ -141,6 +141,7 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
  &tablefunc;
  &tcn;
  &test-parser;
+ &test-shm-mq;
  &tsearch2;
  &unaccent;
  &uuid-ossp;

doc/src/sgml/filelist.sgml

@@ -144,6 +144,7 @@
 <!ENTITY tablefunc       SYSTEM "tablefunc.sgml">
 <!ENTITY tcn             SYSTEM "tcn.sgml">
 <!ENTITY test-parser     SYSTEM "test-parser.sgml">
+<!ENTITY test-shm-mq     SYSTEM "test-shm-mq.sgml">
 <!ENTITY tsearch2        SYSTEM "tsearch2.sgml">
 <!ENTITY unaccent      SYSTEM "unaccent.sgml">
 <!ENTITY uuid-ossp       SYSTEM "uuid-ossp.sgml">

doc/src/sgml/test-shm-mq.sgml

@@ -0,0 +1,71 @@
+<!-- doc/src/sgml/test-shm-mq.sgml -->
+
+<sect1 id="test-shm-mq" xreflabel="test_shm_mq">
+ <title>test_shm_mq</title>
+
+ <indexterm zone="test-shm-mq">
+  <primary>test_shm_mq</primary>
+ </indexterm>
+
+ <para>
+  <filename>test_shm_mq</> is an example of how to use dynamic shared memory
+  and the shared memory message queue facilities to coordinate a user backend
+  with the efforts of one or more background workers.  It is not intended to
+  do anything useful on its own; rather, it is a demonstration of how these
+  facilities can be used, and a unit test of those facilities.
+ </para>
+
+ <para>
+  The function is this extension send the same message repeatedly through
+  a loop of processes.  The message payload, the size of the message queue
+  through which it is sent, and the number of processes in the loop are
+  configurable.  At the end, the message may be verified to ensure that it
+  has not been corrupted in transmission.
+ </para>
+
+ <sect2>
+  <title>Functions</title>
+
+<synopsis>
+test_shm_mq(queue_size int8, message text,
+            repeat_count int4 default 1, num_workers int4 default 1)
+    RETURNS void
+</synopsis>
+
+  <para>
+   This function sends and receives messages synchronously.  The user
+   backend sends the provided message to the first background worker using
+   a message queue of the given size.  The first background worker sends
+   the message to the second background worker, if the number of workers
+   is greater than one, and so forth.  Eventually, the last background
+   worker sends the message back to the user backend.  If the repeat count
+   is greater than one, the user backend then sends the message back to
+   the first worker.  Once the message has been send and received by all
+   the coordinating processes a number of times equal to the repeat count,
+   the user backend verifies that the message finally received matches the
+   one originally sent and throws an error if not.
+  </para>
+
+<synopsis>
+test_shm_mq_pipelined(queue_size int8, message text,
+                      repeat_count int4 default 1, num_workers int4 default 1,
+                      verify bool default true)
+    RETURNS void
+</synopsis>
+
+  <para>
+   This function sends the same message multiple times, as specified by the
+   repeat count, to the first background worker using a queue of the given
+   size.  These messages are then forwarded to each background worker in
+   turn, in each case using a queue of the given size.  Finally, the last
+   background worker sends the messages back to the user backend.  The user
+   backend uses non-blocking sends and receives, so that it may begin receiving
+   copies of the message before it has finished sending all copies of the
+   message.  The <literal>verify</> argument controls whether or not the
+   received copies are checked against the message that was sent.  (This
+   takes nontrivial time so it may be useful to disable it for benchmarking
+   purposes.)
+  </para>
+
+ </sect2>
+</sect1>