Events are used to synchronize a task with an ISR or between two tasks. More...
#include <OsEvent.h>
Public Member Functions | |
| OsEvent (const intptr_t userData=0) | |
| Constructor. More... | |
| virtual | ~OsEvent () |
| Destructor. More... | |
| virtual OsStatus | signal (const intptr_t eventData) |
| Set the event data and signal the occurrence of the event. More... | |
| virtual OsStatus | reset (void) |
| Reset the event so that it may be signaled again. More... | |
| virtual OsStatus | wait (const OsTime &rTimeout=OsTime::OS_INFINITY) |
| Wait for the event to be signaled. More... | |
| virtual OsStatus | setUserData (intptr_t userData) |
| Sets the user data specified. There are situations (such as the OsProtedtedEvent) More... | |
| virtual OsStatus | getEventData (intptr_t &rEventData) |
| Return the event data that was signaled by the notifier task. More... | |
| virtual OsStatus | getUserData (intptr_t &rUserData) const |
| Return the user data specified when this object was constructed. More... | |
| virtual UtlBoolean | isSignaled (void) |
| Return TRUE if the event has been signaled, otherwise FALSE. More... | |
 Public Member Functions inherited from OsNotification | |
| OsNotification () | |
| virtual | ~OsNotification () |
| virtual void | setTimeout (const OsTime &signalTimeout) |
| Set timeout to use when signalling if supported by derived class. More... | |
Additional Inherited Members | |
| Protected Attributes inherited from OsNotification | |
| OsTime | mSignalTimeout |
| Used by derived classes that support a timeout on signal. More... | |
Detailed Description
Events are used to synchronize a task with an ISR or between two tasks.
Events consist of event data (an integer) that is set when the event is signaled and a state variable that indicates whether the event has been signaled. When first initialized, an OsEvent is ready to be signaled. However, once signaled, the OsEvent must be explicitly reset before it may be signaled again. An OsEvent is intended for use in synchronizing one notifier (task or ISR) with one listener task. If an OsEvent object is intended for use with more than one notifier or listener, then an external mutex must be used to serialize access and avoid race conditions.
Background
First, a little bit of terminology. The task that wishes to be notified when an event occurs is the "Listener" task. The task that signals when a given event occurs is the "Notifier" task. A Notifier informs the Listener that a given event has occurred by sending an "Event Notification".
Expected Usage
The Listener passes an event object to the Notifier. When the corresponding event occurs, the Notifier uses the event object to signal the occurrence of the event. The Listener may receive event notifications by: polling, blocking until the event is signaled, or blocking until either the event is signaled or a timeout expires. When the Listener receives the event notification, it can then invoke the appropriate event handler. This handler will run in the Listener's task context.
- Note
- Using a busy loop to poll for event status is considered anti-social behavior. However, when using the event object approach, a task can perform a blocking wait for only one event at a time. A solution that allows a task to receive signals for multiple events is a message queue (see OsQueuedEvent for more information).
Constructor & Destructor Documentation
|
virtual |
Destructor.
Member Function Documentation
Set the event data and signal the occurrence of the event.
Return OS_ALREADY_SIGNALED if the event has already been signaled (and has not yet been cleared), otherwise return OS_SUCCESS.
Implements OsNotification.
Reimplemented in OsProtectedEvent.
|
virtual |
Reset the event so that it may be signaled again.
Return OS_NOT_SIGNALED if the event has not been signaled (or has already been cleared), otherwise return OS_SUCCESS.
Reimplemented in OsProtectedEvent.
|
virtual |
Wait for the event to be signaled.
Return OS_BUSY if the timeout expired, otherwise return OS_SUCCESS.
Sets the user data specified. There are situations (such as the OsProtedtedEvent)
when the user data can not be specified when this object was constructed so that this method is necessary to set the user data. Always returns OS_SUCCESS.
Return the event data that was signaled by the notifier task.
Return OS_NOT_SIGNALED if the event has not been signaled (or has already been cleared), otherwise return OS_SUCCESS.
Return the user data specified when this object was constructed.
Always returns OS_SUCCESS.
|
virtual |
Return TRUE if the event has been signaled, otherwise FALSE.
