epicsMutex.h

APIs for the epicsMutex mutual exclusion semaphore.

Mutual exclusion semaphores are for situations requiring exclusive access to resources. An epicsMutex may be claimed recursively, i.e. taken more than once by a thread, which must release it as many times as it was taken. Recursive usage is common for a set of routines that call each other while working on an exclusive resource.

The typical C++ use of a mutual exclusion semaphore is:

epicsMutex lock;
...
...
{
    epicsMutex::guard_t G(lock); // lock
    // process resources
} // unlock
// or for compatibility
{
    epicsGuard<epicsMutex> G(lock); // lock
    // process resources
} // unlock

Note

The implementation:

  • MUST implement recursive locking

  • SHOULD implement priority inheritance and deletion safety if possible.

Defines

newEpicsMutex

Create a C++ epicsMutex with current filename and line number.

epicsMutexCreate()

Create an epicsMutex semaphore for use from C code.

This macro stores the source location of the creation call in the mutex.

Returns:

An identifier for the mutex, or NULL if one could not be created.

epicsMutexMustCreate()

Create an epicsMutex semaphore for use from C code.

This macro stores the source location of the creation call in the mutex. The routine does not return if the object could not be created.

Returns:

An identifier for the mutex.

epicsMutexMustLock(ID)

Claim a semaphore (see epicsMutexLock()).

This routine does not return if the identifier is invalid.

Parameters:
  • ID – The mutex identifier.

Typedefs

typedef struct epicsMutexParm *epicsMutexId

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

Enums

enum epicsMutexLockStatus

Return status from some C API routines.

Values:

enumerator epicsMutexLockOK
enumerator epicsMutexLockTimeout
enumerator epicsMutexLockError

Functions

epicsMutexId epicsMutexOsiCreate(const char *pFileName, int lineno)

Internal API, used by epicsMutexCreate().

epicsMutexId epicsMutexOsiMustCreate(const char *pFileName, int lineno)

Internal API, used by epicsMutexMustCreate().

void epicsMutexDestroy(epicsMutexId id)

Destroy an epicsMutex semaphore.

Parameters:

id – The mutex identifier.

void epicsMutexUnlock(epicsMutexId id)

Release the semaphore.

Note

If a thread issues recursive locks, it must call epicsMutexUnlock() as many times as it calls epicsMutexLock() or equivalents.

Parameters:

id – The mutex identifier.

epicsMutexLockStatus epicsMutexLock(epicsMutexId id)

Claim the semaphore, waiting until it’s free if currently owned owned by a different thread.

This call blocks until the calling thread can get exclusive access to the semaphore.

Note

After a successful lock(), additional recursive locks may be issued by the same thread, but each must have an associated unlock().

Parameters:

id – The mutex identifier.

Returns:

Status indicator.

epicsMutexLockStatus epicsMutexTryLock(epicsMutexId id)

Similar to epicsMutexLock() except that the call returns immediately, with the return status indicating if the semaphore is currently owned by this thread or another thread.

Returns:

epicsMutexLockOK if the resource is now owned by the caller.

Returns:

epicsMutexLockTimeout if some other thread owns the resource.

void epicsMutexShow(epicsMutexId id, unsigned int level)

Display information about the semaphore.

Note

Results are architecture dependent.

Parameters:
  • id – The mutex identifier.

  • level – Desired information level to report

void epicsMutexShowAll(int onlyLocked, unsigned int level)

Display information about all epicsMutex semaphores.

Note

Results are architecture dependent.

Parameters:
  • onlyLocked – Non-zero to show only locked semaphores.

  • level – Desired information level to report

struct epicsMutexOSD *epicsMutexOsdCreate(void)

The following are interfaces to the OS dependent implementation and should NOT be called directly by user code.

void epicsMutexOsdDestroy(struct epicsMutexOSD*)
void epicsMutexOsdUnlock(struct epicsMutexOSD*)
epicsMutexLockStatus epicsMutexOsdLock(struct epicsMutexOSD*)
epicsMutexLockStatus epicsMutexOsdTryLock(struct epicsMutexOSD*)
void epicsMutexOsdShow(struct epicsMutexOSD*, unsigned int level)
class epicsMutex
#include <epicsMutex.h>

The C++ API for an epicsMutex.

Public Types

typedef epicsGuard<epicsMutex> guard_t
typedef epicsGuard<epicsMutex> release_t

Public Functions

epicsMutex()

Create a mutual exclusion semaphore.

epicsMutex(const char *pFileName, int lineno)

Create a mutual exclusion semaphore with source location.

Note

The newEpicsMutex macro simplifies using this constructor.

Parameters:
  • *pFileName – Source file name.

  • lineno – Source line number

~epicsMutex()

Delete the semaphore and its resources.

void show(unsigned level) const

Display information about the semaphore.

Note

Results are architecture dependent.

Parameters:

level – Desired information level to report

void lock()

Claim the semaphore, waiting until it’s free if currently owned owned by a different thread.

This call blocks until the calling thread can get exclusive access to the semaphore.

Note

After a successful lock(), additional recursive locks may be issued by the same thread, but each must have an associated unlock().

void unlock()

Release the semaphore.

Note

If a thread issues recursive locks, it must call unlock() as many times as it calls lock().

bool tryLock()

Similar to lock() except that the call returns immediately if the semaphore is currently owned by another thread, giving the value false.

Returns:

True if the resource is now owned by the caller.

Returns:

False if some other thread already owns the resource.

Private Functions

epicsMutex(const epicsMutex&)
epicsMutex &operator=(const epicsMutex&)

Private Members

epicsMutexId id
class epicsDeadlockDetectMutex
#include <epicsMutex.h>

A semaphore for locating deadlocks in C++ code.

Public Types

typedef epicsGuard<epicsDeadlockDetectMutex> guard_t
typedef epicsGuard<epicsDeadlockDetectMutex> release_t
typedef unsigned hierarchyLevel_t

Public Functions

epicsDeadlockDetectMutex(unsigned hierarchyLevel_t)
~epicsDeadlockDetectMutex()
void show(unsigned level) const
void lock()
void unlock()
bool tryLock()

Private Functions

epicsDeadlockDetectMutex(const epicsDeadlockDetectMutex&)
epicsDeadlockDetectMutex &operator=(const epicsDeadlockDetectMutex&)

Private Members

epicsMutex mutex
const hierarchyLevel_t hierarchyLevel
class epicsDeadlockDetectMutex *pPreviousLevel