Embedded Multicore Building Blocks V1.0.0
Typedefs | Enumerations | Functions

Mutexes for thread synchronization. More...

Typedefs

typedef opaque_type embb_mutex_t
 Opaque type representing a mutex. More...
 
typedef opaque_type embb_spinlock_t
 Opaque type representing a spinlock. More...
 

Enumerations

enum  { EMBB_MUTEX_PLAIN, EMBB_MUTEX_RECURSIVE }
 Types of mutexes to be used in embb_mutex_init() More...
 

Functions

int embb_mutex_init (embb_mutex_t *mutex, int type)
 Initializes a mutex. More...
 
int embb_mutex_lock (embb_mutex_t *mutex)
 Waits until the mutex can be locked and locks it. More...
 
int embb_mutex_try_lock (embb_mutex_t *mutex)
 Tries to lock the mutex and returns immediately. More...
 
int embb_mutex_unlock (embb_mutex_t *mutex)
 Unlocks a locked mutex. More...
 
void embb_mutex_destroy (embb_mutex_t *mutex)
 Destroys a mutex and frees its resources. More...
 
int embb_spin_init (embb_spinlock_t *spinlock)
 Initializes a spinlock. More...
 
int embb_spin_lock (embb_spinlock_t *spinlock)
 Spins until the spinlock can be locked and locks it. More...
 
int embb_spin_try_lock (embb_spinlock_t *spinlock, unsigned int max_number_spins)
 Tries to lock the spinlock and returns if not successful. More...
 
int embb_spin_unlock (embb_spinlock_t *spinlock)
 Unlocks a locked spinlock. More...
 
void embb_spin_destroy (embb_spinlock_t *spinlock)
 Destroys a spinlock and frees its resources. More...
 

Detailed Description

Mutexes for thread synchronization.

Provides an abstraction from platform-specific mutex implementations. Plain and recursive mutexes are available, where the plain version can only be locked once by the same thread.

Typedef Documentation

typedef opaque_type embb_mutex_t

Opaque type representing a mutex.

typedef opaque_type embb_spinlock_t

Opaque type representing a spinlock.

Enumeration Type Documentation

anonymous enum

Types of mutexes to be used in embb_mutex_init()

Enumerator
EMBB_MUTEX_PLAIN 

Mutex can be locked only once by the same thread.

EMBB_MUTEX_RECURSIVE 

Mutex can be locked recursively by the same thread.

Function Documentation

int embb_mutex_init ( embb_mutex_t mutex,
int  type 
)

Initializes a mutex.

Postcondition
mutex is initialized
Returns
EMBB_SUCCESS if mutex could be initialized
EMBB_ERROR otherwise
Dynamic memory allocation
(Potentially) allocates dynamic memory
Concurrency
Not thread-safe
See also
embb_mutex_destroy()
Parameters
[out]mutexPointer to mutex
[in]typeEMBB_MUTEX_PLAIN or EMBB_MUTEX_RECURSIVE. There is no guarantee that a mutex is non-recursive if the plain type is given.
int embb_mutex_lock ( embb_mutex_t mutex)

Waits until the mutex can be locked and locks it.

Precondition
mutex is initialized
If the mutex type is plain, mutex must not be locked by the current thread.
Postcondition
If successful, mutex is locked.
Returns
EMBB_SUCCESS if mutex could be locked
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_mutex_try_lock(), embb_mutex_unlock()
Parameters
[in,out]mutexPointer to mutex
int embb_mutex_try_lock ( embb_mutex_t mutex)

Tries to lock the mutex and returns immediately.

Precondition
mutex is initialized
Postcondition
If successful, mutex is locked
Returns
EMBB_SUCCESS if mutex could be locked
EMBB_BUSY if mutex could not be locked
EMBB_ERROR if an error occurred
Concurrency
Thread-safe
See also
embb_mutex_lock(), embb_mutex_unlock()
Parameters
[in,out]mutexPointer to mutex
int embb_mutex_unlock ( embb_mutex_t mutex)

Unlocks a locked mutex.

Precondition
mutex has been locked by the current thread.
Postcondition
If successful and when the given mutex type is plain, mutex is unlocked. If its type is recursive, mutex is only unlocked if the number of successful unlocks has reached the number of successful locks done by the current thread.
Returns
EMBB_SUCCESS if the operation was successful
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_mutex_lock(), embb_mutex_try_lock()
Parameters
[in,out]mutexPointer to mutex
void embb_mutex_destroy ( embb_mutex_t mutex)

Destroys a mutex and frees its resources.

Precondition
mutex is initialized and is not NULL.
Postcondition
mutex is uninitialized
Concurrency
Not thread-safe
See also
embb_mutex_init()
Parameters
[in,out]mutexPointer to mutex
int embb_spin_init ( embb_spinlock_t spinlock)

Initializes a spinlock.

Precondition
spinlock is uninitialized
Postcondition
spinlock is initialized
Returns
EMBB_SUCCESS if spinlock could be initialized
EMBB_ERROR otherwise
Dynamic memory allocation
(Potentially) allocates dynamic memory
Concurrency
Not thread-safe
See also
embb_spinlock_destroy()
Parameters
[out]spinlockPointer to spinlock
int embb_spin_lock ( embb_spinlock_t spinlock)

Spins until the spinlock can be locked and locks it.

Note
This method yields the current thread in regular, implementation-defined intervals.
Precondition
spinlock is initialized
Postcondition
If successful, spinlock is locked.
Returns
EMBB_SUCCESS if spinlock could be locked.
EMBB_ERROR if an error occurred.
Concurrency
Thread-safe
See also
embb_spinlock_try_lock(), embb_mutex_unlock()
Parameters
[in,out]spinlockPointer to spinlock
int embb_spin_try_lock ( embb_spinlock_t spinlock,
unsigned int  max_number_spins 
)

Tries to lock the spinlock and returns if not successful.

Precondition
spinlock is initialized
Postcondition
If successful, spinlock is locked
Returns
EMBB_SUCCESS if spinlock could be locked
EMBB_BUSY if spinlock could not be locked
EMBB_ERROR if an error occurred
Concurrency
Thread-safe
See also
embb_spin_lock(), embb_spin_unlock()
Parameters
[in,out]spinlockPointer to spinlock
[in]max_number_spinsMaximal count of spins to perform, trying to acquire lock. Note that passing 0 here results in not trying to obtain the lock at all.
int embb_spin_unlock ( embb_spinlock_t spinlock)

Unlocks a locked spinlock.

Precondition
spinlock has been locked by the current thread.
Postcondition
If successful, spinlock is unlocked.
Returns
EMBB_SUCCESS if the operation was successful
EMBB_ERROR otherwise
Concurrency
Thread-safe
See also
embb_spin_lock(), embb_spin_try_lock()
Parameters
[in,out]spinlockPointer to spinlock
void embb_spin_destroy ( embb_spinlock_t spinlock)

Destroys a spinlock and frees its resources.

Precondition
spinlock is initialized and is not NULL.
Postcondition
spinlock is uninitialized
Concurrency
Not thread-safe
See also
embb_spin_init()
Parameters
[in,out]spinlockPointer to spinlock