VxWorks API Reference : OS Libraries
eventLib - VxWorks events library
eventReceive( ) - Wait for event(s)
eventSend( ) - Send event(s)
eventClear( ) - Clear all events for current task.
Events are a means of communication between tasks and interrupt routines, based on a synchronous model. Only tasks can receive events, and both tasks and ISRs can send them.
Events are similar to signals in that they are directed at one task but differ in the fact that they are synchronous in nature. Thus, the receiving task must pend when waiting for events to occur. Also, unlike signals, a handler is not needed since, when wanted events are received, the pending task continues its execution (like after a call to msgQReceive( ) or semTake( )).
Each task has its own events field that can be filled by having tasks (even itself) and/or ISRs sending events to the task. Each event's meaning is different for every task. Event X when received can be interpreted differently by separate tasks. Also, it should be noted that events are not accumulated. If the same event is received several times, it counts as if it were received only once. It is not possible to track how many times each event has been sent to a task.
There are some VxWorks objects that can send events when they become available. They are referred to as resources in the context of events. They include semaphores and message queues. For example, when a semaphore becomes free, events can be sent to a task that asked for it.
eventLib.h
taskLib, semLib, semBLib, semCLib, semMLib, msgQLib, VxWorks Programmer's Guide: Basic OS
eventReceive( ) - Wait for event(s)
STATUS eventReceive ( UINT32 events, /* events task is waiting to occur */ UINT8 options, /* user options */ int timeout, /* ticks to wait */ UINT32 * pEventsReceived /* events occured are returned through this */ )
Pends task until one or all specified events have occurred. When they have, pEventsReceived will be filled with those that did occur.
The options parameter is used for four user options. Firstly, it is used to specify if the task is going to wait for all events to occur or only one of them. One of the following has to be selected:
Secondly, it is used to specify if the events returned in pEventsReceived will be only those received and wanted, or all events received (even the ones received before eventReceive( ) was called). By default it returns only the events wanted.
- EVENTS_WAIT_ANY (0x1)
- only one event has to occur
- EVENTS_WAIT_ALL (0x0)
- will wait until all events occur.
Thirdly, the user can specify if the events received but not wanted are to be cleared or not in the calling task's events register. They are cleared by default. Wanted events are always cleared.
- EVENTS_RETURN_ALL (0x2)
- When this option is turned on, it causes the function to return received events, both wanted and unwanted. All events are cleared when this option is selected.
Lastly, it can be used to retrieve what events have been received by the current task.
- EVENTS_KEEP_UNWANTED (0x4)
- Tells the system not to clear the unwanted events. In the case that the option EVENTS_RETURN_ALL is used, all events are cleared even if this one is selected.
- EVENTS_FETCH (0x80)
- If this option is set, then pEventsReceived will be filled with the events that have already been received and will return immediately. In this case, the parameters events and timeout, as well as all the other options, are ignored. Also, events are not cleared, allowing to get a peek at the events that have already been received.
The timeout parameter specifies the number of ticks to wait for wanted events to be sent to the waiting task. It can also have the following special values:
- NO_WAIT (0)
- return immediately, even if no events have arrived.
- WAIT_FOREVER (-1)
- never time out.
The parameter pEventsReceived is always filled with the events received even when the function returns an error, except if a value of NULL was passed.
This routine may not be used from interrupt level.
OK on success or ERROR.
- S_eventLib_TIMEOUT
- Wanted events not received before specified time expired.
- S_eventLib_NOT_ALL_EVENTS
- Specified NO_WAIT as the timeout parameter and wanted events were not already received when the routine was called.
- S_objLib_OBJ_DELETED
- Task is waiting for some events from a resource that is subsequently deleted.
- S_intLib_NOT_ISR_CALLABLE
- Function has been called from ISR.
- S_eventLib_ZERO_EVENTS
- The events parameter has been passed a value of 0.
eventLib, semEvLib, msgQEvLib, eventSend( )
eventSend( ) - Send event(s)
STATUS eventSend ( int taskId, /* task events will be sent to */ UINT32 events /* events to send */ )
Sends specified event(s) to specified task. Passing a taskId of NULL sends events to the calling task.
OK on success or ERROR.
- S_objLib_OBJ_ID_ERROR
- Task ID is invalid.
- S_eventLib_NULL_TASKID_AT_INT_LEVEL
- Routine was called from ISR with a taskId of NULL.
eventLib, eventReceive( )
eventClear( ) - Clear all events for current task.
STATUS eventClear (void)
This function clears all received events for the calling task.
OK on success or ERROR.
- S_intLib_NOT_ISR_CALLABLE
- Routine has been called from interrupt level.