diff --git a/src/lib/eina/eina_cow.h b/src/lib/eina/eina_cow.h index e7f0d20527..400cfe473f 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 055887f85b..ba2fb4d653 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 b9136fcef5..0de48e5cc4 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 4ae63df6b6..2d9acb0188 100644 --- a/src/lib/eina/eina_inline_lock_win32.x +++ b/src/lib/eina/eina_inline_lock_win32.x @@ -25,6 +25,7 @@ #include #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 f98adf6bbe..95374d57a6 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 7c12717a11..d0f2e3154a 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 + * here + * + * 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 + * Condition Varable Overview + * 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