epicsMessageQueue.h

A C++ and a C facility for communication between threads.

Each C function corresponds to one of the C++ methods.

Author: W. Eric Norum

Typedefs

typedef struct epicsMessageQueueOSD *epicsMessageQueueId

Functions

epicsMessageQueueId epicsMessageQueueCreate(unsigned int capacity, unsigned int maximumMessageSize)

Create a message queue.

Parameters:

capacity – Maximum number of messages to queue
maximumMessageSize – Number of bytes of the largest message that may be queued

Returns:

An identifier for the new queue, or 0.

void epicsMessageQueueDestroy(epicsMessageQueueId id): Destroy a message queue, release all its memory.

int epicsMessageQueueTrySend(epicsMessageQueueId id, void *message, unsigned int messageSize)

Try to send a message.

Note

On VxWorks and RTEMS this routine may be called from an interrupt handler.

Returns:: 0 if the message was sent to a receiver or queued for future delivery.
Returns:: -1 if no more messages can be queued or if the message is larger than the queue’s maximum message size.

int epicsMessageQueueSend(epicsMessageQueueId id, void *message, unsigned int messageSize)

Send a message.

Returns:: 0 if the message was sent to a receiver or queued for future delivery.
Returns:: -1 if the message is larger than the queue’s maximum message size.

int epicsMessageQueueSendWithTimeout(epicsMessageQueueId id, void *message, unsigned int messageSize, double timeout)

Send a message or timeout.

Returns:: 0 if the message was sent to a receiver or queued for future delivery.
Returns:: -1 if the timeout was reached before the message could be sent or queued, or if the message is larger than the queue’s maximum message size.

int epicsMessageQueueTryReceive(epicsMessageQueueId id, void *message, unsigned int size)

Try to receive a message.

If the queue holds at least one message, the first message on the queue is moved to the specified location and the length of that message is returned.

If the received message is larger than the specified message size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Returns:: Number of bytes in the message.
Returns:: -1 if the message queue is empty, or the buffer too small.

int epicsMessageQueueReceive(epicsMessageQueueId id, void *message, unsigned int size)

Fetch the next message on the queue.

Wait for a message to be sent if the queue is empty, then move the first message queued to the specified location.

If the received message is larger than the specified message size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Returns:: Number of bytes in the message.
Returns:: -1 if the buffer is too small for the message.

int epicsMessageQueueReceiveWithTimeout(epicsMessageQueueId id, void *message, unsigned int size, double timeout)

Wait for a message to be queued.

Wait up to timeout seconds for a message to be sent if the queue is empty, then move the first message to the specified location.

If the received message is larger than the specified message buffer size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Returns:: Number of bytes in the message.
Returns:: -1 if a message is not received within the timeout interval.

int epicsMessageQueuePending(epicsMessageQueueId id)

How many messages are queued.

Parameters:: id – Message queue identifier.
Returns:: The number of messages presently in the queue.

void epicsMessageQueueShow(epicsMessageQueueId id, int level)

Displays some information about the message queue.

Parameters:

id – Message queue identifier.
level – Controls the amount of information displayed.

class epicsMessageQueue

#include <epicsMessageQueue.h>

Provides methods for sending messages between threads on a first in, first out basis. It is designed so that a single message queue can be used with multiple writer and reader threads.

A C++ epicsMessageQueue cannot be assigned to, copy-constructed, or constructed without giving the capacity and max-imumMessageSize arguments.

The C++ compiler will object to some of the statements below:

epicsMessageQueue mq0();   // Error: default constructor is private
epicsMessageQueue mq1(10, 20); // OK
epicsMessageQueue mq2(t1); // Error: copy constructor is private
epicsMessageQueue*pmq;    // OK, pointer
*pmq = mq1;               // Error: assignment operator is private
pmq = &mq1;               // OK, pointer assignment and address-of

Public Functions

epicsMessageQueue(unsigned int capacity, unsigned int maximumMessageSize)

Constructor.

Parameters:

capacity – Maximum number of messages to queue
maximumMessageSize – Number of bytes of the largest message that may be queued

~epicsMessageQueue(): Destructor.

int trySend(void *message, unsigned int messageSize)

Try to send a message.

Note

On VxWorks and RTEMS this method may be called from an interrupt handler.

Returns:: 0 if the message was sent to a receiver or queued for future delivery.
Returns:: -1 if no more messages can be queued or if the message is larger than the queue’s maximum message size.

int send(void *message, unsigned int messageSize)

Send a message.

Returns:: 0 if the message was sent to a receiver or queued for future delivery.
Returns:: -1 if the message is larger than the queue’s maximum message size.

int send(void *message, unsigned int messageSize, double timeout)

Send a message or timeout.

Parameters:

message – Pointer to the message to be sent
messageSize – The size of message
timeout – The timeout delay in seconds. A timeout of zero is equivalent to calling trySend(); NaN or any value too large to be represented to the target OS is equivalent to no timeout.

Returns:

0 if the message was sent to a receiver or queued for future delivery.

Returns:

-1 if the timeout was reached before the message could be sent or queued, or if the message is larger than the queue’s maximum message size.

int tryReceive(void *message, unsigned int size)

Try to receive a message.

If the queue holds at least one message, the first message on the queue is moved to the specified location and the length of that message is returned.

If the received message is larger than the specified message size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Parameters:

message – [out] Output buffer to store the received message
size – Size of the buffer pointed to by message

Returns:

Number of bytes in the message.

Returns:

-1 if the message queue is empty, or the buffer too small.

int receive(void *message, unsigned int size)

Fetch the next message on the queue.

Wait for a message to be sent if the queue is empty, then move the first message queued to the specified location.

If the received message is larger than the specified message size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Parameters:

message – [out] Output buffer to store the received message
size – Size of the buffer pointed to by message

Returns:

Number of bytes in the message.

Returns:

-1 if the buffer is too small for the message.

int receive(void *message, unsigned int size, double timeout)

Wait for and fetch the next message.

Waits up to timeout seconds for a message to arrive if the queue is empty, then moves the first message to the message buffer.

If the received message is larger than the buffer size the implementation may either return -1, or truncate the message. It is most efficient if the messageBufferSize is equal to the maximumMessageSize with which the message queue was created.

Parameters:

message – [out] Output buffer to store the received message
size – Size of the buffer pointed to by message
timeout – The timeout delay in seconds. A timeout of zero is equivalent to calling tryReceive(); NaN or any value too large to be represented to the target OS is equivalent to no timeout.

Returns:

Number of bytes in the message.

Returns:

-1 if a message is not received within the timeout interval.

void show(unsigned int level = 0)

Displays some information about the message queue.

Parameters:: level – Controls the amount of information displayed.

unsigned int pending()

How many messages are queued.

Returns:: The number of messages presently in the queue.

Private Functions

epicsMessageQueue(): Prevent compiler-generated member functions default constructor, copy constructor, assignment operator.

epicsMessageQueue(const epicsMessageQueue&)

epicsMessageQueue &operator=(const epicsMessageQueue&)

Private Members

epicsMessageQueueId id