vxworks下的消息队列应用手册

msgQLib

NAME

msgQLib - message queue library

ROUTINES

( ) - create and initialize a message queue
( ) - delete a message queue
( ) - send a message to a message queue
( ) - receive a message from a message queue
( ) - get the number of messages queued to a message queue

DESCRIPTION

This library contains routines for creating and using message queues, the primary intertask communication mechanism within a single CPU. Message queues allow a variable number of messages (varying in length) to be queued in first-in-first-out (FIFO) order. Any task or interrupt service routine can send messages to a message queue. Any task can receive messages from a message queue. Multiple tasks can send to and receive from the same message queue. Full-duplex communication between two tasks generally requires two message queues, one for each direction.

CREATING AND USING MESSAGE QUEUES

A message queue is created with ( ). Its parameters specify the maximum 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.

A task or interrupt service routine sends a message to a message queue with ( ). 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 message queue, the message is immediately delivered to the first waiting task.

A task receives a message from a message queue with ( ). 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 to a queue of tasks waiting for messages. This queue of waiting tasks can be ordered either by task priority or FIFO, as specified in an option parameter when the queue is created.

TIMEOUTS

Both ( ) and ( ) take timeout parameters. When sending a message, if no buffer space is available to queue the message, the timeout specifies how many ticks to wait for space to become available. When receiving a message, the timeout specifies how many ticks to wait if no message is immediately available. The timeout parameter can have the special values NO_WAIT (0) or WAIT_FOREVER (-1). NO_WAIT means the routine should return immediately; WAIT_FOREVER means the routine should never time out.

URGENT MESSAGES

The ( ) routine allows the priority of a message to be specified as either normal or urgent, MSG_PRI_NORMAL (0) and MSG_PRI_URGENT (1), respectively. Normal priority messages are added to the tail of the list of queued messages, while urgent priority messages are added to the head of the list.

INCLUDE FILES

msgQLib.h

SEE ALSO

, , , VxWorks Programmer's Guide: Basic OS

msgQCreate( )

NAME

msgQCreate( ) - create and initialize a message queue

SYNOPSIS

MSG_Q_ID msgQCreate ( int maxMsgs, /* max messages that can be queued */ int maxMsgLength, /* max bytes in a message */ int options /* message queue options */ )

DESCRIPTION

This routine creates a message queue capable of holding up to maxMsgs messages, each up to maxMsgLength 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:

MSG_Q_FIFO (0x00)queue pended tasks in FIFO order.

MSG_Q_PRIORITY (0x01)queue pended tasks in priority order.

RETURNS

MSG_Q_ID, or NULL if error.

ERRNO

S_memLib_NOT_ENOUGH_MEMORY, S_intLib_NOT_ISR_CALLABLE

SEE ALSO

, 

msgQDelete( )

NAME

msgQDelete( ) - delete a message queue

SYNOPSIS

STATUS msgQDelete ( MSG_Q_ID msgQId /* message queue to delete */ )

DESCRIPTION

This routine deletes a message queue. Any task blocked on either a ( ) or ( ) will be unblocked and receive an error from the call with errno set to S_objLib_OBJECT_DELETED. The msgQId parameter will no longer be a valid message queue ID.

RETURNS

OK or ERROR.

ERRNO

S_objLib_OBJ_ID_ERROR, S_intLib_NOT_ISR_CALLABLE

SEE ALSO

, 

msgQSend( )

NAME

msgQSend( ) - send a message to a message queue

SYNOPSIS

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 */ )

DESCRIPTION

This routine sends the message in buffer of length nBytes to the message queue msgQId. If any tasks are already waiting to receive messages on the queue, the message will immediately be delivered to the first waiting task. If no task is waiting to receive messages, the message is saved in the message queue.

The timeout parameter specifies the number of ticks to wait for free space if the message queue is full. The timeout parameter can also have the following special values:

NO_WAIT (0)return immediately, even if the message has not been sent.

WAIT_FOREVER (-1)never time out.

The priority parameter specifies the priority of the message being sent. The possible values are:

MSG_PRI_NORMAL (0)normal priority; add the message to the tail of the list of queued messages.

MSG_PRI_URGENT (1)urgent priority; add the message to the head of the list of queued messages.

USE BY INTERRUPT SERVICE ROUTINES

This routine can be called by interrupt service routines as well as by tasks. This is one of the primary means of communication between an interrupt service routine and a task. When called from an interrupt service routine, timeout must be NO_WAIT.

RETURNS

OK or ERROR.

ERRNO

S_distLib_NOT_INITIALIZED, S_objLib_OBJ_ID_ERROR,
        S_objLib_OBJ_DELETED, S_objLib_OBJ_UNAVAILABLE,
        S_objLib_OBJ_TIMEOUT, S_msgQLib_INVALID_MSG_LENGTH,
        S_msgQLib_NON_ZERO_TIMEOUT_AT_INT_LEVEL

SEE ALSO

, 

msgQReceive( )

NAME

msgQReceive( ) - receive a message from a message queue

SYNOPSIS

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 */ )

DESCRIPTION

This routine receives a message from the message queue msgQId. The received message is copied into the specified 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 timeout parameter specifies the number of ticks to wait for a message to be sent to the queue, if no message is available when ( ) is called. The timeout parameter can also have the following special values:

NO_WAIT (0)return immediately, even if the message has not been sent.

WAIT_FOREVER (-1)never time out.

WARNING

This routine must not be called by interrupt service routines.

RETURNS

The number of bytes copied to buffer, or ERROR.

ERRNO

S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,
       S_objLib_OBJ_ID_ERROR, S_objLib_OBJ_DELETED,
       S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_TIMEOUT,
       S_msgQLib_INVALID_MSG_LENGTH

SEE ALSO

, 

msgQNumMsgs( )

NAME

msgQNumMsgs( ) - get the number of messages queued to a message queue

SYNOPSIS

int msgQNumMsgs ( MSG_Q_ID msgQId /* message queue to examine */ )

DESCRIPTION

This routine returns the number of messages currently queued to a specified message queue.

RETURNS

The number of messages queued, or ERROR.

ERRNO

S_distLib_NOT_INITIALIZED, S_smObjLib_NOT_INITIALIZED,
        S_objLib_OBJ_ID_ERROR

SEE ALSO

,