epicsMessageQueue.h File Reference

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

#include "epicsAssert.h"
#include "libComAPI.h"
#include "osdMessageQueue.h"

Include dependency graph for epicsMessageQueue.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct epicsMessageQueueOSD *	epicsMessageQueueId

Functions
LIBCOM_API epicsMessageQueueId epicsStdCall	epicsMessageQueueCreate (unsigned int capacity, unsigned int maximumMessageSize)
	Create a message queue. More...
LIBCOM_API void epicsStdCall	epicsMessageQueueDestroy (epicsMessageQueueId id)
	Destroy a message queue, release all its memory. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueTrySend (epicsMessageQueueId id, void *message, unsigned int messageSize)
	Try to send a message. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueSend (epicsMessageQueueId id, void *message, unsigned int messageSize)
	Send a message. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueSendWithTimeout (epicsMessageQueueId id, void *message, unsigned int messageSize, double timeout)
	Send a message or timeout. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueTryReceive (epicsMessageQueueId id, void *message, unsigned int size)
	Try to receive a message. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueReceive (epicsMessageQueueId id, void *message, unsigned int size)
	Fetch the next message on the queue. More...
LIBCOM_API int epicsStdCall	epicsMessageQueueReceiveWithTimeout (epicsMessageQueueId id, void *message, unsigned int size, double timeout)
	Wait for a message to be queued. More...
LIBCOM_API int epicsStdCall	epicsMessageQueuePending (epicsMessageQueueId id)
	How many messages are queued. More...
LIBCOM_API void epicsStdCall	epicsMessageQueueShow (epicsMessageQueueId id, int level)
	Displays some information about the message queue. More...

Detailed Description

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

Author

W. Eric Norum

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

Definition in file epicsMessageQueue.h.

Typedef Documentation

typedef struct epicsMessageQueueOSD* epicsMessageQueueId

Definition at line 26 of file epicsMessageQueue.h.

Function Documentation

LIBCOM_API epicsMessageQueueId epicsStdCall 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.

Definition at line 69 of file osdMessageQueue.cpp.

{
    epicsMessageQueueId pmsg;
    unsigned int slotBytes, slotLongs;

    if(capacity == 0)
        return NULL;

    pmsg = (epicsMessageQueueId)calloc(1, sizeof(*pmsg));
    if(!pmsg)
        return NULL;

    pmsg->capacity = capacity;
    pmsg->maxMessageSize = maxMessageSize;
    slotLongs = 1 + ((maxMessageSize + sizeof(unsigned long) - 1) / sizeof(unsigned long));
    slotBytes = slotLongs * sizeof(unsigned long);

    pmsg->mutex = epicsMutexCreate();
    pmsg->buf = (unsigned long*)calloc(pmsg->capacity, slotBytes);
    if(!pmsg->buf || !pmsg->mutex) {
        if(pmsg->mutex)
            epicsMutexDestroy(pmsg->mutex);
        free(pmsg->buf);
        free(pmsg);
        return NULL;
    }

    pmsg->inPtr = pmsg->outPtr = pmsg->firstMessageSlot = (char *)&pmsg->buf[0];
    pmsg->lastMessageSlot = (char *)&pmsg->buf[(capacity - 1) * slotLongs];
    pmsg->full = false;
    pmsg->slotSize = slotBytes;

    ellInit(&pmsg->sendQueue);
    ellInit(&pmsg->receiveQueue);
    ellInit(&pmsg->eventFreeList);
    return pmsg;
}

LIBCOM_API void epicsStdCall epicsMessageQueueDestroy

(

epicsMessageQueueId

id

)

Destroy a message queue, release all its memory.

Definition at line 117 of file osdMessageQueue.cpp.

{
    struct eventNode *evp;

    while ((evp = reinterpret_cast < struct eventNode * >
            ( ellGet(&pmsg->eventFreeList) ) ) != NULL) {
        destroyEventNode(evp);
    }
    epicsMutexDestroy(pmsg->mutex);
    free(pmsg->buf);
    free(pmsg);
}

LIBCOM_API int epicsStdCall epicsMessageQueuePending

(

epicsMessageQueueId

id

)

How many messages are queued.

Parameters

id	Message queue identifier.

Returns

The number of messages presently in the queue.

Definition at line 398 of file osdMessageQueue.cpp.

{
    char *myInPtr, *myOutPtr;
    int nmsg;

    epicsMutexMustLock(pmsg->mutex);
    myInPtr = (char *)pmsg->inPtr;
    myOutPtr = (char *)pmsg->outPtr;
    if (pmsg->full)
        nmsg = pmsg->capacity;
    else if (myInPtr >= myOutPtr)
        nmsg = (myInPtr - myOutPtr) / pmsg->slotSize;
    else
        nmsg = pmsg->capacity  - (myOutPtr - myInPtr) / pmsg->slotSize;
    epicsMutexUnlock(pmsg->mutex);
    return nmsg;
}

LIBCOM_API int epicsStdCall 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.

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

Definition at line 384 of file osdMessageQueue.cpp.

{
    return myReceive(pmsg, message, size, -1);
}

LIBCOM_API int epicsStdCall 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.

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

Definition at line 391 of file osdMessageQueue.cpp.

{
    return myReceive(pmsg, message, size, timeout);
}

LIBCOM_API int epicsStdCall 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.

-1 if the message is larger than the queue's maximum message size.

Definition at line 263 of file osdMessageQueue.cpp.

{
    return mySend(pmsg, message, size, -1);
}

LIBCOM_API int epicsStdCall 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.

-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.

Definition at line 270 of file osdMessageQueue.cpp.

{
    return mySend(pmsg, message, size, timeout);
}

LIBCOM_API void epicsStdCall epicsMessageQueueShow	(	epicsMessageQueueId	id,
		int	level
	)

Displays some information about the message queue.

Parameters

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

Definition at line 417 of file osdMessageQueue.cpp.

{
    printf("Message Queue Used:%d  Slots:%lu",
        epicsMessageQueuePending(pmsg), pmsg->capacity);
    if (level >= 1)
        printf("  Maximum size:%lu", pmsg->maxMessageSize);
    printf("\n");
}

LIBCOM_API int epicsStdCall 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.

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

Definition at line 377 of file osdMessageQueue.cpp.

{
    return myReceive(pmsg, message, size, 0);
}

LIBCOM_API int epicsStdCall 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.

-1 if no more messages can be queued or if the message is larger than the queue's maximum message size.

Definition at line 256 of file osdMessageQueue.cpp.

{
    return mySend(pmsg, message, size, 0);
}