epicsMutex.h File Reference

APIs for the epicsMutex mutual exclusion semaphore. More...

#include "epicsAssert.h"
#include "libComAPI.h"
#include "compilerDependencies.h"
#include "epicsGuard.h"
#include "osdMutex.h"

Include dependency graph for epicsMutex.h:

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

Go to the source code of this file.

Classes
class	epicsMutex
	The C++ API for an epicsMutex. More...
class	epicsDeadlockDetectMutex
	A semaphore for locating deadlocks in C++ code. More...

Macros
#define	newEpicsMutex   new epicsMutex(__FILE__,__LINE__)
	Create a C++ epicsMutex with current filename and line number.
#define	epicsMutexCreate()   epicsMutexOsiCreate(__FILE__,__LINE__)
	Create an epicsMutex semaphore for use from C code. More...
#define	epicsMutexMustCreate()   epicsMutexOsiMustCreate(__FILE__,__LINE__)
	Create an epicsMutex semaphore for use from C code. More...
#define	epicsMutexMustLock(ID)
	Claim a semaphore (see epicsMutexLock()). More...

Typedefs
typedef struct epicsMutexParm *	epicsMutexId
	An identifier for an epicsMutex for use with the C API.

Enumerations
enum	epicsMutexLockStatus { epicsMutexLockOK = 0, epicsMutexLockTimeout, epicsMutexLockError }

Functions
LIBCOM_API epicsMutexId epicsStdCall	epicsMutexOsiCreate (const char *pFileName, int lineno)
	Internal API, used by epicsMutexCreate().
LIBCOM_API epicsMutexId epicsStdCall	epicsMutexOsiMustCreate (const char *pFileName, int lineno)
	Internal API, used by epicsMutexMustCreate().
LIBCOM_API void epicsStdCall	epicsMutexDestroy (epicsMutexId id)
	Destroy an epicsMutex semaphore. More...
LIBCOM_API void epicsStdCall	epicsMutexUnlock (epicsMutexId id)
	Release the semaphore. More...
LIBCOM_API epicsMutexLockStatus epicsStdCall	epicsMutexLock (epicsMutexId id)
	Claim the semaphore, waiting until it's free if currently owned owned by a different thread. More...
LIBCOM_API epicsMutexLockStatus epicsStdCall	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. More...
LIBCOM_API void epicsStdCall	epicsMutexShow (epicsMutexId id, unsigned int level)
	Display information about the semaphore. More...
LIBCOM_API void epicsStdCall	epicsMutexShowAll (int onlyLocked, unsigned int level)
	Display information about all epicsMutex semaphores. More...

Detailed Description

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.

Definition in file epicsMutex.h.

Macro Definition Documentation

#define epicsMutexCreate

(

)

epicsMutexOsiCreate(__FILE__,__LINE__)

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.

Definition at line 169 of file epicsMutex.h.

#define epicsMutexMustCreate

(

)

epicsMutexOsiMustCreate(__FILE__,__LINE__)

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.

Definition at line 180 of file epicsMutex.h.

#define epicsMutexMustLock

(

ID

)

Value:

{                        \
    epicsMutexLockStatus status = epicsMutexLock(ID);   \
    assert(status == epicsMutexLockOK);                 \
}

This routine does not return if the identifier is invalid.

Parameters

ID	The mutex identifier.

Definition at line 215 of file epicsMutex.h.

Enumeration Type Documentation

enum epicsMutexLockStatus

Return status from some C API routines.

Definition at line 52 of file epicsMutex.h.

Function Documentation

LIBCOM_API void epicsStdCall epicsMutexDestroy

(

epicsMutexId

id

)

Parameters

id	The mutex identifier.

LIBCOM_API void epicsStdCall epicsMutexUnlock

(

epicsMutexId

id

)

Parameters

id	The mutex identifier.

Note

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

LIBCOM_API epicsMutexLockStatus epicsStdCall epicsMutexLock

(

epicsMutexId

id

)

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.

LIBCOM_API epicsMutexLockStatus epicsStdCall epicsMutexTryLock

(

epicsMutexId

id

)

Returns

epicsMutexLockOK if the resource is now owned by the caller.

epicsMutexLockTimeout if some other thread owns the resource.

LIBCOM_API void epicsStdCall epicsMutexShow	(	epicsMutexId	id,
		unsigned int	level
	)

Note

Results are architecture dependent.

Parameters

id	The mutex identifier.
level	Desired information level to report

LIBCOM_API void epicsStdCall epicsMutexShowAll	(	int	onlyLocked,
		unsigned int	level
	)

Note

Results are architecture dependent.

Parameters

onlyLocked	Non-zero to show only locked semaphores.
level	Desired information level to report