StateOS
Loading...
Searching...
No Matches
Mutex

mutexes with configurable type, protocol and robustness More...

Macros

#define mtxNormal   0U
 normal mutex
#define mtxErrorCheck   1U
 error checking mutex
#define mtxRecursive   2U
 recursive mutex
#define mtxDefault   mtxNormal
 default mutex type
#define mtxPrioNone   0U
 none
#define mtxPrioInherit   4U
 priority inheritance mutex
#define mtxPrioProtect   8U
 priority protected mutex (ICPP, POSIX PTHREAD_PRIO_PROTECT): the owner runs at least
#define mtxStalled   0U
 stalled mutex
#define mtxRobust   16U
 robust mutex
#define mtxInconsistent   32U
 inconsistent mutex
#define OS_MTX(mtx, mode, ...)
 define and initialize a mutex object
#define static_MTX(mtx, mode, ...)
 static alias of OS_MTX()
#define MTX_INIT(mode, ...)
 create and initialize a mutex object
#define MTX_CREATE(mode, ...)
 create and initialize a mutex object
#define MTX_NEW   MTX_CREATE
 alias of MTX_CREATE()

Functions

void mtx_init (mtx_t *mtx, unsigned mode, unsigned prio)
 initialize a mutex object
mtx_t * mtx_create (unsigned mode, unsigned prio)
 create and initialize a new mutex object
mtx_t * mtx_new (unsigned mode, unsigned prio)
 alias of mtx_create()
void mtx_reset (mtx_t *mtx)
 reset the mutex object and wake up all waiting tasks with 'E_STOPPED' event value
void mtx_kill (mtx_t *mtx)
 alias of mtx_reset()
void mtx_destroy (mtx_t *mtx)
 reset the mutex object, wake up all waiting tasks with 'E_DELETED' event value and free allocated resource
void mtx_delete (mtx_t *mtx)
 alias of mtx_destroy()
unsigned mtx_prio (mtx_t *mtx)
 get priority of given mutex
int mtx_take (mtx_t *mtx)
 try to lock the mutex object, don't wait if the mutex object can't be locked immediately
int mtx_tryLock (mtx_t *mtx)
 alias of mtx_take()
int mtx_waitFor (mtx_t *mtx, cnt_t delay)
 try to lock the mutex object, wait for given duration of time if the mutex object can't be locked immediately
int mtx_waitUntil (mtx_t *mtx, cnt_t time)
 try to lock the mutex object, wait until given timepoint if the mutex object can't be locked immediately
int mtx_wait (mtx_t *mtx)
 try to lock the mutex object, wait indefinitely if the mutex object can't be locked immediately
int mtx_lock (mtx_t *mtx)
 alias of mtx_wait()
int mtx_give (mtx_t *mtx)
 try to unlock the mutex object (only owner task can unlock mutex object), don't wait if the mutex object can't be unlocked
int mtx_unlock (mtx_t *mtx)
 alias of mtx_give()

Detailed Description

mutexes with configurable type, protocol and robustness

Macro Definition Documentation

◆ OS_MTX

#define OS_MTX ( mtx,
mode,
... )
Value:
mtx_t mtx[] = { _MTX_INIT(mode, _VA_MTX(__VA_ARGS__) ) }

define and initialize a mutex object

Parameters
mtxname of a pointer to mutex object
modemutex mode (mutex type + mutex protocol + mutex robustness)
  • type: mtxNormal or mtxErrorCheck or mtxRecursive
  • protocol: mtxPrioNone or mtxPrioInherit or mtxPrioProtect
  • robustness: mtxStalled or mtxRobust
...prio: mutex priority ceiling; used only with mtxPrioProtect protocol

◆ static_MTX

#define static_MTX ( mtx,
mode,
... )
Value:
static mtx_t mtx[] = { _MTX_INIT(mode, _VA_MTX(__VA_ARGS__) ) }

static alias of OS_MTX()

◆ MTX_INIT

#define MTX_INIT ( mode,
... )
Value:
_MTX_INIT( mode, _VA_MTX(__VA_ARGS__) )

create and initialize a mutex object

Parameters
modemutex mode (mutex type + mutex protocol + mutex robustness)
  • type: mtxNormal or mtxErrorCheck or mtxRecursive
  • protocol: mtxPrioNone or mtxPrioInherit or mtxPrioProtect
  • robustness: mtxStalled or mtxRobust
...prio: mutex priority ceiling; used only with mtxPrioProtect protocol
Returns
mutex object
Note
use only in 'C' code

◆ MTX_CREATE

#define MTX_CREATE ( mode,
... )
Value:
{ MTX_INIT ( mode, _VA_MTX(__VA_ARGS__) ) }
#define MTX_INIT(mode,...)
create and initialize a mutex object
Definition osmutex.h:156

create and initialize a mutex object

Parameters
modemutex mode (mutex type + mutex protocol + mutex robustness)
  • type: mtxNormal or mtxErrorCheck or mtxRecursive
  • protocol: mtxPrioNone or mtxPrioInherit or mtxPrioProtect
  • robustness: mtxStalled or mtxRobust
...prio: mutex priority ceiling; used only with mtxPrioProtect protocol
Returns
mutex object as array (id)
Note
use only in 'C' code

Function Documentation

◆ mtx_init()

void mtx_init ( mtx_t * mtx,
unsigned mode,
unsigned prio )

initialize a mutex object

Parameters
mtxpointer to mutex object
modemutex mode (mutex type + mutex protocol + mutex robustness)
  • type: mtxNormal or mtxErrorCheck or mtxRecursive
  • protocol: mtxPrioNone or mtxPrioInherit or mtxPrioProtect
  • robustness: mtxStalled or mtxRobust
priomutex priority ceiling; used only with mtxPrioProtect protocol
Note
use only in thread mode

◆ mtx_create()

mtx_t * mtx_create ( unsigned mode,
unsigned prio )

create and initialize a new mutex object

Parameters
modemutex mode (mutex type + mutex protocol + mutex robustness)
  • type: mtxNormal or mtxErrorCheck or mtxRecursive
  • protocol: mtxPrioNone or mtxPrioInherit or mtxPrioProtect
  • robustness: mtxStalled or mtxRobust
priomutex priority ceiling; used only with mtxPrioProtect protocol
Returns
pointer to mutex object
Return values
NULLobject not created (not enough free memory)
Note
use only in thread mode

◆ mtx_reset()

void mtx_reset ( mtx_t * mtx)

reset the mutex object and wake up all waiting tasks with 'E_STOPPED' event value

Parameters
mtxpointer to mutex object
Note
use only in thread mode

◆ mtx_destroy()

void mtx_destroy ( mtx_t * mtx)

reset the mutex object, wake up all waiting tasks with 'E_DELETED' event value and free allocated resource

Parameters
mtxpointer to mutex object
Note
use only in thread mode

◆ mtx_prio()

unsigned mtx_prio ( mtx_t * mtx)

get priority of given mutex

Parameters
mtxpointer to mutex object
Returns
mutex priority
Note
use only in thread mode

◆ mtx_take()

int mtx_take ( mtx_t * mtx)

try to lock the mutex object, don't wait if the mutex object can't be locked immediately

Parameters
mtxpointer to mutex object
Return values
E_SUCCESSmutex object was successfully locked
OWNERDEADmutex object was successfully locked, previous owner has stopped
E_FAILUREmutex object can't be locked (also: the task priority is above the priority ceiling of a mtxPrioProtect mutex)
E_TIMEOUTmutex object can't be locked immediately, try again
Note
use only in thread mode

◆ mtx_waitFor()

int mtx_waitFor ( mtx_t * mtx,
cnt_t delay )

try to lock the mutex object, wait for given duration of time if the mutex object can't be locked immediately

Parameters
mtxpointer to mutex object
delayduration of time (maximum number of ticks to wait for lock the mutex object)
  • IMMEDIATE: don't wait if the mutex object can't be locked immediately
  • INFINITE: wait indefinitely until the mutex object has been locked
Return values
E_SUCCESSmutex object was successfully locked
OWNERDEADmutex object was successfully locked, previous owner has stopped
E_FAILUREmutex object can't be locked (also: the task priority is above the priority ceiling of a mtxPrioProtect mutex)
E_STOPPEDmutex object was reseted before the specified timeout expired
E_DELETEDmutex object was deleted before the specified timeout expired
E_TIMEOUTmutex object was not locked before the specified timeout expired
Note
use only in thread mode

◆ mtx_waitUntil()

int mtx_waitUntil ( mtx_t * mtx,
cnt_t time )

try to lock the mutex object, wait until given timepoint if the mutex object can't be locked immediately

Parameters
mtxpointer to mutex object
timetimepoint value
Return values
E_SUCCESSmutex object was successfully locked
OWNERDEADmutex object was successfully locked, previous owner has stopped
E_FAILUREmutex object can't be locked (also: the task priority is above the priority ceiling of a mtxPrioProtect mutex)
E_STOPPEDmutex object was reseted before the specified timeout expired
E_DELETEDmutex object was deleted before the specified timeout expired
E_TIMEOUTmutex object was not locked before the specified timeout expired
Note
use only in thread mode

◆ mtx_wait()

int mtx_wait ( mtx_t * mtx)
inline

try to lock the mutex object, wait indefinitely if the mutex object can't be locked immediately

Parameters
mtxpointer to mutex object
Return values
E_SUCCESSmutex object was successfully locked
OWNERDEADmutex object was successfully locked, previous owner has stopped
E_FAILUREmutex object can't be locked (also: the task priority is above the priority ceiling of a mtxPrioProtect mutex)
E_STOPPEDmutex object was reseted
E_DELETEDmutex object was deleted
Note
use only in thread mode

◆ mtx_give()

int mtx_give ( mtx_t * mtx)

try to unlock the mutex object (only owner task can unlock mutex object), don't wait if the mutex object can't be unlocked

Parameters
mtxpointer to mutex object
Return values
E_SUCCESSmutex object was successfully unlocked
E_FAILUREmutex object can't be unlocked
Note
use only in thread mode