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;
The consumer thread has code containing:
while(1) {
    pevent.wait();
    while( {more work} ) {
        {process work}
    }
}
Producers create requests and issue the statement:
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
enum epicsEventInitialState

Possible initial states of a new epicsEvent.

Values:

enumerator epicsEventEmpty
enumerator epicsEventFull

Functions

epicsEventId epicsEventCreate(epicsEventInitialState initialState)

Create an epicsEvent for use from C code, or return NULL.

Parameters:

initialState – Starting state, epicsEventEmpty or epicsEventFull.

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 or epicsEventFull.

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.

inline void signal()

Signal is a synonym for trigger().

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 Functions

epicsEvent(const epicsEvent&)
epicsEvent &operator=(const epicsEvent&)

Private Members

epicsEventId id