VxWorks Reference Manual : Libraries
msgQLib - message queue library
msgQCreate( ) - create and initialize a message queue
msgQDelete( ) - delete a message queue
msgQSend( ) - send a message to a message queue
msgQReceive( ) - receive a message from a message queue
msgQNumMsgs( ) - get the number of messages queued to a message queue
This library contains routines for creating and using message queues, the primary intertask communication mechanism within a single CPU. Message queues allow a variable number of messages (varying in length) to be queued in first-in-first-out (FIFO) order. Any task or interrupt service routine can send messages to a message queue. Any task can receive messages from a message queue. Multiple tasks can send to and receive from the same message queue. Full-duplex communication between two tasks generally requires two message queues, one for each direction.
A message queue is created with msgQCreate( ). Its parameters specify the maximum number of messages that can be queued to that message queue and the maximum length in bytes of each message. Enough buffer space will be pre-allocated to accommodate the specified number of messages of specified length.
A task or interrupt service routine sends a message to a message queue with msgQSend( ). If no tasks are waiting for messages on the message queue, the message is simply added to the buffer of messages for that queue. If any tasks are already waiting to receive a message from the message queue, the message is immediately delivered to the first waiting task.
A task receives a message from a message queue with msgQReceive( ). If any messages are already available in the message queue's buffer, the first message is immediately dequeued and returned to the caller. If no messages are available, the calling task will block and be added to a queue of tasks waiting for messages. This queue of waiting tasks can be ordered either by task priority or FIFO, as specified in an option parameter when the queue is created.
Both msgQSend( ) and msgQReceive( ) take timeout parameters. When sending a message, if no buffer space is available to queue the message, the timeout specifies how many ticks to wait for space to become available. When receiving a message, the timeout specifies how many ticks to wait if no message is immediately available. The timeout parameter can have the special values NO_WAIT (0) or WAIT_FOREVER (-1). NO_WAIT means the routine should return immediately; WAIT_FOREVER means the routine should never time out.
The msgQSend( ) routine allows the priority of a message to be specified as either normal or urgent, MSG_PRI_NORMAL (0) and MSG_PRI_URGENT (1), respectively. Normal priority messages are added to the tail of the list of queued messages, while urgent priority messages are added to the head of the list.
msgQLib.h
msgQLib, pipeDrv, msgQSmLib, VxWorks Programmer's Guide: Basic OS
msgQCreate( ) - create and initialize a message queue
MSG_Q_ID msgQCreate ( int maxMsgs, /* max messages that can be queued */ int maxMsgLength, /* max bytes in a message */ int options /* message queue options */ )
This routine creates a message queue capable of holding up to maxMsgs messages, each up to maxMsgLength bytes long. The routine returns a message queue ID used to identify the created message queue in all subsequent calls to routines in this library. The queue can be created with the following options:
- MSG_Q_FIFO (0x00)
- queue pended tasks in FIFO order.
- MSG_Q_PRIORITY (0x01)
- queue pended tasks in priority order.
MSG_Q_ID, or NULL if error.
S_memLib_NOT_ENOUGH_MEMORY, S_intLib_NOT_ISR_CALLABLE
msgQDelete( ) - delete a message queue
STATUS msgQDelete ( MSG_Q_ID msgQId /* message queue to delete */ )
This routine deletes a message queue. Any task blocked on either a msgQSend( ) or msgQReceive( ) will be unblocked and receive an error from the call with errno set to S_objLib_OBJECT_DELETED. The msgQId parameter will no longer be a valid message queue ID.
OK or ERROR.
S_objLib_OBJ_ID_ERROR, S_intLib_NOT_ISR_CALLABLE
msgQSend( ) - send a message to a message queue
STATUS msgQSend ( MSG_Q_ID msgQId, /* message queue on which to send */ char * buffer, /* message to send */ UINT nBytes, /* length of message */ int timeout, /* ticks to wait */ int priority /* MSG_PRI_NORMAL or MSG_PRI_URGENT */ )
This routine sends the message in buffer of length nBytes to the message queue msgQId. If any tasks are already waiting to receive messages on the queue, the message will immediately be delivered to the first waiting task. If no task is waiting to receive messages, the message is saved in the message queue.
The timeout parameter specifies the number of ticks to wait for free space if the message queue is full. The timeout parameter can also have the following special values:
- NO_WAIT (0)
- return immediately, even if the message has not been sent.
- WAIT_FOREVER (-1)
- never time out.
The priority parameter specifies the priority of the message being sent. The possible values are:
- MSG_PRI_NORMAL (0)
- normal priority; add the message to the tail of the list of queued messages.
- MSG_PRI_URGENT (1)
- urgent priority; add the message to the head of the list of queued messages.
This routine can be called by interrupt service routines as well as by tasks. This is one of the primary means of communication between an interrupt service routine and a task. When called from an interrupt service routine, timeout must be NO_WAIT.
OK or ERROR.
S_distLib_NOT_INITIALIZED, S_objLib_OBJ_ID_ERROR,
S_objLib_OBJ_DELETED, S_objLib_OBJ_UNAVAILABLE,
S_objLib_OBJ_TIMEOUT, S_msgQLib_INVALID_MSG_LENGTH,
S_msgQLib_NON_ZERO_TIMEOUT_AT_INT_LEVEL
msgQReceive( ) - receive a message from a message queue
int msgQReceive ( MSG_Q_ID msgQId, /* message queue from which to receive */ char * buffer, /* buffer to receive message */ UINT maxNBytes, /* length of buffer */ int timeout /* ticks to wait */ )
This routine receives a message from the message queue msgQId. The received message is copied into the specified buffer, which is maxNBytes in length. If the message is longer than maxNBytes, the remainder of the message is discarded (no error indication is returned).
The timeout parameter specifies the number of ticks to wait for a message to be sent to the queue, if no message is available when msgQReceive( ) is called. The timeout parameter can also have the following special values:
- NO_WAIT (0)
- return immediately, even if the message has not been sent.
- WAIT_FOREVER (-1)
- never time out.
This routine must not be called by interrupt service routines.
The number of bytes copied to buffer, or ERROR.
S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,
S_objLib_OBJ_ID_ERROR, S_objLib_OBJ_DELETED,
S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_TIMEOUT,
S_msgQLib_INVALID_MSG_LENGTH
msgQNumMsgs( ) - get the number of messages queued to a message queue
int msgQNumMsgs ( MSG_Q_ID msgQId /* message queue to examine */ )
This routine returns the number of messages currently queued to a specified message queue.
The number of messages queued, or ERROR.
S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,
S_objLib_OBJ_ID_ERROR