vxwmsgq.html

vxworks相关论文

&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;the&nbsp;queue&nbsp;is&nbsp;full&nbsp;for&nbsp;<i>timeout</i>&nbsp;ticks.
<p>
S_msgQLib_INVALID_MSG_LENGTH<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;<i>nBytes</i>&nbsp;is&nbsp;larger&nbsp;than&nbsp;the&nbsp;<i>maxMsgLength</i>&nbsp;set&nbsp;for&nbsp;the&nbsp;message&nbsp;queue.
<p>
S_msgQLib_NON_ZERO_TIMEOUT_AT_INT_LEVEL<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;called&nbsp;from&nbsp;an&nbsp;ISR,&nbsp;with&nbsp;<i>timeout</i>&nbsp;not&nbsp;set&nbsp;to&nbsp;<b>NO_WAIT</b>.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWMsgQ.html#top">VXWMsgQ</a></b>

<hr>
<a name="VXWMsgQ::receive"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWMsgQ::receive</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWMsgQ::receive</i>(&nbsp;)</strong> - receive a message from message queue</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>int receive
    (
    char * buffer,
    UINT   nBytes,
    int    timeout
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine receives a message from its message queue.
The received message is copied into the specified <i>buffer</i>, which is
<i>nBytes</i> in length.  If the message is longer than <i>nBytes</i>,
the remainder of the message is discarded (no error indication
is returned).
<p>
The <i>timeout</i> parameter specifies the number of ticks to wait for 
a message to be sent to the queue, if no message is available when
<b><i><a href="./VXWMsgQ.html#VXWMsgQ::receive">VXWMsgQ::receive</a></i>(&nbsp;)</b> is called.  The <i>timeout</i> parameter can also have 
the following special values: 
<dl>
<dt>
<b>NO_WAIT</b>
<dd>

return immediately, even if the message has not been sent.  
<p>
<dt>
<b>WAIT_FOREVER</b>
<dd>
 never time out. 
</dl>

<p>

</blockquote><h4>WARNING</h4><blockquote><p>
This routine must not be called by interrupt service routines.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<p>
The number of bytes copied to <i>buffer</i>, or ERROR.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
<p>
S_objLib_OBJ_DELETED<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;the&nbsp;message&nbsp;queue&nbsp;was&nbsp;deleted&nbsp;while&nbsp;waiting&nbsp;to&nbsp;receive&nbsp;a&nbsp;message.
<p>
S_objLib_OBJ_UNAVAILABLE<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;<i>timeout</i>&nbsp;is&nbsp;set&nbsp;to&nbsp;<b>NO_WAIT</b>,&nbsp;and&nbsp;no&nbsp;messages&nbsp;are&nbsp;available.
<p>
S_objLib_OBJ_TIMEOUT<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;no&nbsp;messages&nbsp;were&nbsp;received&nbsp;in&nbsp;<i>timeout</i>&nbsp;ticks.
<p>
S_msgQLib_INVALID_MSG_LENGTH<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;<i>nBytes</i>&nbsp;is&nbsp;less&nbsp;than&nbsp;0.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWMsgQ.html#top">VXWMsgQ</a></b>

<hr>
<a name="VXWMsgQ::numMsgs"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWMsgQ::numMsgs</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWMsgQ::numMsgs</i>(&nbsp;)</strong> - report the number of messages queued</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>    int numMsgs ()</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine returns the number of messages currently queued to the
message queue.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<p>
The number of messages queued, or ERROR.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
<p>
S_objLib_OBJ_ID_ERROR<br>
&nbsp;&nbsp;&nbsp;&nbsp;-&nbsp;<i>msgQId</i>&nbsp;is&nbsp;invalid.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWMsgQ.html#top">VXWMsgQ</a></b>

<hr>
<a name="VXWMsgQ::info"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWMsgQ::info</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWMsgQ::info</i>(&nbsp;)</strong> - get information about message queue</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS info
    (
    MSG_Q_INFO * pInfo
    ) const</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine gets information about the state and contents of its message
queue.  The parameter <i>pInfo</i> is a pointer to a structure of type <b>MSG_Q_INFO</b>
defined in <b>msgQLib.h</b> as follows:
<p>
<pre> 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;
</pre>

If the message queue is empty, there may be tasks blocked on receiving.
If the message queue is full, there may be tasks blocked on sending.
This can be determined as follows:
<ul>
<li>  If <i>numMsgs</i> is 0, then <i>numTasks</i> indicates the number of tasks blocked
on receiving.</li>
<li>  If <i>numMsgs</i> is equal to <i>maxMsgs</i>, then <i>numTasks</i> is the number of
tasks blocked on sending.</li>
<li>   If <i>numMsgs</i> is greater than 0 but less than <i>maxMsgs</i>, then <i>numTasks</i> 
will be 0. 
</ul>

<p>

<p>
A list of pointers to the messages queued and their lengths can be
obtained by setting <i>msgPtrList</i> and <i>msgLenList</i> to the addresses of
arrays to receive the respective lists, and setting <i>msgListMax</i> to
the maximum number of elements in those arrays.  If either list pointer
is NULL, no data is returned for that array.
<p>
No more than <i>msgListMax</i> message pointers and lengths are returned,
although <i>numMsgs</i> is always returned with the actual number of messages
queued.
<p>
For example, if the caller supplies a <i>msgPtrList</i> and <i>msgLenList</i>
with room for 10 messages and sets <i>msgListMax</i> to 10, but there are 20
messages queued, then the pointers and lengths of the first 10 messages in
the queue are returned in <i>msgPtrList</i> and <i>msgLenList</i>, but <i>numMsgs</i> is
returned with the value 20.
<p>
A list of the task IDs of tasks blocked on the message queue can be obtained
by setting <i>taskIdList</i> to the address of an array to receive the list, and
setting <i>taskIdListMax</i> to the maximum number of elements in that array.
If <i>taskIdList</i> is NULL, then no task IDs are returned.  No more than
<i>taskIdListMax</i> task IDs are returned, although <i>numTasks</i> is always
returned with the actual number of tasks blocked.
<p>
For example, if the caller supplies a <i>taskIdList</i> with room for 10 task IDs
and sets <i>taskIdListMax</i> to 10, but there are 20 tasks blocked on the
message queue, then the IDs of the first 10 tasks in the blocked queue
are returned in <i>taskIdList</i>, but <i>numTasks</i> is returned with
the value 20.
<p>
Note that the tasks returned in <i>taskIdList</i> may be blocked for either send
or receive.  As noted above this can be determined by examining <i>numMsgs</i>.
The variables <i>sendTimeouts</i> and <i>recvTimeouts</i> are the counts of
the number of times <b><i><a href="./VXWMsgQ.html#VXWMsgQ::send">VXWMsgQ::send</a></i>(&nbsp;)</b> and <b><i><a href="./VXWMsgQ.html#VXWMsgQ::receive">VXWMsgQ::receive</a></i>(&nbsp;)</b> (or
their equivalents in other language bindings) respectively returned
with a timeout.
<p>
The variables <i>options</i>, <i>maxMsgs</i>, and <i>maxMsgLength</i> are the parameters
with which the message queue was created.
<p>
</blockquote><h4>WARNING</h4><blockquote><p>
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 is 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.
<p>
</blockquote><h4>WARNING</h4><blockquote><p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK or ERROR.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWMsgQ.html#top">VXWMsgQ</a></b>

<hr>
<a name="VXWMsgQ::show"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWMsgQ::show</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWMsgQ::show</i>(&nbsp;)</strong> - show information about a message queue</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS show
    (
    int level
    ) const</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine displays the state and optionally the contents of a message
queue.
<p>
A summary of the state of the message queue is displayed as follows:
<pre>    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    : 0
</pre>

If <i>level</i> is 1, more detailed information is displayed.
If messages are queued, they are displayed as follows:
<pre>    Messages queued:
      #    address length value
      1 0x123eb204    4   0x00000001 0x12345678
</pre>

If tasks are blocked on the queue, they are displayed as follows:
<pre>    Receivers blocked:

       NAME      TID    PRI DELAY
    ---------- -------- --- -----
    tExcTask     3fd678   0   21
</pre>

</blockquote><h4>RETURNS</h4><blockquote><p>
OK or ERROR.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWMsgQ.html#top">VXWMsgQ</a></b>

</body>
</html>