📄 msgqlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/msgQLib.html - generated by refgen from msgQLib.c --> <title> msgQLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>msgQLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQLib</strong> - message queue library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./msgQLib.html#msgQCreate">msgQCreate</a></i>( )</b> - create and initialize a message queue<br><b><i><a href="./msgQLib.html#msgQDelete">msgQDelete</a></i>( )</b> - delete a message queue<br><b><i><a href="./msgQLib.html#msgQSend">msgQSend</a></i>( )</b> - send a message to a message queue<br><b><i><a href="./msgQLib.html#msgQReceive">msgQReceive</a></i>( )</b> - receive a message from a message queue<br><b><i><a href="./msgQLib.html#msgQNumMsgs">msgQNumMsgs</a></i>( )</b> - get the number of messages queued to a message queue<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library contains routines for creating and using message queues, the primary intertask communication mechanism within a single CPU. Messagequeues allow a variable number of messages (varying in length) to bequeued in first-in-first-out (FIFO) order. Any task or interrupt serviceroutine can send messages to a message queue. Any task can receivemessages from a message queue. Multiple tasks can send to and receivefrom the same message queue. Full-duplex communication between two tasksgenerally requires two message queues, one for each direction.<p></blockquote><h4>CREATING AND USING MESSAGE QUEUES</h4><blockquote><p>A message queue is created with <b><i><a href="./msgQLib.html#msgQCreate">msgQCreate</a></i>( )</b>. Its parameters specify themaximum 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.<p>A task or interrupt service routine sends a message to a message queuewith <b><i><a href="./msgQLib.html#msgQSend">msgQSend</a></i>( )</b>. 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 messagequeue, the message is immediately delivered to the first waiting task.<p>A task receives a message from a message queue with <b><i><a href="./msgQLib.html#msgQReceive">msgQReceive</a></i>( )</b>.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 toa queue of tasks waiting for messages. This queue of waiting tasks canbe ordered either by task priority or FIFO, as specified in an optionparameter when the queue is created.<p></blockquote><h4>TIMEOUTS</h4><blockquote><p>Both <b><i><a href="./msgQLib.html#msgQSend">msgQSend</a></i>( )</b> and <b><i><a href="./msgQLib.html#msgQReceive">msgQReceive</a></i>( )</b> take timeout parameters. When sending amessage, if no buffer space is available to queue the message, the timeoutspecifies how many ticks to wait for space to become available. Whenreceiving a message, the timeout specifies how many ticks to wait if nomessage is immediately available. The <i>timeout</i> parameter canhave the special values <b>NO_WAIT</b> (0) or <b>WAIT_FOREVER</b> (-1). <b>NO_WAIT</b> means the routine should return immediately; <b>WAIT_FOREVER</b> means the routineshould never time out.<p></blockquote><h4>URGENT MESSAGES</h4><blockquote><p>The <b><i><a href="./msgQLib.html#msgQSend">msgQSend</a></i>( )</b> routine allows the priority of a message to be specifiedas either normal or urgent, <b>MSG_PRI_NORMAL</b> (0) and <b>MSG_PRI_URGENT</b> (1),respectively. Normal priority messages are added to the tail of the listof queued messages, while urgent priority messages are added to the headof the list.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>msgQLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./pipeDrv.html#top">pipeDrv</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b>, <i>VxWorks Programmer's Guide: Basic OS</i><hr><a name="msgQCreate"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>msgQCreate</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>msgQCreate</i>( )</strong> - create and initialize a message queue</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>MSG_Q_ID msgQCreate ( int maxMsgs, /* max messages that can be queued */ int maxMsgLength, /* max bytes in a message */ int options /* message queue options */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine creates a message queue capable of holding up to <i>maxMsgs</i>messages, each up to <i>maxMsgLength</i> 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:<dl><dt><b>MSG_Q_FIFO</b> (0x00)<dd>queue pended tasks in FIFO order.<p><dt><b>MSG_Q_PRIORITY</b> (0x01)<dd> queue pended tasks in priority order.<p></dl></blockquote><h4>RETURNS</h4><blockquote><p><p><b>MSG_Q_ID</b>, or NULL if error.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_memLib_NOT_ENOUGH_MEMORY, S_intLib_NOT_ISR_CALLABLE<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b><hr><a name="msgQDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>msgQDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>msgQDelete</i>( )</strong> - delete a message queue</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS msgQDelete ( MSG_Q_ID msgQId /* message queue to delete */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine deletes a message queue. Any task blocked on eithera <b><i><a href="./msgQLib.html#msgQSend">msgQSend</a></i>( )</b> or <b><i><a href="./msgQLib.html#msgQReceive">msgQReceive</a></i>( )</b> will be unblocked and receive an errorfrom the call with <b>errno</b> set to S_objLib_OBJECT_DELETED. The<i>msgQId</i> parameter will no longer be a valid message queue ID.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK or ERROR.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_objLib_OBJ_ID_ERROR, S_intLib_NOT_ISR_CALLABLE<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b><hr><a name="msgQSend"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>msgQSend</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>msgQSend</i>( )</strong> - send a message to a message queue</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine sends the message in <i>buffer</i> of length <i>nBytes</i> to the messagequeue <i>msgQId</i>. If any tasks are already waiting to receive messageson the queue, the message will immediately be delivered to the firstwaiting task. If no task is waiting to receive messages, the messageis saved in the message queue.<p>The <i>timeout</i> parameter specifies the number of ticks to wait for freespace if the message queue is full. The <i>timeout</i> parameter can also have the following special values:<dl><dt><b>NO_WAIT</b> (0)<dd>return immediately, even if the message has not been sent. <p><dt><b>WAIT_FOREVER</b> (-1)<dd> never time out. </dl><p>The <i>priority</i> parameter specifies the priority of the message being sent.The possible values are:<dl><dt><b>MSG_PRI_NORMAL</b> (0)<dd>normal priority; add the message to the tail of the list of queued messages.<p><dt><b>MSG_PRI_URGENT</b> (1)<dd> urgent priority; add the message to the head of the list of queued messages. </dl><p></blockquote><h4>USE BY INTERRUPT SERVICE ROUTINES</h4><blockquote><p>This routine can be called by interrupt service routines as well asby tasks. This is one of the primary means of communicationbetween an interrupt service routine and a task. When called from aninterrupt service routine, <i>timeout</i> must be <b>NO_WAIT</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK or ERROR.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_distLib_NOT_INITIALIZED, S_objLib_OBJ_ID_ERROR,<br> S_objLib_OBJ_DELETED, S_objLib_OBJ_UNAVAILABLE,<br> S_objLib_OBJ_TIMEOUT, S_msgQLib_INVALID_MSG_LENGTH,<br> S_msgQLib_NON_ZERO_TIMEOUT_AT_INT_LEVEL<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b><hr><a name="msgQReceive"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>msgQReceive</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>msgQReceive</i>( )</strong> - receive a message from a message queue</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine receives a message from the message queue <i>msgQId</i>.The received message is copied into the specified <i>buffer</i>, which is<i>maxNBytes</i> in length. If the message is longer than <i>maxNBytes</i>,the remainder of the message is discarded (no error indicationis 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="./msgQLib.html#msgQReceive">msgQReceive</a></i>( )</b> is called. The <i>timeout</i> parameter can also have the following special values: <dl><dt><b>NO_WAIT</b> (0)<dd>return immediately, even if the message has not been sent. <p><dt><b>WAIT_FOREVER</b> (-1)<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>S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,<br> S_objLib_OBJ_ID_ERROR, S_objLib_OBJ_DELETED,<br> S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_TIMEOUT,<br> S_msgQLib_INVALID_MSG_LENGTH<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b><hr><a name="msgQNumMsgs"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>msgQNumMsgs</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>msgQNumMsgs</i>( )</strong> - get the number of messages queued to a message queue</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int msgQNumMsgs ( MSG_Q_ID msgQId /* message queue to examine */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine returns the number of messages currently queued to a specifiedmessage queue.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>The number of messages queued, or ERROR.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,<br> S_objLib_OBJ_ID_ERROR<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -