VxWorks Reference Manual : Libraries
msgQDistLib - distributed objects message queue library (VxFusion)
msgQDistCreate( ) - create a distributed message queue
msgQDistSend( ) - send a message to a distributed message queue
msgQDistReceive( ) - receive a message from a distributed message queue
msgQDistNumMsgs( ) - get the number of messages in a distributed message queue
This library provides the interface to distributed message queues. Any task on any node in the system can send messages to or receive from a distributed messsage queue. Full duplex communication between two tasks generally requires two distributed messsage queues, one for each direction.
Distributed messsage queues are created with msgQDistCreate( ). After creation, they can be manipulated using the generic routines for local message queues; for more information on the use of these routines, see the manual entry for msgQLib. The msgQDistLib library also provides the msgQDistSend( ), msgQDistReceive( ), and msgQDistNumMsgs( ) routines which support additional parameters that are useful for working with distributed message queues.
The distributed objects message queue library is initialized by calling distInit( ).
msgQDistLib.h
msgQDistLib, msgQLib, msgQDistShow, distLib
msgQDistCreate( ) - create a distributed message queue
MSG_Q_ID msgQDistCreate ( int maxMsgs, /* max messages that can be queued */ int maxMsgLength, /* max bytes in a message */ int options /* message queue options */ )
This routine creates a distributed message queue capable of holding up to maxMsgs messages, each up to maxMsgLength bytes long. This routine returns a message queue ID used to identify the created message queue. The queue can be created with the following options:
- MSG_Q_FIFO (0x00)
- The queue pends tasks in FIFO order.
- MSG_Q_PRIORITY (0x01)
- The queue pends tasks in priority order. Remote tasks share the same priority level.
The global message queue identifier returned can be used directly by generic message queue handling routines in msgQLib, such as, msgQSend( ), msgQReceive( ), and msgQNumMsgs( ).
MSG_Q_ID, or NULL if there is an error.
- S_memLib_NOT_ENOUGH_MEMORY
- If the routine is unable to allocate memory for message queues and message buffers.
- S_intLib_NOT_ISR_CALLABLE
- If the routine is called from an interrupt service routine.
- S_msgQLib_INVALID_QUEUE_TYPE
- If the type of queue is invalid.
- S_msgQDistLib_INVALID_MSG_LENGTH
- If the message is too long for the VxFusion network layer.
msgQDistSend( ) - send a message to a distributed message queue
STATUS msgQDistSend ( MSG_Q_ID msgQId, /* message queue on which to send */ char * buffer, /* message to send */ UINT nBytes, /* length of message */ int msgQTimeout, /* ticks to wait at message queue */ int overallTimeout, /* ticks to wait overall */ int priority /* priority */ )
This routine sends the message specified by buffer of length nBytes to the distributed message queue or group specified by msgQId.
The argument msgQTimeout specifies the time in ticks to wait for the queuing of the message. The argument overallTimeout specifies the time in ticks to wait for both the sending and queuing of the message. While it is an error to set overallTimeout to NO_WAIT (0), WAIT_FOREVER (-1) is allowed for both msgQTimeout and overallTimeout.
The priority parameter specifies the priority of the message being sent. It ranges between DIST_MSG_PRI_0 (highest priority) and DIST_MSG_PRI_7 (lowest priority). A priority of MSG_PRI_URGENT is mapped to DIST_MSG_PRI_0; MSG_PRI_NORMAL is mapped to DIST_MSG_PRI_4. Messages sent with high priorities (DIST_MSG_PRI_0 to DIST_MSG_PRI_3) are put to the head of the list of queued messages. Lower priority messages (DIST_MSG_PRI_4 to DIST_MSG_PRI_7) are placed at the queue's tail.
When msgQDistSend( ) is called through msgQSend( ), msgQTimeout is set to timeout and overallTimeout to WAIT_FOREVER.
OK, or ERROR if the operation fails.
- S_distLib_OBJ_ID_ERROR
- The argument msgQId is invalid.
- S_distLib_UNREACHABLE
- Could not establish communications with the remote node.
- S_msgQDistLib_INVALID_PRIORITY
- The argument priority is invalid.
- S_msgQDistLib_INVALID_TIMEOUT
- The argument overallTimeout is NO_WAIT.
- S_msgQDistLib_RMT_MEMORY_SHORTAGE
- There is not enough memory on the remote node.
- S_objLib_OBJ_UNAVAILABLE
- The argument msgQTimeout is set to NO_WAIT, and the queue is full.
- S_objLib_OBJ_TIMEOUT
- The queue is full for msgQTimeout ticks.
- S_msgQLib_INVALID_MSG_LENGTH
- The argument nBytes is larger than the maxMsgLength set for the message queue.
- S_msgQDistLib_OVERALL_TIMEOUT
- There was no response from the remote side in overallTimeout ticks.
msgQDistReceive( ) - receive a message from a distributed message queue
int msgQDistReceive ( MSG_Q_ID msgQId, /* message queue from which to receive */ char * buffer, /* buffer to receive message */ UINT maxNBytes, /* length of buffer */ int msgQTimeout, /* ticks to wait at the message queue */ int overallTimeout /* ticks to wait overall */ )
This routine receives a message from the distributed message queue specified by msgQId. The received message is copied into the specified buffer, 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 argument msgQTimeout specifies the time in ticks to wait for the queuing of the message. The argument overallTimeout specifies the time in ticks to wait for both the sending and queuing of the message. While it is an error to set overallTimeout to NO_WAIT (0), WAIT_FOREVER (-1) is allowed for both msgQTimeout and overallTimeout.
Calling msgQDistReceive( ) on a distributed message group returns an error.
When msgQDistReceive( ) is called through msgQReceive( ), msgQTimeout is set to timeout and overallTimeout to WAIT_FOREVER.
The number of bytes copied to buffer, or ERROR.
- S_distLib_OBJ_ID_ERROR
- The argument msgQId is invalid.
- S_distLib_UNREACHABLE
- Could not establish communications with the remote node.
- S_msgQLib_INVALID_MSG_LENGTH
- The argument maxNBytes is less than 0.
- S_msgQDistLib_INVALID_TIMEOUT
- The argument overallTimeout is NO_WAIT.
- S_msgQDistLib_RMT_MEMORY_SHORTAGE
- There is not enough memory on the remote node.
- S_objLib_OBJ_UNAVAILABLE
- The argument msgQTimeout is set to NO_WAIT, and no messages are available.
- S_objLib_OBJ_TIMEOUT
- No messages were received in msgQTimeout ticks.
- S_msgQDistLib_OVERALL_TIMEOUT
- There was no response from the remote side in overallTimeout ticks.
msgQDistNumMsgs( ) - get the number of messages in a distributed message queue
int msgQDistNumMsgs ( MSG_Q_ID msgQId, /* message queue to examine */ int overallTimeout /* ticks to wait overall */ )
This routine returns the number of messages currently queued to a specified distributed message queue.
When msgQDistNumMsgs( ) is called through msgQNumMsgs( ), overallTimeout is set to WAIT_FOREVER. You cannot set overallTimeout to NO_WAIT (0) because the process of sending a message from the local node to the remote node always takes a finite amount of time.
The number of messages queued, or ERROR if the operation fails.
- S_distLib_OBJ_ID_ERROR
- The argument msgQId is invalid.
- S_distLib_UNREACHABLE
- Could not establish communications with the remote node.
- S_msgQDistLib_INVALID_TIMEOUT
- The argument overallTimeout is NO_WAIT.