epicsMutex.h File Reference

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

#include "epicsAssert.h"
#include "libComAPI.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.

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

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

Functions
LIBCOM_API epicsMutexId epicsStdCall	epicsMutexOsiCreate (const char *pFileName, int lineno)
	Internal API, used by epicsMutexCreate(). More...
LIBCOM_API epicsMutexId epicsStdCall	epicsMutexOsiMustCreate (const char *pFileName, int lineno)
	Internal API, used by epicsMutexMustCreate(). More...
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

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 compatiblity
{
    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__)

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.

Definition at line 168 of file epicsMutex.h.

#define epicsMutexMustCreate

(

)

epicsMutexOsiMustCreate(__FILE__,__LINE__)

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.

Definition at line 179 of file epicsMutex.h.

#define epicsMutexMustLock

(

ID

)

Value:

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

Claim a semaphore (see epicsMutexLock()).

This routine does not return if the identifier is invalid.

Parameters

ID	The mutex identifier.

Definition at line 214 of file epicsMutex.h.

Typedef Documentation

typedef struct epicsMutexParm* epicsMutexId

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

Definition at line 48 of file epicsMutex.h.

Enumeration Type Documentation

enum epicsMutexLockStatus

Return status from some C API routines.

Enumerator
epicsMutexLockOK
epicsMutexLockTimeout
epicsMutexLockError

Definition at line 51 of file epicsMutex.h.

             {
    epicsMutexLockOK = 0,
    epicsMutexLockTimeout,
    epicsMutexLockError
} epicsMutexLockStatus;

Function Documentation

LIBCOM_API void epicsStdCall epicsMutexDestroy

(

epicsMutexId

id

)

Destroy an epicsMutex semaphore.

Parameters

id	The mutex identifier.

Definition at line 127 of file epicsMutex.cpp.

{
    epicsMutexLockStatus lockStat =
        epicsMutexOsdLock(epicsMutexGlobalLock);
    assert ( lockStat == epicsMutexLockOK );
    ellDelete(&mutexList,&pmutexNode->node);
    epicsMutexOsdDestroy(pmutexNode->id);
    VALGRIND_MEMPOOL_FREE(&freeList, pmutexNode);
    VALGRIND_MEMPOOL_ALLOC(&freeList, &pmutexNode->node, sizeof(pmutexNode->node));
    ellAdd(&freeList,&pmutexNode->node);
    epicsMutexOsdUnlock(epicsMutexGlobalLock);
}

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

Definition at line 145 of file epicsMutex.cpp.

{
    epicsMutexLockStatus status =
        epicsMutexOsdLock(pmutexNode->id);
#   ifdef LOG_LAST_OWNER
        if ( status == epicsMutexLockOK ) {
            pmutexNode->lastOwner = epicsThreadGetIdSelf();
        }
#   endif
    return status;
}

LIBCOM_API epicsMutexId epicsStdCall epicsMutexOsiCreate	(	const char *	pFileName,
		int	lineno
	)

Internal API, used by epicsMutexCreate().

Definition at line 85 of file epicsMutex.cpp.

{
    epicsMutexOSD * id;

    epicsThreadOnce(&epicsMutexOsiOnce, epicsMutexOsiInit, NULL);

    id = epicsMutexOsdCreate();
    if(!id) {
        return 0;
    }
    epicsMutexLockStatus lockStat =
        epicsMutexOsdLock(epicsMutexGlobalLock);
    assert ( lockStat == epicsMutexLockOK );
    epicsMutexParm *pmutexNode =
        reinterpret_cast < epicsMutexParm * > ( ellFirst(&freeList) );
    if(pmutexNode) {
        ellDelete(&freeList,&pmutexNode->node);
        VALGRIND_MEMPOOL_FREE(&freeList, pmutexNode);
    } else {
        pmutexNode = static_cast < epicsMutexParm * > ( calloc(1,sizeof(epicsMutexParm)) );
    }
    VALGRIND_MEMPOOL_ALLOC(&freeList, pmutexNode, sizeof(epicsMutexParm));
    pmutexNode->id = id;
#   ifdef LOG_LAST_OWNER
        pmutexNode->lastOwner = 0;
#   endif
    pmutexNode->pFileName = pFileName;
    pmutexNode->lineno = lineno;
    ellAdd(&mutexList,&pmutexNode->node);
    epicsMutexOsdUnlock(epicsMutexGlobalLock);
    return(pmutexNode);
}

LIBCOM_API epicsMutexId epicsStdCall epicsMutexOsiMustCreate	(	const char *	pFileName,
		int	lineno
	)

Internal API, used by epicsMutexMustCreate().

Definition at line 119 of file epicsMutex.cpp.

{
    epicsMutexId id = epicsMutexOsiCreate(pFileName,lineno);
    assert(id);
    return(id );
}

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

Display information about the semaphore.

Note

Results are architecture dependant.

Parameters

id	The mutex identifier.
level	Desired information level to report

Definition at line 191 of file epicsMutex.cpp.

{
#   ifdef LOG_LAST_OWNER
        char threadName [255];
        if ( pmutexNode->lastOwner ) {
#           error currently not safe to fetch name for stale thread
            epicsThreadGetName ( pmutexNode->lastOwner,
                threadName, sizeof ( threadName ) );
        }
        else {
            strcpy ( threadName, "<not used>" );
        }
        printf("epicsMutexId %p last owner \"%s\" source %s line %d\n",
            (void *)pmutexNode, threadName,
            pmutexNode->pFileName, pmutexNode->lineno);
#   else
        printf("epicsMutexId %p source %s line %d\n",
            (void *)pmutexNode, pmutexNode->pFileName,
            pmutexNode->lineno);
#   endif
    if ( level > 0 ) {
        epicsMutexOsdShow(pmutexNode->id,level-1);
    }
}

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

Display information about all epicsMutex semaphores.

Note

Results are architecture dependant.

Parameters

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

Definition at line 217 of file epicsMutex.cpp.

{
    epicsMutexParm *pmutexNode;

    if (epicsMutexOsiOnce == EPICS_THREAD_ONCE_INIT)
        return;

    printf("ellCount(&mutexList) %d ellCount(&freeList) %d\n",
        ellCount(&mutexList),ellCount(&freeList));
    epicsMutexLockStatus lockStat =
        epicsMutexOsdLock(epicsMutexGlobalLock);
    assert ( lockStat == epicsMutexLockOK );
    pmutexNode = reinterpret_cast < epicsMutexParm * > ( ellFirst(&mutexList) );
    while(pmutexNode) {
        if(onlyLocked) {
            epicsMutexLockStatus status;
            status = epicsMutexOsdTryLock(pmutexNode->id);
            if(status==epicsMutexLockOK) {
                epicsMutexOsdUnlock(pmutexNode->id);
                pmutexNode =
                    reinterpret_cast < epicsMutexParm * >
                        ( ellNext(&pmutexNode->node) );
                continue;
            }
        }
        epicsMutexShow(pmutexNode, level);
        pmutexNode =
            reinterpret_cast < epicsMutexParm * > ( ellNext(&pmutexNode->node) );
    }
    epicsMutexOsdUnlock(epicsMutexGlobalLock);
}

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.

Returns

epicsMutexLockOK if the resource is now owned by the caller.

epicsMutexLockTimeout if some other thread owns the resource.

Definition at line 158 of file epicsMutex.cpp.

{
    epicsMutexLockStatus status =
        epicsMutexOsdTryLock(pmutexNode->id);
#   ifdef LOG_LAST_OWNER
        if ( status == epicsMutexLockOK ) {
            pmutexNode->lastOwner = epicsThreadGetIdSelf();
        }
#   endif
    return status;
}

LIBCOM_API void epicsStdCall epicsMutexUnlock

(

epicsMutexId

id

)

Release the semaphore.

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.

Definition at line 140 of file epicsMutex.cpp.

{
    epicsMutexOsdUnlock(pmutexNode->id);
}