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:

Macros
#define	epicsEventWaitStatus epicsEventStatus
	Old name provided for backwards compatibility. More...

#define	epicsEventWaitOK epicsEventOK
	Old name provided for backwards compatibility. More...

#define	epicsEventWaitError epicsEventError
	Old name provided for backwards compatibility. More...

#define	epicsEventSignal(ID) epicsEventMustTrigger(ID)
	A synonym for epicsEventTrigger(). More...

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

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. More...

LIBCOM_API epicsEventId	epicsEventMustCreate (epicsEventInitialState initialState)
	Create an epicsEvent for use from C code. More...

LIBCOM_API void	epicsEventDestroy (epicsEventId id)
	Destroy an epicsEvent and any resources it holds. More...

LIBCOM_API epicsEventStatus	epicsEventTrigger (epicsEventId id)
	Trigger an event i.e. ensures the next or current call to wait completes. More...

LIBCOM_API void	epicsEventMustTrigger (epicsEventId id)
	Trigger an event. More...

LIBCOM_API epicsEventStatus	epicsEventWait (epicsEventId id)
	Wait for an event. More...

LIBCOM_API void	epicsEventMustWait (epicsEventId id)
	Wait for an event (see epicsEventWait()). More...

LIBCOM_API epicsEventStatus	epicsEventWaitWithTimeout (epicsEventId id, double timeOut)
	Wait an the event or until the specified timeout period is over. More...

LIBCOM_API epicsEventStatus	epicsEventTryWait (epicsEventId id)
	Similar to wait() except that if the event is currenly empty the call will return immediately with status `epicsEventWaitTimeout`. More...

LIBCOM_API void	epicsEventShow (epicsEventId id, unsigned int level)
	Display information about the semaphore. More...

Detailed Description

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 signalled.

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

#define epicsEventSignal ( ID ) epicsEventMustTrigger(ID)

A synonym for epicsEventTrigger().

Parameters

ID	The event identifier.

Returns: Status indicator.

Definition at line 172 of file epicsEvent.h.

#define epicsEventWaitError epicsEventError

Old name provided for backwards compatibility.

Definition at line 60 of file epicsEvent.h.

#define epicsEventWaitOK epicsEventOK

Old name provided for backwards compatibility.

Definition at line 58 of file epicsEvent.h.

#define epicsEventWaitStatus epicsEventStatus

Old name provided for backwards compatibility.

Definition at line 56 of file epicsEvent.h.

Typedef Documentation

typedef struct epicsEventOSD* epicsEventId

An identifier for an epicsEvent for use with the C API.

Definition at line 46 of file epicsEvent.h.

Enumeration Type Documentation

enum epicsEventInitialState

Possible initial states of a new epicsEvent.

Enumerator
epicsEventEmpty
epicsEventFull

Definition at line 63 of file epicsEvent.h.

              {
     epicsEventEmpty,
     epicsEventFull
 } epicsEventInitialState;

enum epicsEventStatus

Return status from several C API routines.

Enumerator
epicsEventOK
epicsEventWaitTimeout
epicsEventError

Definition at line 49 of file epicsEvent.h.

              {
     epicsEventOK = 0,
     epicsEventWaitTimeout,
     epicsEventError
 } epicsEventStatus;

Function Documentation

LIBCOM_API 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.

Definition at line 47 of file osdEvent.c.

 {
     epicsEventId pevent = malloc(sizeof(*pevent));
 
     if (pevent) {
         int status = pthread_mutex_init(&pevent->mutex, 0);
 
         pevent->isFull = (init == epicsEventFull);
         if (status) {
             printStatus(status, "pthread_mutex_init", "epicsEventCreate");
         } else {
             status = pthread_cond_init(&pevent->cond, 0);
             if (!status)
                 return pevent;
             printStatus(status, "pthread_cond_init", "epicsEventCreate");
             status = pthread_mutex_destroy(&pevent->mutex);
             checkStatus(status, "pthread_mutex_destroy", "epicsEventCreate");
         }
         free(pevent);
     }
     return NULL;
 }

LIBCOM_API 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.

Definition at line 70 of file osdEvent.c.

 {
     int status = pthread_mutex_destroy(&pevent->mutex);
 
     checkStatus(status, "pthread_mutex_destroy", "epicsEventDestroy");
     status = pthread_cond_destroy(&pevent->cond);
     checkStatus(status, "pthread_cond_destroy", "epicsEventDestroy");
     free(pevent);
 }

LIBCOM_API 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.

Definition at line 106 of file epicsEvent.cpp.

 {
     epicsEventId id = epicsEventCreate (initialState);
 
     if (!id)
         cantProceed ("epicsEventMustCreate");
     return id;
 }

LIBCOM_API void epicsEventMustTrigger ( epicsEventId id )

Trigger an event.

This routine does not return if the identifier is invalid.

Parameters

id	The event identifier.

Definition at line 116 of file epicsEvent.cpp.

                                                         {
     epicsEventStatus status = epicsEventTrigger (id);
 
     if (status != epicsEventOK)
         cantProceed ("epicsEventMustTrigger");
 }

LIBCOM_API 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.

Definition at line 123 of file epicsEvent.cpp.

                                                      {
     epicsEventStatus status = epicsEventWait (id);
 
     if (status != epicsEventOK)
         cantProceed ("epicsEventMustWait");
 }

LIBCOM_API void epicsEventShow	(	epicsEventId	id,
		unsigned int	level
	)

Display information about the semaphore.

Note: The information displayed is architecture dependant.

Parameters

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

Definition at line 150 of file osdEvent.c.

 {
     printf("epicsEvent %p: %s\n", pevent,
         pevent->isFull ? "full" : "empty");
     if (level > 0)
         printf("    pthread_mutex = %p, pthread_cond = %p\n",
             &pevent->mutex, &pevent->cond);
 }

LIBCOM_API 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.

Definition at line 80 of file osdEvent.c.

 {
     int status = pthread_mutex_lock(&pevent->mutex);
 
     checkStatusReturn(status, "pthread_mutex_lock", "epicsEventTrigger");
     if (!pevent->isFull) {
         pevent->isFull = 1;
         status = pthread_cond_signal(&pevent->cond);
         checkStatus(status, "pthread_cond_signal", "epicsEventTrigger");
     }
     status = pthread_mutex_unlock(&pevent->mutex);
     checkStatusReturn(status, "pthread_mutex_unlock", "epicsEventTrigger");
     return epicsEventOK;
 }

LIBCOM_API epicsEventStatus epicsEventTryWait ( epicsEventId id )

Similar to wait() except that if the event is currenly empty the call will return immediately with status epicsEventWaitTimeout.

Parameters

id	The event identifier.

Returns: Status indicator, epicsEventWaitTimeout when the event is empty.

Definition at line 145 of file osdEvent.c.

 {
     return epicsEventWaitWithTimeout(id, 0.0);
 }

LIBCOM_API epicsEventStatus epicsEventWait ( epicsEventId id )

Wait for an event.

Note: Blocks until full.

Parameters

id	The event identifier.

Returns: Status indicator.

Definition at line 95 of file osdEvent.c.

 {
     epicsEventStatus result = epicsEventOK;
     int status = pthread_mutex_lock(&pevent->mutex);
 
     checkStatusReturn(status, "pthread_mutex_lock", "epicsEventWait");
     while (!pevent->isFull) {
         status = pthread_cond_wait(&pevent->cond, &pevent->mutex);
         if (status) {
             printStatus(status, "pthread_cond_wait", "epicsEventWait");
             result = epicsEventError;
             goto release;
         }
     }
     pevent->isFull = 0;
     result = epicsEventOK;
 release:
     status = pthread_mutex_unlock(&pevent->mutex);
     checkStatusReturn(status, "pthread_mutex_unlock", "epicsEventWait");
     return result;
 }

LIBCOM_API 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.

Returns: Status indicator.

Definition at line 117 of file osdEvent.c.

 {
     epicsEventStatus result = epicsEventOK;
     int status = pthread_mutex_lock(&pevent->mutex);
 
     checkStatusReturn(status, "pthread_mutex_lock", "epicsEventWaitWithTimeout");
     if (!pevent->isFull) {
         struct timespec wakeTime;
 
         convertDoubleToWakeTime(timeout, &wakeTime);
         while (!status && !pevent->isFull) {
             status = pthread_cond_timedwait(&pevent->cond, &pevent->mutex,
                 &wakeTime);
         }
         if (status) {
             result = (status == ETIMEDOUT) ?
                 epicsEventWaitTimeout : epicsEventError;
             goto release;
         }
     }
     pevent->isFull = 0;
 release:
     status = pthread_mutex_unlock(&pevent->mutex);
     checkStatusReturn(status, "pthread_mutex_unlock", "epicsEventWaitWithTimeout");
     return result;
 }

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation