core/include/mutex.h File Reference

Mutexes. More...

Data Structures
struct	os_mutex_s
	Mutex structure. More...
Functions
os_result_t	os_mutex_init (os_mutex_t *mutex)
	initialization of mutex
os_result_t	os_mutex_get (os_mutex_t *mutex)
	Gets mutex for running thread.
os_result_t	os_mutex_tryget (os_mutex_t *mutex)
	Trial of getting the mutex for running thread.
os_result_t	os_mutex_release (os_mutex_t *mutex)
	Release the mutex.
Variables
struct os_mutex_s	os_mutex_t
	Mutex.

---

Detailed Description

Mutexes.

Author:

Piotr Romaniuk, (c) ELESOFTROM

Version:

1.1 Nov 8, 2013

A mutex (MUTually EXlusive) is synchronization object that is useful for guarding an access to common data shared between threads. When the mutex is properly used it prevents from concurrent processing of data from different threads. If one need to perform an operation on the data, first he need to own mutex. After that modification of data are protected. When he finishes mutex should be released. If this rule is applied in all locations where the data is accessed it is guaranteed that only one thread can manipulate on the data, so the access is safe. The application of mutex may be extended to exclusive code sections. In this case mutex assure that execution is only in one section. Note that inside the section interrupts are not being disabled.

The mutex must be released by the same thread that has owned it. This is important difference from semaphore, where post and wait can be performed in different threads. Releasing unlocked mutex is considered as critical condition and will throw an exception by os_bug().

The DioneOS mutex implementation allows for nesting the calls, so one thread can own it multiple times, but must release the same number times after that. In this case the mutex is released and accessible for others after the last release.

Because mutex owning operation can block the execution (it happens when the mutex is already locked) it cannot be used from ISR context nor when preemption is disabled. Nevertheless, it is possible to try to own the mutex from section where preemption is disabled (os_mutex_tryget()). If the mutex is already locked the function returns immediately with OS_WOULD_WAIT code.

---

Function Documentation

os_result_t os_mutex_get

(

os_mutex_t *

mutex

)

Gets mutex for running thread.

Call of this function can be nested in one thread.

Note:

Do not use in ISR because thread that locked the mutex (and owns it) may be interrupted by ISR. In such condition there is no way to prevent the lock up. This is general constraint and is not related to specific implementation of mutex in the system.

Parameters:

[in]

mutex

pointer to mutex structure to be owned

Returns:

OS_STATUS_OK if mutex is owned
OS_PREEMPT_DIS when os_preempt is disabled or os_bug is thrown (option is set in config.h)
os_bug() is thrown if counter is overflowed or mutex is locked by someone else but there are not ready threads

os_result_t os_mutex_init

(

os_mutex_t *

mutex

)

initialization of mutex

Parameters:

[in]

mutex

pointer to mutex structure to be initialized

Returns:

OS_STATUS_OK

os_result_t os_mutex_release

(

os_mutex_t *

mutex

)

Release the mutex.

The mutex release must be done by the same thread that has locked it (the owner). Function calls can be nested. The mutex is released when number of releases is equal to number of getting it.

Note:

It may throw os_bug(OS_BUG_MUTEX_BAD_RELEASE) or os_bug(OS_BUG_MUTEX) when current thread is not an owner of the locked mutex or the mutex is already unlocked.

Parameters:

[in]

mutex

pointer to mutex structure to be released

Returns:

OS_STATUS_OK when it succeded,
OS_PREEMPT_DIS when os_preempt is disabled (and check of that is disabled in config.h)
it may cause os_bug() when counter is overflowed, or there are no ready threads

os_result_t os_mutex_tryget

(

os_mutex_t *

mutex

)

Trial of getting the mutex for running thread.

Call of this function can be nested in one thread. The function never blocks. If it cannot own the mutex (because it is locked by other thread) it returns with OS_WOULD_WAIT.

Parameters:

[in]

mutex

pointer to mutex structure to be owned

Returns:

OS_STATUS_OK if mutex is owned,
OS_WOULD_WAIT if mutex is locked and waiting on it would block the thread.