📄 msgqdistlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/msgQDistLib.html - generated by refgen from msgQDistLib.c --> <title> msgQDistLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>msgQDistLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQDistLib</strong> - distributed objects message queue library (VxFusion option) </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./msgQDistLib.html#msgQDistCreate">msgQDistCreate</a>( )</b> - create a distributed message queue (VxFusion option)<br><b><a href="./msgQDistLib.html#msgQDistSend">msgQDistSend</a>( )</b> - send a message to a distributed message queue (VxFusion option)<br><b><a href="./msgQDistLib.html#msgQDistReceive">msgQDistReceive</a>( )</b> - receive a message from a distributed message queue (VxFusion option)<br><b><a href="./msgQDistLib.html#msgQDistNumMsgs">msgQDistNumMsgs</a>( )</b> - get the number of messages in a distributed message queue (VxFusion option)<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library provides the interface to distributed message queues.Any task on any node in the system can send messages to or receivefrom a distributed messsage queue. Full duplex communication betweentwo tasks generally requires two distributed messsage queues, one foreach direction.<p>Distributed messsage queues are created with <b><a href="./msgQDistLib.html#msgQDistCreate">msgQDistCreate</a>( )</b>. Aftercreation, they can be manipulated using the generic routines for localmessage queues; for more information on the use of these routines, see themanual entry for <b><a href="./msgQLib.html#top">msgQLib</a></b>. The <b><a href="./msgQDistLib.html#top">msgQDistLib</a></b> library also provides the <b><a href="./msgQDistLib.html#msgQDistSend">msgQDistSend</a>( )</b>, <b><a href="./msgQDistLib.html#msgQDistReceive">msgQDistReceive</a>( )</b>, and <b><a href="./msgQDistLib.html#msgQDistNumMsgs">msgQDistNumMsgs</a>( )</b> routines which support additional parameters that are useful for working with distributed message queues.<p>The distributed objects message queue library is initialized by calling<b><a href="./distLib.html#distInit">distInit</a>( )</b>.<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This module is distributed as a component of the unbundled distributedmessage queues option, VxFusion.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>msgQDistLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQLib.html#top">msgQLib</a></b>, <b><a href="./msgQDistShow.html#top">msgQDistShow</a></b>, <b><a href="./distLib.html#top">distLib</a></b><hr><a name="msgQDistCreate"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>msgQDistCreate( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQDistCreate( )</strong> - create a distributed message queue (VxFusion option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>MSG_Q_ID msgQDistCreate ( 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 distributed message queue capable ofholding up to <i>maxMsgs</i> messages, each up to <i>maxMsgLength</i> bytes long.This routine returns a message queue ID used to identify the createdmessage queue. The queue can be created with the following options:<dl><dt><b>MSG_Q_FIFO</b> (0x00)<dd>The queue pends tasks in FIFO order.<dt><b>MSG_Q_PRIORITY</b> (0x01)<dd>The queue pends tasks in priority order. Remote tasks share the samepriority level.</dl>The global message queue identifier returned can be used directly by genericmessage queue handling routines in <b><a href="./msgQLib.html#top">msgQLib</a></b>, such as, <b><a href="./msgQLib.html#msgQSend">msgQSend</a>( )</b>, <b><a href="./msgQLib.html#msgQReceive">msgQReceive</a>( )</b>, and <b><a href="./msgQLib.html#msgQNumMsgs">msgQNumMsgs</a>( )</b>.<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled distributedmessage queues option, VxFusion.<p></blockquote><h4>RETURNS</h4><blockquote><p><p><b>MSG_Q_ID</b>, or NULL if there is an error.<p></blockquote><h4>ERRNO</h4><blockquote><p><p><dl><dt><b>S_memLib_NOT_ENOUGH_MEMORY</b><dd>If the routine is unable to allocate memory for message queues and message buffers.<dt><b>S_intLib_NOT_ISR_CALLABLE</b><dd>If the routine is called from an interrupt service routine.<dt><b>S_msgQLib_INVALID_QUEUE_TYPE</b><dd>If the type of queue is invalid.<dt><b>S_msgQDistLib_INVALID_MSG_LENGTH</b><dd>If the message is too long for the VxFusion network layer.</dl></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQDistLib.html#top">msgQDistLib</a></b>, <b><a href="./msgQLib.html#top">msgQLib</a></b><hr><a name="msgQDistSend"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>msgQDistSend( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQDistSend( )</strong> - send a message to a distributed message queue (VxFusion option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine sends the message specified by <i>buffer</i> of length <i>nBytes</i> to the distributed message queue or group specified by <i>msgQId</i>.<p>The argument <i>msgQTimeout</i> specifies the time in ticks to wait for the queuing of the message. The argument <i>overallTimeout</i> specifies the time inticks to wait for both the sending and queuing of the message.While it is an error to set <i>overallTimeout</i> to <b>NO_WAIT</b> (0), <b>WAIT_FOREVER</b> (-1) is allowed for both <i>msgQTimeout</i> and <i>overallTimeout</i>.<p>The <i>priority</i> parameter specifies the priority of the message being sent.It ranges between <b>DIST_MSG_PRI_0</b> (highest priority) and <b>DIST_MSG_PRI_7</b> (lowest priority). A priority of <b>MSG_PRI_URGENT</b> is mappedto <b>DIST_MSG_PRI_0</b>; <b>MSG_PRI_NORMAL</b> is mapped to <b>DIST_MSG_PRI_4</b> .Messages sent with high priorities (<b>DIST_MSG_PRI_0</b> to <b>DIST_MSG_PRI_3</b>)are put to the head of the list of queued messages.Lower priority messages (<b>DIST_MSG_PRI_4</b> to <b>DIST_MSG_PRI_7</b>) are placedat the queue's tail.<p></blockquote><h4>NOTE</h4><blockquote><p>When <b><a href="./msgQDistLib.html#msgQDistSend">msgQDistSend</a>( )</b> is called through <b><a href="./msgQLib.html#msgQSend">msgQSend</a>( )</b>, <i>msgQTimeout</i> is set to <i>timeout</i> and <i>overallTimeout</i> to <b>WAIT_FOREVER</b> .<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled distributedmessage queues option, VxFusion.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the operation fails.<p></blockquote><h4>ERRNO</h4><blockquote><p><p><dl><dt><b>S_distLib_OBJ_ID_ERROR</b><dd>The argument <i>msgQId</i> is invalid.<dt><b>S_distLib_UNREACHABLE</b><dd>Could not establish communications with the remote node.<dt><b>S_msgQDistLib_INVALID_PRIORITY</b><dd>The argument <i>priority</i> is invalid.<dt><b>S_msgQDistLib_INVALID_TIMEOUT</b><dd>The argument <i>overallTimeout</i> is <b>NO_WAIT</b> .<dt><b>S_msgQDistLib_RMT_MEMORY_SHORTAGE</b><dd>There is not enough memory on the remote node.<dt><b>S_objLib_OBJ_UNAVAILABLE</b><dd>The argument <i>msgQTimeout</i> is set to <b>NO_WAIT</b>, and the queue is full.<dt><b>S_objLib_OBJ_TIMEOUT</b><dd>The queue is full for <i>msgQTimeout</i> ticks.<dt><b>S_msgQLib_INVALID_MSG_LENGTH</b><dd>The argument <i>nBytes</i> is larger than the <i>maxMsgLength</i> set for the message queue.<dt><b>S_msgQDistLib_OVERALL_TIMEOUT</b><dd>There was no response from the remote side in <i>overallTimeout</i> ticks.</dl></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQDistLib.html#top">msgQDistLib</a></b>, <b><a href="./msgQLib.html#top">msgQLib</a></b><hr><a name="msgQDistReceive"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>msgQDistReceive( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQDistReceive( )</strong> - receive a message from a distributed message queue (VxFusion option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine receives a message from the distributed message queue specified by <i>msgQId</i>. The received message is copied into the specified buffer, <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 argument <i>msgQTimeout</i> specifies the time in ticks to wait for the queuing of the message. The argument <i>overallTimeout</i> specifies the timein ticks to wait for both the sending and queuing of the message.While it is an error to set <i>overallTimeout</i> to <b>NO_WAIT</b> (0), <b>WAIT_FOREVER</b> (-1) is allowed for both <i>msgQTimeout</i> and <i>overallTimeout</i>.<p>Calling <b><a href="./msgQDistLib.html#msgQDistReceive">msgQDistReceive</a>( )</b> on a distributed message group returns anerror.<p></blockquote><h4>NOTE</h4><blockquote><p>When <b><a href="./msgQDistLib.html#msgQDistReceive">msgQDistReceive</a>( )</b> is called through <b><a href="./msgQLib.html#msgQReceive">msgQReceive</a>( )</b>, <i>msgQTimeout</i> is set to <i>timeout</i> and <i>overallTimeout</i> to <b>WAIT_FOREVER</b> .<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled distributedmessage queues option, VxFusion.<p></blockquote><h4>RETURNS</h4><blockquote><p>The number of bytes copied to <i>buffer</i>, or ERROR. <p></blockquote><h4>ERRNO</h4><blockquote><p><p><dl><dt><b>S_distLib_OBJ_ID_ERROR</b><dd>The argument <i>msgQId</i> is invalid.<dt><b>S_distLib_UNREACHABLE</b><dd>Could not establish communications with the remote node.<dt><b>S_msgQLib_INVALID_MSG_LENGTH</b><dd>The argument <i>maxNBytes</i> is less than 0.<dt><b>S_msgQDistLib_INVALID_TIMEOUT</b><dd>The argument <i>overallTimeout</i> is <b>NO_WAIT</b> .<dt><b>S_msgQDistLib_RMT_MEMORY_SHORTAGE</b><dd>There is not enough memory on the remote node.<dt><b>S_objLib_OBJ_UNAVAILABLE</b><dd>The argument <i>msgQTimeout</i> is set to <b>NO_WAIT</b>, and no messages are available.<dt><b>S_objLib_OBJ_TIMEOUT</b><dd>No messages were received in <i>msgQTimeout</i> ticks.<dt><b>S_msgQDistLib_OVERALL_TIMEOUT</b><dd>There was no response from the remote side in <i>overallTimeout</i> ticks.</dl><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQDistLib.html#top">msgQDistLib</a></b>, <b><a href="./msgQLib.html#top">msgQLib</a></b><hr><a name="msgQDistNumMsgs"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>msgQDistNumMsgs( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>msgQDistNumMsgs( )</strong> - get the number of messages in a distributed message queue (VxFusion option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int msgQDistNumMsgs ( MSG_Q_ID msgQId, /* message queue to examine */ int overallTimeout /* ticks to wait overall */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine returns the number of messages currently queued to a specifieddistributed message queue.<p></blockquote><h4>NOTE</h4><blockquote><p><p>When <b><a href="./msgQDistLib.html#msgQDistNumMsgs">msgQDistNumMsgs</a>( )</b> is called through <b><a href="./msgQLib.html#msgQNumMsgs">msgQNumMsgs</a>( )</b>, <i>overallTimeout</i>is set to <b>WAIT_FOREVER</b> . You cannot set <i>overallTimeout</i> to <b>NO_WAIT</b> (0)because the process of sending a message from the local node to the remotenode always takes a finite amount of time.<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled distributedmessage queues option, VxFusion.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>The number of messages queued, or ERROR if the operation fails.<p></blockquote><h4>ERRNO</h4><blockquote><p><p><dl><dt><b>S_distLib_OBJ_ID_ERROR</b><dd>The argument <i>msgQId</i> is invalid.<dt><b>S_distLib_UNREACHABLE</b><dd>Could not establish communications with the remote node.<dt><b>S_msgQDistLib_INVALID_TIMEOUT</b><dd>The argument <i>overallTimeout</i> is <b>NO_WAIT</b> .</dl></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./msgQDistLib.html#top">msgQDistLib</a></b>, <b><a href="./msgQLib.html#top">msgQLib</a></b></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -