epicsEvent.h File Reference

APIs for the epicsEvent binary semaphore. More...

#include "libComAPI.h"
#include "osdEvent.h"

Include dependency graph for epicsEvent.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	epicsEvent
	A binary semaphore. More...

Macros
#define	epicsEventWaitStatus   epicsEventStatus
	Old name provided for backwards compatibility.
#define	epicsEventWaitOK   epicsEventOK
	Old name provided for backwards compatibility.
#define	epicsEventWaitError   epicsEventError
	Old name provided for backwards compatibility.
#define	epicsEventSignal(ID)   epicsEventMustTrigger(ID)
	A synonym for epicsEventTrigger().

Typedefs
typedef struct epicsEventOSD *	epicsEventId
	An identifier for an epicsEvent for use with the C API.

Enumerations
enum	epicsEventStatus { epicsEventOK = 0 , epicsEventWaitTimeout , epicsEventError }
	Return status from several C API routines. More...
enum	epicsEventInitialState { epicsEventEmpty , epicsEventFull }
	Possible initial states of a new epicsEvent. More...

Functions
LIBCOM_API epicsEventId	epicsEventCreate (epicsEventInitialState initialState)
	Create an epicsEvent for use from C code, or return NULL.
LIBCOM_API epicsEventId	epicsEventMustCreate (epicsEventInitialState initialState)
	Create an epicsEvent for use from C code.
LIBCOM_API void	epicsEventDestroy (epicsEventId id)
	Destroy an epicsEvent and any resources it holds.
LIBCOM_API epicsEventStatus	epicsEventTrigger (epicsEventId id)
	Trigger an event i.e. ensures the next or current call to wait completes.
LIBCOM_API void	epicsEventMustTrigger (epicsEventId id)
	Trigger an event.
LIBCOM_API epicsEventStatus	epicsEventWait (epicsEventId id)
	Wait for an event.
LIBCOM_API void	epicsEventMustWait (epicsEventId id)
	Wait for an event (see epicsEventWait()).
LIBCOM_API epicsEventStatus	epicsEventWaitWithTimeout (epicsEventId id, double timeout)
	Wait an the event or until the specified timeout period is over.
LIBCOM_API epicsEventStatus	epicsEventTryWait (epicsEventId id)
	Similar to wait() except that if the event is currently empty the call will return immediately with status epicsEventWaitTimeout.
LIBCOM_API void	epicsEventShow (epicsEventId id, unsigned int level)
	Display information about the semaphore.

Detailed Description

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();

Definition in file epicsEvent.h.

Macro Definition Documentation

epicsEventWaitStatus

#define epicsEventWaitStatus   epicsEventStatus

Definition at line 57 of file epicsEvent.h.

epicsEventWaitOK

#define epicsEventWaitOK   epicsEventOK

Definition at line 59 of file epicsEvent.h.

epicsEventWaitError

#define epicsEventWaitError   epicsEventError

Definition at line 61 of file epicsEvent.h.

epicsEventSignal

#define epicsEventSignal

(

ID

)

epicsEventMustTrigger(ID)

Parameters

ID	The event identifier.

Returns

Status indicator.

Definition at line 175 of file epicsEvent.h.

Typedef Documentation

epicsEventId

typedef struct epicsEventOSD* epicsEventId

Definition at line 47 of file epicsEvent.h.

Enumeration Type Documentation

epicsEventStatus

enum epicsEventStatus

Definition at line 50 of file epicsEvent.h.

epicsEventInitialState

enum epicsEventInitialState

Definition at line 64 of file epicsEvent.h.

Function Documentation

epicsEventCreate()

LIBCOM_API epicsEventId epicsEventCreate

(

epicsEventInitialState

initialState

)

Parameters

initialState

Starting state, epicsEventEmpty or epicsEventFull.

Returns

An identifier for the new event, or NULL if one not be created.

epicsEventMustCreate()

LIBCOM_API epicsEventId epicsEventMustCreate

(

epicsEventInitialState

initialState

)

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.

epicsEventDestroy()

LIBCOM_API void epicsEventDestroy

(

epicsEventId

id

)

No calls to any epicsEventWait routines can be active when this call is made.

Parameters

id	The event identifier.

epicsEventTrigger()

LIBCOM_API epicsEventStatus epicsEventTrigger

(

epicsEventId

id

)

Note

This method may be called from a VxWorks or RTEMS interrupt handler.

Parameters

id	The event identifier.

Returns

Status indicator.

epicsEventMustTrigger()

LIBCOM_API void epicsEventMustTrigger

(

epicsEventId

id

)

This routine does not return if the identifier is invalid.

Parameters

id	The event identifier.

epicsEventWait()

LIBCOM_API epicsEventStatus epicsEventWait

(

epicsEventId

id

)

Note

Blocks until full.

Parameters

id	The event identifier.

Returns

Status indicator.

epicsEventMustWait()

LIBCOM_API void epicsEventMustWait

(

epicsEventId

id

)

This routine does not return if the identifier is invalid.

Parameters

id	The event identifier.

epicsEventWaitWithTimeout()

LIBCOM_API epicsEventStatus epicsEventWaitWithTimeout	(	epicsEventId	id,
		double	timeout
	)

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.

epicsEventTryWait()

LIBCOM_API epicsEventStatus epicsEventTryWait

(

epicsEventId

id

)

Parameters

id	The event identifier.

Returns

Status indicator, epicsEventWaitTimeout when the event is empty.

epicsEventShow()

LIBCOM_API void epicsEventShow	(	epicsEventId	id,
		unsigned int	level
	)

Note

The information displayed is architecture dependent.

Parameters

id	The event identifier.
level	An unsigned int for the level of information to be displayed.