The SEND statement sends a message to other threads.
General Format
SEND src-item TO { { THREAD dest-thread } ... }
{ LAST THREAD }
{ ALL THREADS }
Syntax Rules
- src-item is a literal or data item.
- dest-thread is a USAGE HANDLE or HANDLE OF THREAD data item.
General Rules
- The SEND statement sends a message containing the data in
src-item to one or more threads. Which threads receive the message depends on the following:
- THREAD dest-thread causes the message to be sent to the thread identified by dest-thread. More than one
dest-thread can be specified.
- LAST THREAD causes the message to be sent to the last thread. See Thread Fundamentals in the
ACUCOBOL-GT User's Guide for a discussion of the last thread.
- ALL THREADS causes the message to be sent to all currently existing threads, except the sending thread.
- The size of the message is equal to the size of src-item.
- The THREAD dest-thread and LAST THREAD options create a directed message. Directed messages are sent to the specified threads
or last thread and are guaranteed to be delivered to the specified threads. Directed messages are held in a queue. If there
is not enough space in the queue to place the message (because of other messages that have not yet been received), the sending
thread suspends until space becomes available in the queue. Messages are received in the order sent. See the listing for
MESSAGE_QUEUE_SIZE runtime configuration variable located in
Appendix H for options on setting the queue size.
- The ALL THREADS option creates a broadcast message. Broadcast messages can be picked up by any thread. Receiving a broadcast
message does not remove it from the message queue, it remains queued to be received by other threads. Broadcast messages are
removed from the queue when either
- all threads have received it, or
- there is not enough space to hold the next broadcast message. In this case, broadcast messages are removed from the queue
(oldest first) until there is enough space to place the new message in the queue. This allows the queue to empty when there
are threads that never look for messages. It also means that a broadcast message may not be delivered to a particular thread
if other broadcast messages are sent before the first is received. To avoid this problem, use broadcast messages sparingly.
- Broadcast messages can be missed under certain circumstances. To track which messages a thread has read, each thread remembers
the number of the last broadcast message it has read. Messages are numbered sequentially starting at one. If a thread skips
an earlier broadcast message (because the message does not meet the thread's delivery requirements) and then receives a later
broadcast message, the earlier message will never be received because it has an earlier message number. For example, MESSAGE-1
will be missed in the following sequence of events:
SEND MESSAGE-1 TO ALL THREADS (in thread A)
SEND MESSAGE-2 TO ALL THREADS (in thread B)
RECEIVE MSG-2 FROM THREAD B (in thread C)
RECEIVE MSG-1 FROM ANY THREAD (in thread C)
The last RECEIVE in this example does not receive MESSAGE-1 because it was sent earlier than the last broadcast message it
received (MESSAGE-2 in this case). This is caused by the first RECEIVE which picked up a broadcast message while asking for
messages from a particular thread. To avoid this, pick up broadcast messages with the RECEIVE FROM ANY THREAD phrase. This
will prevent you from skipping a message.