VxWorks Reference Manual : Libraries
msgQShow - message queue show routines
msgQShowInit( ) - initialize the message queue show facility
msgQInfoGet( ) - get information about a message queue
msgQShow( ) - show information about a message queue
This library provides routines to show message queue statistics, such as the task queuing method, messages queued, receivers blocked, etc.
The routine msgQshowInit( ) links the message queue show facility into the VxWorks system. It is called automatically when the message queue show facility is configured into VxWorks using either of the following methods:
- If you use the configuration header files, define INCLUDE_SHOW_ROUTINES in config.h.
- If you use the Tornado project facility, select INCLUDE_MSG_Q_SHOW.
msgQLib.h
msgQShow, pipeDrv, VxWorks Programmer's Guide: Basic OS
msgQShowInit( ) - initialize the message queue show facility
void msgQShowInit (void)
This routine links the message queue show facility into the VxWorks system. It is called automatically when the message queue show facility is configured into VxWorks using either of the following methods:
- If you use the configuration header files, define INCLUDE_SHOW_ROUTINES in config.h.
- If you use the Tornado project facility, select INCLUDE_MSG_Q_SHOW.
N/A
msgQInfoGet( ) - get information about a message queue
STATUS msgQInfoGet ( MSG_Q_ID msgQId, /* message queue to query */ MSG_Q_INFO * pInfo /* where to return msg info */ )
This routine gets information about the state and contents of a message queue. The parameter pInfo is a pointer to a structure of type MSG_Q_INFO defined in msgQLib.h as follows:
typedef struct /* MSG_Q_INFO */ { int numMsgs; /* OUT: number of messages queued */ int numTasks; /* OUT: number of tasks waiting on msg q */ int sendTimeouts; /* OUT: count of send timeouts */ int recvTimeouts; /* OUT: count of receive timeouts */ int options; /* OUT: options with which msg q was created */ int maxMsgs; /* OUT: max messages that can be queued */ int maxMsgLength; /* OUT: max byte length of each message */ int taskIdListMax; /* IN: max tasks to fill in taskIdList */ int * taskIdList; /* PTR: array of task IDs waiting on msg q */ int msgListMax; /* IN: max msgs to fill in msg lists */ char ** msgPtrList; /* PTR: array of msg ptrs queued to msg q */ int * msgLenList; /* PTR: array of lengths of msgs */ } MSG_Q_INFO;If a message queue is empty, there may be tasks blocked on receiving. If a message queue is full, there may be tasks blocked on sending. This can be determined as follows:
- If numMsgs is 0, then numTasks indicates the number of tasks blocked on receiving.
- If numMsgs is equal to maxMsgs, then numTasks is the number of tasks blocked on sending.
- If numMsgs is greater than 0 but less than maxMsgs, then numTasks will be 0.
A list of pointers to the messages queued and their lengths can be obtained by setting msgPtrList and msgLenList to the addresses of arrays to receive the respective lists, and setting msgListMax to the maximum number of elements in those arrays. If either list pointer is NULL, no data will be returned for that array.
No more than msgListMax message pointers and lengths are returned, although numMsgs will always be returned with the actual number of messages queued.
For example, if the caller supplies a msgPtrList and msgLenList with room for 10 messages and sets msgListMax to 10, but there are 20 messages queued, then the pointers and lengths of the first 10 messages in the queue are returned in msgPtrList and msgLenList, but numMsgs will be returned with the value 20.
A list of the task IDs of tasks blocked on the message queue can be obtained by setting taskIdList to the address of an array to receive the list, and setting taskIdListMax to the maximum number of elements in that array. If taskIdList is NULL, then no task IDs are returned. No more than taskIdListMax task IDs are returned, although numTasks will always be returned with the actual number of tasks blocked.
For example, if the caller supplies a taskIdList with room for 10 task IDs and sets taskIdListMax to 10, but there are 20 tasks blocked on the message queue, then the IDs of the first 10 tasks in the blocked queue will be returned in taskIdList, but numTasks will be returned with the value 20.
Note that the tasks returned in taskIdList may be blocked for either send or receive. As noted above this can be determined by examining numMsgs.
The variables sendTimeouts and recvTimeouts are the counts of the number of times msgQSend( ) and msgQReceive( ) respectively returned with a timeout.
The variables options, maxMsgs, and maxMsgLength are the parameters with which the message queue was created.
The information returned by this routine is not static and may be obsolete by the time it is examined. In particular, the lists of task IDs and/or message pointers may no longer be valid. However, the information is obtained atomically, thus it will be an accurate snapshot of the state of the message queue at the time of the call. This information is generally used for debugging purposes only.
The current implementation of this routine locks out interrupts while obtaining the information. This can compromise the overall interrupt latency of the system. Generally this routine is used for debugging purposes only.
OK or ERROR.
S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,
S_objLib_OBJ_ID_ERROR
msgQShow( ) - show information about a message queue
STATUS msgQShow ( MSG_Q_ID msgQId, /* message queue to display */ int level /* 0 = summary, 1 = details */ )
This routine displays the state and optionally the contents of a message queue.
A summary of the state of the message queue is displayed as follows:
Message Queue Id : 0x3f8c20 Task Queuing : FIFO Message Byte Len : 150 Messages Max : 50 Messages Queued : 0 Receivers Blocked : 1 Send timeouts : 0 Receive timeouts : 0If level is 1, then more detailed information will be displayed. If messages are queued, they will be displayed as follows:Messages queued: # address length value 1 0x123eb204 4 0x00000001 0x12345678If tasks are blocked on the queue, they will be displayed as follows:Receivers blocked: NAME TID PRI DELAY ---------- -------- --- ----- tExcTask 3fd678 0 21
OK or ERROR.
S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED
msgQShow, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell