diff options
| -rw-r--r-- | doc/src/sgml/contrib.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/test-shm-mq.sgml | 71 |
3 files changed, 73 insertions, 0 deletions
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 2892fa11670..0195916dbfd 100644 --- a/doc/src/sgml/contrib.sgml +++ b/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; diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 552c3aab2d7..09de4bd0518 100644 --- a/doc/src/sgml/filelist.sgml +++ b/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"> diff --git a/doc/src/sgml/test-shm-mq.sgml b/doc/src/sgml/test-shm-mq.sgml new file mode 100644 index 00000000000..32693778a3c --- /dev/null +++ b/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> |