epicsEvent.h
APIs for the epicsEvent binary semaphore.
Defines the C++ and C API’s for a simple binary semaphore. If multiple threads are waiting on the same event, only one of them will be woken when the event is signaled.
The primary use of an event semaphore is for thread synchronization. An example of using an event semaphore is a consumer thread that processes requests from one or more producer threads. For example:
When creating the consumer thread also create an epicsEvent.
epicsEvent event;
while(1) {
pevent.wait();
while( {more work} ) {
{process work}
}
}
pevent.trigger();
Defines
-
epicsEventWaitStatus
Old name provided for backwards compatibility.
-
epicsEventWaitOK
Old name provided for backwards compatibility.
-
epicsEventWaitError
Old name provided for backwards compatibility.
-
epicsEventSignal(ID)
A synonym for epicsEventTrigger().
- Parameters:
ID – The event identifier.
- Returns:
Status indicator.
Typedefs
-
typedef struct epicsEventOSD *epicsEventId
An identifier for an epicsEvent for use with the C API.
Enums
-
enum epicsEventStatus
Return status from several C API routines.
Values:
-
enumerator epicsEventOK
-
enumerator epicsEventWaitTimeout
-
enumerator epicsEventError
-
enumerator epicsEventOK
-
enum epicsEventInitialState
Possible initial states of a new epicsEvent.
Values:
-
enumerator epicsEventEmpty
-
enumerator epicsEventFull
-
enumerator epicsEventEmpty
Functions
-
epicsEventId epicsEventCreate(epicsEventInitialState initialState)
Create an epicsEvent for use from C code, or return NULL.
- Parameters:
initialState – Starting state,
epicsEventEmpty
orepicsEventFull
.- Returns:
An identifier for the new event, or NULL if one not be created.
-
epicsEventId epicsEventMustCreate(epicsEventInitialState initialState)
Create an epicsEvent for use from C code.
This routine does not return if the object could not be created.
- Parameters:
initialState – Starting state,
epicsEventEmpty
orepicsEventFull
.- Returns:
An identifier for the new event.
-
void epicsEventDestroy(epicsEventId id)
Destroy an epicsEvent and any resources it holds.
No calls to any epicsEventWait routines can be active when this call is made.
- Parameters:
id – The event identifier.
-
epicsEventStatus epicsEventTrigger(epicsEventId id)
Trigger an event i.e. ensures the next or current call to wait completes.
Note
This method may be called from a VxWorks or RTEMS interrupt handler.
- Parameters:
id – The event identifier.
- Returns:
Status indicator.
-
void epicsEventMustTrigger(epicsEventId id)
Trigger an event.
This routine does not return if the identifier is invalid.
- Parameters:
id – The event identifier.
-
epicsEventStatus epicsEventWait(epicsEventId id)
Wait for an event.
Note
Blocks until full.
- Parameters:
id – The event identifier.
- Returns:
Status indicator.
-
void epicsEventMustWait(epicsEventId id)
Wait for an event (see epicsEventWait()).
This routine does not return if the identifier is invalid.
- Parameters:
id – The event identifier.
-
epicsEventStatus epicsEventWaitWithTimeout(epicsEventId id, double timeout)
Wait an the event or until the specified timeout period is over.
Note
Blocks until full or timeout.
- Parameters:
id – The event identifier.
timeout – The timeout delay in seconds. A timeout of zero is equivalent to calling epicsEventTryWait(); NaN or any value too large to be represented to the target OS is equivalent to no timeout.
- Returns:
Status indicator.
-
epicsEventStatus epicsEventTryWait(epicsEventId id)
Similar to wait() except that if the event is currently empty the call will return immediately with status
epicsEventWaitTimeout
.- Parameters:
id – The event identifier.
- Returns:
Status indicator,
epicsEventWaitTimeout
when the event is empty.
-
void epicsEventShow(epicsEventId id, unsigned int level)
Display information about the semaphore.
Note
The information displayed is architecture dependent.
- Parameters:
id – The event identifier.
level – An unsigned int for the level of information to be displayed.
-
class epicsEvent
- #include <epicsEvent.h>
A binary semaphore.
An epicsEvent is a binary semaphore that can be empty or full. When empty, a wait() issued before the next call to trigger() will block. When full, the next call to wait() will empty the event and return immediately. Multiple calls to trigger() may occur between wait() calls but will have the same effect as a single trigger(), filling the event.
Public Functions
-
epicsEvent(epicsEventInitialState initial = epicsEventEmpty)
Constructor.
- Parameters:
initial – State when created, empty (the default) or full.
-
~epicsEvent()
Destroy the epicsEvent and any resources it holds. No calls to wait() can be active when this call is made.
-
void trigger()
Trigger the event i.e. ensures the next or current call to wait completes. This method may be called from a vxWorks or RTEMS interrupt handler.
-
void wait()
Wait for the event.
Note
Blocks until full.
-
bool wait(double timeout)
Wait for the event or until the specified timeout.
- Parameters:
timeout – The timeout delay in seconds. A timeout of zero is equivalent to calling tryWait(); NaN or any value too large to be represented to the target OS is equivalent to no timeout.
- Returns:
True if the event was triggered, False if it timed out.
-
bool tryWait()
Similar to wait() except that if the event is currently empty the call will return immediately.
- Returns:
True if the event was full (triggered), False if empty.
-
void show(unsigned level) const
Display information about the semaphore.
Note
The information displayed is architecture dependent.
- Parameters:
level – An unsigned int for the level of information to be displayed.
Private Members
-
epicsEvent(epicsEventInitialState initial = epicsEventEmpty)