raster pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=74556a3f901587f807758a4411a59738696796a9
commit 74556a3f901587f807758a4411a59738696796a9
Author: Jeff Grimshaw <jeffrey.w.grims...@gmail.com>
Date: Tue Mar 25 17:30:42 2014 +0900
efl/eina: Update documentatin for Eina Lock
Summary: Updated documentation for Eina Lock and related files.
Test Plan: Reviewers
Reviewers: cedric, raster
CC: cedric, raster
Differential Revision: https://phab.enlightenment.org/D650
---
src/lib/eina/eina_cow.h | 2 +-
src/lib/eina/eina_inline_lock_barrier.x | 8 +-
src/lib/eina/eina_inline_lock_posix.x | 22 +-
src/lib/eina/eina_inline_lock_win32.x | 37 +--
src/lib/eina/eina_inline_lock_wince.x | 2 +
src/lib/eina/eina_lock.h | 551 +++++++++++++++++++++++++++++---
6 files changed, 553 insertions(+), 69 deletions(-)
diff --git a/src/lib/eina/eina_cow.h b/src/lib/eina/eina_cow.h
index e7f0d20..400cfe4 100644
--- a/src/lib/eina/eina_cow.h
+++ b/src/lib/eina/eina_cow.h
@@ -27,7 +27,7 @@
*/
/**
- * @defgroup Eina_Cow_Group Lock
+ * @defgroup Eina_Cow_Group Copy On Write
*
* @brief These functions provide some helper for a pseudo Copy On Write
mechanism.
*
diff --git a/src/lib/eina/eina_inline_lock_barrier.x
b/src/lib/eina/eina_inline_lock_barrier.x
index 055887f..ba2fb4d 100644
--- a/src/lib/eina/eina_inline_lock_barrier.x
+++ b/src/lib/eina/eina_inline_lock_barrier.x
@@ -1,10 +1,12 @@
typedef struct _Eina_Barrier Eina_Barrier;
+/** @private */
struct _Eina_Barrier
{
- int needed, called;
- Eina_Lock cond_lock;
- Eina_Condition cond;
+ int needed; /**< The number of waiting threads that will cause
the barrier to signal and reset. */
+ int called; /**< The number of threads that are waiting on this
barrier. */
+ Eina_Lock cond_lock; /**< The lock for the barrier */
+ Eina_Condition cond; /**< The condition variable for the barrier */
};
static inline Eina_Bool
diff --git a/src/lib/eina/eina_inline_lock_posix.x
b/src/lib/eina/eina_inline_lock_posix.x
index b9136fc..0de48e5 100644
--- a/src/lib/eina/eina_inline_lock_posix.x
+++ b/src/lib/eina/eina_inline_lock_posix.x
@@ -65,33 +65,35 @@ typedef pthread_spinlock_t Eina_Spinlock;
typedef Eina_Lock Eina_Spinlock;
#endif
+/** @privatesection @{ */
struct _Eina_Lock
{
#ifdef EINA_HAVE_DEBUG_THREADS
- EINA_INLIST;
+ EINA_INLIST; /**< Keeps track of the threads waiting for the lock */
#endif
- pthread_mutex_t mutex;
+ pthread_mutex_t mutex; /**< The mutex that handles the locking */
#ifdef EINA_HAVE_DEBUG_THREADS
- pthread_t lock_thread_id;
- Eina_Lock_Bt_Func lock_bt[EINA_LOCK_DEBUG_BT_NUM];
- int lock_bt_num;
- Eina_Bool locked : 1;
+ pthread_t lock_thread_id; /**< The ID of the thread that currently
has the lock */
+ Eina_Lock_Bt_Func lock_bt[EINA_LOCK_DEBUG_BT_NUM]; /**< The function that
will produce a backtrace on the thread that has the lock */
+ int lock_bt_num; /**< Number of addresses in the backtrace */
+ Eina_Bool locked : 1; /**< Indicates locked or not locked */
#endif
};
struct _Eina_Condition
{
- Eina_Lock *lock;
- pthread_cond_t condition;
+ Eina_Lock *lock; /**< The lock for this condition */
+ pthread_cond_t condition; /**< The condition variable */
};
struct _Eina_RWLock
{
- pthread_rwlock_t mutex;
+ pthread_rwlock_t mutex; /**< The mutex that handles the locking */
#ifdef EINA_HAVE_DEBUG_THREADS
- pthread_t lock_thread_wid;
+ pthread_t lock_thread_wid; /**< The ID of the thread that currently
has the lock */
#endif
};
+/** @} privatesection */
EAPI extern Eina_Bool _eina_threads_activated;
diff --git a/src/lib/eina/eina_inline_lock_win32.x
b/src/lib/eina/eina_inline_lock_win32.x
index 4ae63df..2d9acb0 100644
--- a/src/lib/eina/eina_inline_lock_win32.x
+++ b/src/lib/eina/eina_inline_lock_win32.x
@@ -25,6 +25,7 @@
#include <windows.h>
#undef WIN32_LEAN_AND_MEAN
+/** @privatesection @{ */
typedef CRITICAL_SECTION Eina_Lock;
typedef struct _Eina_Condition Eina_Condition;
typedef struct _Eina_RWLock Eina_RWLock;
@@ -35,40 +36,40 @@ typedef Eina_Lock Eina_Spinlock;
#if _WIN32_WINNT >= 0x0600
struct _Eina_Condition
{
- CRITICAL_SECTION *mutex;
- CONDITION_VARIABLE condition;
+ CRITICAL_SECTION *mutex; /**< The locking mechanism for this
condition variable */
+ CONDITION_VARIABLE condition; /**< The condition variable */
};
struct _Eina_RWLock
{
- SRWLOCK mutex;
+ SRWLOCK mutex; /**< The locking mechanism */
- Eina_Bool is_read_mode : 1;
+ Eina_Bool is_read_mode : 1; /**< Indicates if the lock is a read lock */
};
#else
struct _Eina_Condition
{
- int waiters_count;
- CRITICAL_SECTION waiters_count_lock;
- CRITICAL_SECTION *mutex;
- HANDLE semaphore;
- HANDLE waiters_done;
- Eina_Bool was_broadcast;
+ int waiters_count; /**< The count of threads that are
waiting on this condition */
+ CRITICAL_SECTION waiters_count_lock; /**< The locking mechanism for the
waiters_count member */
+ CRITICAL_SECTION *mutex; /**< The locking mechanism for the
condition */
+ HANDLE semaphore; /**< Semaphore used to coordinate
waiters */
+ HANDLE waiters_done; /**< Event to trigger when all the
waiters are done */
+ Eina_Bool was_broadcast; /**< Indicates whether this
condition has signalled its waiters */
};
struct _Eina_RWLock
{
- LONG readers_count;
- LONG writers_count;
- int readers;
- int writers;
+ LONG readers_count; /**< The number of readers waiting for locks
*/
+ LONG writers_count; /**< The number of writers waiting for locks
*/
+ int readers; /**< The number of readers that have locks */
+ int writers; /**< The number of writers that have locks */
- Eina_Lock mutex;
- Eina_Condition cond_read;
- Eina_Condition cond_write;
+ Eina_Lock mutex; /**< The locking mechanism */
+ Eina_Condition cond_read; /**< The condition for readers */
+ Eina_Condition cond_write; /**< The condition for writers */
};
#endif
-
+/** @} privatesection */
EAPI extern Eina_Bool _eina_threads_activated;
EAPI extern Eina_Bool _eina_thread_tls_cb_register(Eina_TLS key,
Eina_TLS_Delete_Cb cb);
diff --git a/src/lib/eina/eina_inline_lock_wince.x
b/src/lib/eina/eina_inline_lock_wince.x
index f98adf6..95374d5 100644
--- a/src/lib/eina/eina_inline_lock_wince.x
+++ b/src/lib/eina/eina_inline_lock_wince.x
@@ -30,11 +30,13 @@ EAPI extern Eina_Bool _eina_thread_tls_cb_register(Eina_TLS
key, Eina_TLS_Delete
EAPI extern Eina_Bool _eina_thread_tls_cb_unregister(Eina_TLS key);
EAPI extern Eina_Bool _eina_thread_tls_key_add(Eina_TLS key);
+/** @privatesection @{ */
typedef HANDLE Eina_Lock;
typedef Eina_Lock Eina_Spinlock;
typedef Eina_Lock Eina_RWLock;
typedef DWORD Eina_TLS;
typedef void * Eina_Semaphore;
+/** @} privatesection */
static inline Eina_Bool
eina_lock_new(Eina_Lock *mutex)
diff --git a/src/lib/eina/eina_lock.h b/src/lib/eina/eina_lock.h
index 7c12717..d0f2e31 100644
--- a/src/lib/eina/eina_lock.h
+++ b/src/lib/eina/eina_lock.h
@@ -31,17 +31,79 @@
/**
* @defgroup Eina_Lock_Group Lock
+ *
+ * The Eina lock libraries provide thread locking and sychronization
capabilities
+ * similar to POISIX threads (pthreads), but it takes care of the platform
specific
+ * details so you don't have to.
+ *
+ * If you know how @c pthreads work, this library will look familiar to you.
+ * If you are not familiar with @c pthreads, a good overview is available
+ * <a href="https://computing.llnl.gov/tutorials/pthreads/";>here</a>
+ *
+ * The Eina lock functions are grouped into several categories to handle
different
+ * thread locking and sychronization methods:
+ * @li eina_lock_* - Functions that implement locking.
+ * @li eina_condition_* - Functions that implement condition variables.
+ * @li eina_rwlock_* - Functions that implement read/write locks.
+ * @li eina_tls_* - Functions that implement thread level storage.
+ * @li eina_semaphore_* - Functions that implement semaphores.
+ * @li eina_barrier_* - Functions that implement barriers.
+ * @li eina_spinlock_* - Functions that implement spinlocks if they are
available
+ * on the platform. If they are not available, these functuions degrade to
plain locks.
+ *
+ *
*
* @{
*/
+/**
+* @typedef Eina_Barrier
+* An opaque type for working with barrier locks.
+*
+*/
+/**
+* @typedef Eina_Lock
+* An opaque type for working with locks.
+*
+*/
+/**
+* @typedef Eina_Condition
+* An opaque type that represents a condition variable.
+*
+*/
+/**
+* @typedef Eina_RWLock
+* An opaque type for working with read/write locks.
+*
+*/
+/**
+* @typedef Eina_TLS
+* An opaque type for working with thread level storage.
+*
+*/
+/**
+* @typedef Eina_Semaphore
+* An opaque type for working with semaphores.
+*
+*/
+/**
+* @typedef Eina_Spinlock
+* An opaque type for working with spinlocks.
+*
+*/
+
+/**
+ * @typedef Eina_Lock_Result
+ * Return codes for lock operations.
+ */
typedef enum
{
- EINA_LOCK_FAIL = EINA_FALSE,
- EINA_LOCK_SUCCEED = EINA_TRUE,
- EINA_LOCK_DEADLOCK
+ EINA_LOCK_FAIL = EINA_FALSE, /**< Indicates that the lock operation
failed. */
+ EINA_LOCK_SUCCEED = EINA_TRUE, /**< Indicates that the lock operation
succeeded. */
+ EINA_LOCK_DEADLOCK /**< Indicates that the lock is
deadlocked. */
} Eina_Lock_Result;
+/** Type definition for deallocation callbacks for thread level sotrage data.
A simple function pointer. */
typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
#ifdef _WIN32_WCE
@@ -52,80 +114,495 @@ typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
# include "eina_inline_lock_posix.x"
#endif
+/** A type definition for warning that a function was called from somewhere
other than the EFL main loop. */
EAPI extern Eina_Error EINA_ERROR_NOT_MAIN_LOOP;
-/** @relates static Eina_Bool eina_lock_new(_Eina_Lock *mutex) */
+/**
+ * @brief Initializes a new Eina_Lock
+ *
+ * This function initializes an Eina_Lock with appropriate values.
+ * These values are platform dependent as is the structure of the Eina_Lock
+ * itself.
+ *
+ * @param mutex The Eina_Lock structure to be initialized.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_lock_new(Eina_Lock *mutex);
-/** @relates static void eina_lock_free(_Eina_Lock *mutex) */
+
+/**
+ * @brief Deallocates an Eina_Lock
+ *
+ * This function deallocates an Eina_Lock and does any platform dependent
+ * cleanup that is required.
+ *
+ * @param mutex The Eina_Lock structure to be deallocated.
+ *
+ */
static inline void eina_lock_free(Eina_Lock *mutex);
-/** @relates static Eina_Lock_Result eina_lock_take(_Eina_Lock *mutex) */
+
+/**
+ * @brief Attempts to take a lock.
+ *
+ * This function attempts to gain a lock on the indicated Eina_Lock. If the
+ * underlying Eina_Lock is locked already, this call will block until
+ * the lock is released. This is appropriate in many cases, but consider using
+ * #eina_lock_take_try if you don't need to block.
+ *
+ * @param mutex The Eina_Lock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails
because
+ * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some
other
+ * condition causes the take to fail, EINA_LOCK_FAIL is returned.
+ *
+ */
static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
-/** @relates static Eina_Lock_Result eina_lock_take_try(_Eina_Lock *mutex) */
+
+/**
+ * @brief Attempts to take a lock.
+ *
+ * This function attempts to gain a lock on the indicated Eina_Lock.
Identical
+ * to #eina_lock_take, but returns immediately if the lock is already taken.
+ *
+ * @param mutex The Eina_Lock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails
because
+ * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some
other
+ * condition causes the take to fail, EINA_LOCK_FAIL is returned.
+ *
+ */
static inline Eina_Lock_Result eina_lock_take_try(Eina_Lock *mutex);
-/** @relates static Eina_Lock_Result eina_lock_release(_Eina_Lock *mutex) */
+
+/**
+ * @brief Releases a lock.
+ *
+ * This function will release the lock on the indicated Eina_Lock. If
successful,
+ * and EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
+ * about the locking process is removed (e.g. thread number and backtrace for
POSIX).
+ *
+ * @param mutex The Eina_Lock to release.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If it fails, EINA_LOCK_FAIL
is
+ * returned.
+ *
+ */
static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex);
-/** @relates static void eina_lock_debug(const _Eina_Lock *mutex) */
+
+/**
+ * @brief Print debug information about a lock.
+ *
+ * This function will print debug information for @p mutex. The information
is
+ * platform dependant. On POSIX systems it will print the address of @p
mutex,
+ * lock state, thread number and a backtrace.
+ *
+ * @param mutex The Eina_Lock to print debug info for.
+ *
+ * @note If EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing.
+ * @note This function is implemented on Win32 or WinCE, but it will
+ * not produce any output, regardless of EINA_HAVE_DEBUG_THREADS being set.
+ */
static inline void eina_lock_debug(const Eina_Lock *mutex);
-/** @relates static Eina_Bool eina_condition_new(_Eina_Condition *cond,
_Eina_Lock *mutex) */
+/**
+ * @brief Initializes a new condition variable
+ *
+ * This function initializes an Eina_Condition structure and associates it with
+ * an existing lock.
+ *
+ * Condition variables are used to coordinate actions between threads. See
+ * <a href="https://computing.llnl.gov/tutorials/pthreads/#ConVarOverview";>
Condition Varable Overview </a>
+ * for an introduction to condition variables and their use.
+ *
+ * @param cond The condition variable to create.
+ * @param mutex The _Eina_Lock structure that controls access to this
condition variable.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock
*mutex);
-/** @relates static void eina_condition_free(_Eina_Condition *cond) */
+
+/**
+ * @brief Deallocates a condition variable
+ *
+ * This function deallocates a condition variable and does any platform
dependent
+ * cleanup that is required.
+ *
+ * @param cond The condition variable to be deallocated.
+ *
+ */
static inline void eina_condition_free(Eina_Condition *cond);
-/** @relates static Eina_Bool eina_condition_wait(_Eina_Condition *cond) */
+
+/**
+ * @brief Causes a thread to wait until signaled by the condition.
+ *
+ * This function makes a thread block until a signal is sent to it via @p
cond.
+ *
+ * @param cond The Eina_Condition upon which the thread will wait.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ */
static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
-/** @relates static Eina_Bool eina_condition_timedwait(_Eina_Condition *cond,
double t) */
+
+/**
+ * @brief Causes a thread to wait until signaled by the condition or a
+ * timeout is reached.
+ *
+ * This function makes a thread block until either a signal is sent to it via
+ * @p cond or @p t seconds have passed.
+ *
+ * @param cond The Eina_Condition upon which the thread will wait.
+ * @param t The maximum amount of time to wait, in seconds.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double
t);
-/** @relates static Eina_Bool eina_condition_broadcast(_Eina_Condition *cond)
*/
+
+/**
+ * @brief Signal all threads waiting for a condition.
+ *
+ * This function sends a signal to all the threads waiting on the condition @p
cond.
+ * If you know for sure that there is only one thread waiting, use
eina_condition_signal
+ * instead to gain a little optimization.
+ *
+ * @param cond The Eina_Condition that will signal all its waiting threads.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond);
-/** @relates static Eina_Bool eina_condition_signal(_Eina_Condition *cond) */
+
+/**
+ * @brief Signal a thread waiting for a condition.
+ *
+ * This function sends a signal to a thread waiting on the condition @p cond.
+ * If you do not know for sure that there is only one thread waiting, use
+ * eina_condition_broadcast instead.
+ *
+ * If there is more than one thread waiting on this condition, one of them
will
+ * be signalled, but which one is undefined.
+ *
+ * @param cond The Eina_Condition that will signal its waiting thread.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_condition_signal(Eina_Condition *cond);
-/** @relates static Eina_Bool eina_rwlock_new(_Eina_RWLock *mutex) */
+
+/**
+ * @brief Initializes a new Eina_RWLock
+ *
+ * This function initializes an Eina_RWLock with appropriate values.
+ * These values are platform dependent as is the structure of the Eina_RWLock
+ * itself.
+ *
+ * @param mutex The Eina_RWLock to be initialized.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex);
-/** @relates static void eina_rwlock_free(_Eina_RWLock *mutex) */
+
+/**
+ * @brief Deallocates an Eina_RWLock
+ *
+ * This function deallocates an Eina_RWLock and does any platform dependent
+ * cleanup that is required.
+ *
+ * @param mutex The Eina_RWLock structure to be deallocated.
+ *
+ */
static inline void eina_rwlock_free(Eina_RWLock *mutex);
-/** @relates static Eina_Lock_Result eina_rwlock_take_read(_Eina_RWLock
*mutex) */
+
+/**
+ * @brief Attempts to take a read lock.
+ *
+ * This function attempts to gain a read lock on the indicated Eina_RWLock.
If
+ * the Eina_RWLock is write locked, this call will block until
+ * the lock is released.
+ *
+ * @param mutex The Eina_RWLock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
+ * @note This function will never return EINA_LOCK_DEADLOCK.
+ *
+ */
static inline Eina_Lock_Result eina_rwlock_take_read(Eina_RWLock *mutex);
-/** @relates static Eina_Lock_Result eina_rwlock_take_write(_Eina_RWLock
*mutex) */
+
+/**
+ * @brief Attempts to take a write lock.
+ *
+ * This function attempts to gain a write lock on the indicated Eina_RWLock.
If
+ * the Eina_RWLock is locked for reading or writing, this call
+ * will block until the lock is released.
+ *
+ * @param mutex The Eina_RWLock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
+ * @note This function will never return EINA_LOCK_DEADLOCK.
+ *
+ */
static inline Eina_Lock_Result eina_rwlock_take_write(Eina_RWLock *mutex);
-/** @relates static Eina_Lock_Result eina_rwlock_release(_Eina_RWLock *mutex)
*/
+
+/**
+ * @brief Releases a lock.
+ *
+ * This function will release the lock on the indicated Eina_RWLock.
+ *
+ * @param mutex The Eina_RWLock to release.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If it fails, EINA_LOCK_FAIL
is
+ * returned.
+ *
+ */
static inline Eina_Lock_Result eina_rwlock_release(Eina_RWLock *mutex);
-/** @relates static Eina_Bool eina_tls_new(pthread_key_t *key) */
+/**
+ * @brief Initializes a new Eina_TLS, or thread level storage, to store thread
+ * specific data.
+ *
+ * This function initializes an Eina_TLS with @p key but does not set a
+ * callback to deallocate @p key when the thread exits. The implementation
+ * is platform dependent as is the structure of the Eina_TLS itself.
+ *
+ * @param key The Eina_TLS to be initialized.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_tls_new(Eina_TLS *key);
-/** @relates static Eina_Bool eina_tls_cb_new(pthread_key_t *key,
Eina_TLS_Delete_Cb delete_cb) */
+
+/**
+ * @brief Initializes a new Eina_TLS, or thread level storage, to store thread
+ * specific data.
+ *
+ * This function initializes an Eina_TLS with @p key and sets a
+ * callback to deallocate @p key when the thread exits. The implementation
+ * is platform dependent as is the structure of the Eina_TLS itself.
+ *
+ * @param key The Eina_TLS to be initialized.
+ * @param delete_cb A pointer to a function that will deallocate @p key.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_tls_cb_new(Eina_TLS *key, Eina_TLS_Delete_Cb
delete_cb);
-/** @relates static void eina_tls_free(pthread_key_t key) */
+
+/**
+ * @brief Frees an allocated Eina_TLS.
+ *
+ * This function frees the Eina_TLS @p key. The implementation
+ * is platform dependent.
+ *
+ * @param key The Eina_TLS to be freed.
+ *
+ */
static inline void eina_tls_free(Eina_TLS key);
-/** @relates static void eina_tls_get(pthread_key_t key) */
+
+/**
+ * @brief Gets the value in Eina_TLS for this thread.
+ *
+ * This function gets a pointer to the data associated with Eina_TLS @p key
for
+ * this thread. The implementation is platform dependent.
+ *
+ * @param key The Eina_TLS to be retrieved.
+ *
+ * @return A pointer to the data associated with @p key.
+ *
+ */
static inline void *eina_tls_get(Eina_TLS key);
-/** @relates static Eina_Bool eina_tls_set(pthread_key_t key, const void
*data) */
+
+/**
+ * @brief Sets the value in Eina_TLS for this thread.
+ *
+ * This function sets the value associated with @p key to the pointer to the
data
+ * @p data. The implementation is platform dependent.
+ *
+ * @param key The Eina_TLS to be set.
+ * @param data A pointer to the data to be stored.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data);
-/** @relates static Eina_Bool eina_semaphore_new(sem_t *sem, int count_init) */
+
+
+/**
+ * @brief Initializes a new Eina_Semaphore
+ *
+ * This function initializes an unnamed Eina_Semaphore with appropriate
values.
+ * These values are platform dependent.
+ *
+ *
+ * Be aware that the behavior of the parameter @p count_init differs by
+ * platform.
+ *
+ * @li POSIX: Indicates whether this semaphore can be shared by between
processes. Greater than 0 == shared.
+ * @li Win32: Indicates the initial count of threads waiting on this
semaphore.
+ *
+ * @note Semaphores are not avialable on the WinCE platform.
+ *
+ * @param sem The Eina_Semaphore to be initialized.
+ * @param count_init Behavior is platofrm specific. See above.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int
count_init);
-/** @relates static Eina_Bool eina_semaphore_free(sem_t *sem) */
+
+/**
+ * @brief Frees an allocated Eina_Semaphore.
+ *
+ * This function frees the Eina_Semaphore @p sem. The implementation
+ * is platform dependent.
+ *
+ * @param sem The Eina_Semaphore to be freed.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem);
-/** @relates static Eina_Bool eina_semaphore_lock(sem_t *sem) */
+
+/**
+ * @brief Gets a lock on an Eina_Semaphore.
+ *
+ * This function locks the Eina_Semaphore @p sem. The implementation
+ * is platform dependent.
+ *
+ * @param sem The Eina_Semaphore to lock.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem);
-/** @relates static Eina_Bool eina_semaphore_release(sem_t *sem, int
count_release) */
+
+/**
+ * @brief Releases a lock on an Eina_Semaphore.
+ *
+ * This function releases a lock on the Eina_Semaphore @p sem. The
implementation
+ * is platform dependent.
+ *
+ * @param sem The Eina_Semaphore to release.
+ * @param count_release Not used.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int
count_release);
-/** @relates static Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int
needed) @since 1.8 */
+
+/**
+ * @brief Initializes a new Eina_Barrier
+ *
+ * This function initializes a new Eina_Barrier. It will set the @c needed
flag
+ * to the value of @p needed, set the barrier's @c count member to 0 and will
+ * create new Eina_Lock and Eina_Condition objects for the barrier.
+ *
+ * @param barrier The Eina_Barrier to be initialized.
+ * @param needed The number of thread waits that will cause this barrier to be
reset.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed);
-/** @relates static void eina_barrier_free(Eina_Barrier *barrier); @since 1.8
*/
+
+/**
+ * @brief Frees an allocated Eina_Barrier.
+ *
+ * This function frees the Eina_Barrier @p barrier.
+ *
+ * @param barrier The Eina_Barrier to be freed.
+ *
+ */
static inline void eina_barrier_free(Eina_Barrier *barrier);
-/** @relates static Eina_Bool eina_barrier_wait(Eina_Barrier *barrier); @since
1.8 */
+
+/**
+ * @brief Increments the count of threads that are waiting on @p barrier.
+ *
+ * When the count of threads reaches the @c needed value for the barrier, all
+ * waiting threads will be notified via eina_condition_broadcast.
+ *
+ * @param barrier The Eina_Barrier to be incremented.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier);
-/** @relates static Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
@since 1.8 */
+
+/**
+ * @brief Initializes a new Eina_Spinlock
+ *
+ * This function initializes a new Eina_Spinlock, if spinlocks are available.
If
+ * spinlocks are not avialable, it will create a new Eina_Lock.
+ *
+ *@note Spinlocks are only implemented on the POSIX platform and are only
available
+ *if EINA_HAVE_POSIX_SPINLOCK is defined. All other platforms will get a new
Eina_Lock.
+ *
+ * @param spinlock The Eina_Spinlock to be initialized.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
+ *
+ */
static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
-/** @relates static Eina_Lock_Result eina_spinlock_take(Eina_Spinlock
*spinlock); @since 1.8 */
+
+/**
+ * @brief Attempts to take a spinlock.
+ *
+ * This function attempts to gain a lock on the indicated Eina_Spinlock. If
the
+ * underlying Eina_Spinlock is locked already, this call will block until
+ * the lock is released. This is appropriate in many cases, but consider using
+ * #eina_spinlock_take_try if you don't need to block.
+ *
+ * @param spinlock The Eina_Spinlock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails
because
+ * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some
other
+ * condition causes the take to fail, EINA_LOCK_FAIL is returned.
+ *
+ */
static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
-/** @relates static Eina_Lock_Result eina_spinlock_take(Eina_Spinlock
*spinlock); @since 1.8 */
+
+/**
+ * @brief Attempts to take a spinlock.
+ *
+ * This function attempts to gain a lock on the indicated Eina_Spinlock.
Identical
+ * to #eina_lock_take, but returns immediately if the lock is already taken.
+ *
+ * @param spinlock The Eina_Spinlock to take.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails
because
+ * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some
other
+ * condition causes the take to fail, EINA_LOCK_FAIL is returned.
+ *
+ */
static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
-/** @relates static Eina_Lock_Result eina_spinlock_release(Eina_Spinlock
*spinlock); @since 1.8 */
+
+/**
+ * @brief Releases a spinlock.
+ *
+ * This function will release the lock on the indicated Eina_Spinlock. If
successful,
+ * and EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
+ * about the locking process is removed (e.g. thread number and backtrace for
POSIX).
+ *
+ * @param spinlock The Eina_Spinlock to release.
+ *
+ * @return Returns EINA_LOCK_SUCCEED on success, else EINA_LOCK_FAIL.
+ *
+ */
static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock);
-/** @relates static void eina_spinlock_free(Eina_Spinlock *spinlock); @since
1.8 */
+
+/**
+ * @brief Deallocates an Eina_Spinlock
+ *
+ * This function deallocates an Eina_Spinlock and does any platform dependent
+ * cleanup that is required.
+ *
+ * @param spinlock The Eina_Spinlock to be deallocated.
+ *
+ */
static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
#ifdef EINA_HAVE_DEBUG_THREADS
--
