VxWorks API Reference : OS Libraries

msgQEvLib

NAME

msgQEvLib - VxWorks events support for message queues

ROUTINES

msgQEvStart( ) - start event notification process for a message queue
msgQEvStop( ) - stop event notification process for a message queue

DESCRIPTION

This library is an extension to eventLib, the events library. Its purpose is to support events for message queues.

The functions in this library are used to control registration of tasks on a message queue. The routine msgQEvStart( ) registers a task and starts the notification process. The function msgQEvStop( ) un-registers the task, which stops the notification mechanism.

When a task is registered and a message arrives on the queue, the events specified are sent to that task, on the condition that no other task is pending on that message queue. However, if a msgQReceive( ) is to be done afterwards to get the message, there is no guarantee that it will still be available.

INCLUDE FILES

msgQEvLib.h

SEE ALSO

eventLib, VxWorks Programmer's Guide: Basic OS

---

OS Libraries : Routines

msgQEvStart( )

NAME

msgQEvStart( ) - start event notification process for a message queue

SYNOPSIS

STATUS msgQEvStart
    (
    MSG_Q_ID msgQId,          /* msg Q for which to register events */
    UINT32   events,          /* 32 possible events */
    UINT8    options          /* event-related msg Q options */
    )

DESCRIPTION

This routine turns on the event notification process for a given message queue, registering the calling task on that queue. When a message arrives on the queue and no receivers are pending, the events specified will be sent to the registered task. A task can always overwrite its own registration.

The options parameter is used for 3 user options:

• Specify if the events are to be sent only once or every time a message
arrives until msgQEvStop( ) is called.
• Specify if another task can subsequently register itself while the calling
task is still registered. If so specified, the existing task registration will be overwritten without any warning.
• Specify if events are to be sent right away in the case a message is
waiting to be picked up.

Here are the respective values to be used to form the option field:

EVENTS_SEND_ONCE (0x1)

The message queue will send the events only once.

EVENTS_ALLOW_OVERWRITE (0x2)

Allows subsequent registrations from other tasks to overwrite the current one.

EVENTS_SEND_IF_FREE (0x4)

The registration process will send events if a message is present on the message queue when msgQEvStart( ) is called.

EVENTS_OPTIONS_NONE (0x0)

Must be passed to the options parameter if none of the other three options are used.

WARNING

This routine cannot be called from interrupt level.

WARNING

Task preemption can allow a msgQDelete to be performed between the calls to msgQEvStart and eventReceive. This will prevent the task from ever receiving the events wanted from the message queue.

RETURNS

OK on success, or ERROR.

ERRNO

S_objLib_OBJ_ID_ERROR

The message queue ID is invalid.

S_eventLib_ALREADY_REGISTERED

A task is already registered on the message queue.

S_intLib_NOT_ISR_CALLABLE

Routine has been called from interrupt level.

S_eventLib_EVENTSEND_FAILED

User chose to send events right away and that operation failed.

S_eventLib_ZERO_EVENTS

User passed in a value of zero to the events parameter.

SEE ALSO

msgQEvLib, eventLib, msgQLib, msgQEvStop( )

---

OS Libraries : Routines

msgQEvStop( )

NAME

msgQEvStop( ) - stop event notification process for a message queue

SYNOPSIS

STATUS msgQEvStop
    (
    MSG_Q_ID msgQId
    )

DESCRIPTION

This routine turns off the event notification process for a given message queue. It thus allows another task to register itself for event notification on that particular message queue. It has to be called by the task that is already registered on that particular message queue.

RETURNS

OK on success, or ERROR.

ERRNO

S_objLib_OBJ_ID_ERROR

The message queue ID is invalid.

S_intLib_NOT_ISR_CALLABLE

Routine has been called from interrupt level.

S_eventLib_TASK_NOT_REGISTERED

Routine has not been called by registered task.

SEE ALSO

msgQEvLib, eventLib, msgQLib, msgQEvStart( )