90 lines
2.5 KiB
C
90 lines
2.5 KiB
C
#ifndef __MUTEX_H__
|
|
#define __MUTEX_H__
|
|
|
|
/**
|
|
* @file mutex.h
|
|
* @brief Core Mutex Routines
|
|
*/
|
|
|
|
#include "core.h"
|
|
#include "core_errno.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/**
|
|
* @defgroup mutex Thread Mutex Routines
|
|
* @ingroup CORE
|
|
* @{
|
|
*/
|
|
|
|
/** Opaque thread-local mutex structure */
|
|
typedef c_uintptr_t mutex_id;
|
|
|
|
#define MUTEX_DEFAULT 0x0 /**< platform-optimal lock behavior */
|
|
#define MUTEX_NESTED 0x1 /**< enable nested (recursive) locks */
|
|
#define MUTEX_UNNESTED 0x2 /**< disable nested locks */
|
|
|
|
/**
|
|
* Initialize Mutex Pool
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_init(void);
|
|
|
|
/**
|
|
* Finalize Mutex Pool
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_final(void);
|
|
|
|
/**
|
|
* Create and initialize a mutex that can be used to synchronize threads.
|
|
* @param id the memory address where the newly created mutex will be
|
|
* stored.
|
|
* @param flags Or'ed value of:
|
|
* <PRE>
|
|
* MUTEX_DEFAULT platform-optimal lock behavior.
|
|
* MUTEX_NESTED enable nested (recursive) locks.
|
|
* MUTEX_UNNESTED disable nested locks (non-recursive).
|
|
* </PRE>
|
|
* @param pool the pool from which to allocate the mutex.
|
|
* @warning Be cautious in using MUTEX_DEFAULT. While this is the
|
|
* most optimial mutex based on a given platform's performance charateristics,
|
|
* it will behave as either a nested or an unnested lock.
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_create(mutex_id *id, unsigned int flags);
|
|
/**
|
|
* Acquire the lock for the given mutex. If the mutex is already locked,
|
|
* the current thread will be put to sleep until the lock becomes available.
|
|
* @param id the mutex on which to acquire the lock.
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_lock(mutex_id id);
|
|
|
|
/**
|
|
* Attempt to acquire the lock for the given mutex. If the mutex has already
|
|
* been acquired, the call returns immediately with CORE_EBUSY. Note: it
|
|
* is important that the CORE_STATUS_IS_EBUSY(s) macro be used to determine
|
|
* if the return value was CORE_EBUSY, for portability reasons.
|
|
* @param id the mutex on which to attempt the lock acquiring.
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_trylock(mutex_id id);
|
|
|
|
/**
|
|
* Release the lock for the given mutex.
|
|
* @param id the mutex from which to release the lock.
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_unlock(mutex_id id);
|
|
|
|
/**
|
|
* Destroy the mutex and free the memory associated with the lock.
|
|
* @param id the mutex to destroy.
|
|
*/
|
|
CORE_DECLARE(status_t) mutex_delete(mutex_id id);
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#endif /* ! __MUTEX_H__ */
|