From 16cad3e8674777d3e0bedbc1e1c408b0448d0545 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Tue, 14 Jan 2014 15:58:15 -0500 Subject: [PATCH] Documentation for test_shm_mq. Commit 4db3744f1f43554b03d8193da4645a0a5326eb18 added this contrib module but neglected to document it. Oops. --- doc/src/sgml/contrib.sgml | 1 + doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/test-shm-mq.sgml | 71 +++++++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+) create mode 100644 doc/src/sgml/test-shm-mq.sgml diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 2892fa1167..0195916dbf 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -141,6 +141,7 @@ CREATE EXTENSION 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 552c3aab2d..09de4bd051 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -144,6 +144,7 @@ + diff --git a/doc/src/sgml/test-shm-mq.sgml b/doc/src/sgml/test-shm-mq.sgml new file mode 100644 index 0000000000..32693778a3 --- /dev/null +++ b/doc/src/sgml/test-shm-mq.sgml @@ -0,0 +1,71 @@ + + + + test_shm_mq + + + test_shm_mq + + + + 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. + + + + 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. + + + + Functions + + +test_shm_mq(queue_size int8, message text, + repeat_count int4 default 1, num_workers int4 default 1) + RETURNS void + + + + 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. + + + +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 + + + + 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 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.) + + + + -- 2.40.0