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
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 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.
-
void unlock()
Release the semaphore.
Private Members
-
epicsMutex()
-
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
-
typedef epicsGuard<epicsDeadlockDetectMutex> guard_t