|
| 1 | +<!-- doc/src/sgml/test-shm-mq.sgml --> |
| 2 | + |
| 3 | +<sect1 id="test-shm-mq" xreflabel="test_shm_mq"> |
| 4 | + <title>test_shm_mq</title> |
| 5 | + |
| 6 | + <indexterm zone="test-shm-mq"> |
| 7 | + <primary>test_shm_mq</primary> |
| 8 | + </indexterm> |
| 9 | + |
| 10 | + <para> |
| 11 | + <filename>test_shm_mq</> is an example of how to use dynamic shared memory |
| 12 | + and the shared memory message queue facilities to coordinate a user backend |
| 13 | + with the efforts of one or more background workers. It is not intended to |
| 14 | + do anything useful on its own; rather, it is a demonstration of how these |
| 15 | + facilities can be used, and a unit test of those facilities. |
| 16 | + </para> |
| 17 | + |
| 18 | + <para> |
| 19 | + The function is this extension send the same message repeatedly through |
| 20 | + a loop of processes. The message payload, the size of the message queue |
| 21 | + through which it is sent, and the number of processes in the loop are |
| 22 | + configurable. At the end, the message may be verified to ensure that it |
| 23 | + has not been corrupted in transmission. |
| 24 | + </para> |
| 25 | + |
| 26 | + <sect2> |
| 27 | + <title>Functions</title> |
| 28 | + |
| 29 | +<synopsis> |
| 30 | +test_shm_mq(queue_size int8, message text, |
| 31 | + repeat_count int4 default 1, num_workers int4 default 1) |
| 32 | + RETURNS void |
| 33 | +</synopsis> |
| 34 | + |
| 35 | + <para> |
| 36 | + This function sends and receives messages synchronously. The user |
| 37 | + backend sends the provided message to the first background worker using |
| 38 | + a message queue of the given size. The first background worker sends |
| 39 | + the message to the second background worker, if the number of workers |
| 40 | + is greater than one, and so forth. Eventually, the last background |
| 41 | + worker sends the message back to the user backend. If the repeat count |
| 42 | + is greater than one, the user backend then sends the message back to |
| 43 | + the first worker. Once the message has been send and received by all |
| 44 | + the coordinating processes a number of times equal to the repeat count, |
| 45 | + the user backend verifies that the message finally received matches the |
| 46 | + one originally sent and throws an error if not. |
| 47 | + </para> |
| 48 | + |
| 49 | +<synopsis> |
| 50 | +test_shm_mq_pipelined(queue_size int8, message text, |
| 51 | + repeat_count int4 default 1, num_workers int4 default 1, |
| 52 | + verify bool default true) |
| 53 | + RETURNS void |
| 54 | +</synopsis> |
| 55 | + |
| 56 | + <para> |
| 57 | + This function sends the same message multiple times, as specified by the |
| 58 | + repeat count, to the first background worker using a queue of the given |
| 59 | + size. These messages are then forwarded to each background worker in |
| 60 | + turn, in each case using a queue of the given size. Finally, the last |
| 61 | + background worker sends the messages back to the user backend. The user |
| 62 | + backend uses non-blocking sends and receives, so that it may begin receiving |
| 63 | + copies of the message before it has finished sending all copies of the |
| 64 | + message. The <literal>verify</> argument controls whether or not the |
| 65 | + received copies are checked against the message that was sent. (This |
| 66 | + takes nontrivial time so it may be useful to disable it for benchmarking |
| 67 | + purposes.) |
| 68 | + </para> |
| 69 | + |
| 70 | + </sect2> |
| 71 | +</sect1> |