summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorJeff Grimshaw <jeffrey.w.grimshaw@gmail.com>2014-03-25 17:30:42 +0900
committerCarsten Haitzler (Rasterman) <raster@rasterman.com>2014-03-25 17:30:43 +0900
commit74556a3f901587f807758a4411a59738696796a9 (patch)
tree8b0ff9ec21308ad41680377a9463e83e4924f900 /src
parent7d9d42a281b88356f87aa8c0f57ff22ee0409974 (diff)
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
Diffstat (limited to 'src')
-rw-r--r--src/lib/eina/eina_cow.h2
-rw-r--r--src/lib/eina/eina_inline_lock_barrier.x8
-rw-r--r--src/lib/eina/eina_inline_lock_posix.x22
-rw-r--r--src/lib/eina/eina_inline_lock_win32.x37
-rw-r--r--src/lib/eina/eina_inline_lock_wince.x2
-rw-r--r--src/lib/eina/eina_lock.h551
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 @@
27 */ 27 */
28 28
29/** 29/**
30 * @defgroup Eina_Cow_Group Lock 30 * @defgroup Eina_Cow_Group Copy On Write
31 * 31 *
32 * @brief These functions provide some helper for a pseudo Copy On Write mechanism. 32 * @brief These functions provide some helper for a pseudo Copy On Write mechanism.
33 * 33 *
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 @@
1typedef struct _Eina_Barrier Eina_Barrier; 1typedef struct _Eina_Barrier Eina_Barrier;
2 2
3/** @private */
3struct _Eina_Barrier 4struct _Eina_Barrier
4{ 5{
5 int needed, called; 6 int needed; /**< The number of waiting threads that will cause the barrier to signal and reset. */
6 Eina_Lock cond_lock; 7 int called; /**< The number of threads that are waiting on this barrier. */
7 Eina_Condition cond; 8 Eina_Lock cond_lock; /**< The lock for the barrier */
9 Eina_Condition cond; /**< The condition variable for the barrier */
8}; 10};
9 11
10static inline Eina_Bool 12static 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;
65typedef Eina_Lock Eina_Spinlock; 65typedef Eina_Lock Eina_Spinlock;
66#endif 66#endif
67 67
68/** @privatesection @{ */
68struct _Eina_Lock 69struct _Eina_Lock
69{ 70{
70#ifdef EINA_HAVE_DEBUG_THREADS 71#ifdef EINA_HAVE_DEBUG_THREADS
71 EINA_INLIST; 72 EINA_INLIST; /**< Keeps track of the threads waiting for the lock */
72#endif 73#endif
73 pthread_mutex_t mutex; 74 pthread_mutex_t mutex; /**< The mutex that handles the locking */
74#ifdef EINA_HAVE_DEBUG_THREADS 75#ifdef EINA_HAVE_DEBUG_THREADS
75 pthread_t lock_thread_id; 76 pthread_t lock_thread_id; /**< The ID of the thread that currently has the lock */
76 Eina_Lock_Bt_Func lock_bt[EINA_LOCK_DEBUG_BT_NUM]; 77 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 */
77 int lock_bt_num; 78 int lock_bt_num; /**< Number of addresses in the backtrace */
78 Eina_Bool locked : 1; 79 Eina_Bool locked : 1; /**< Indicates locked or not locked */
79#endif 80#endif
80}; 81};
81 82
82struct _Eina_Condition 83struct _Eina_Condition
83{ 84{
84 Eina_Lock *lock; 85 Eina_Lock *lock; /**< The lock for this condition */
85 pthread_cond_t condition; 86 pthread_cond_t condition; /**< The condition variable */
86}; 87};
87 88
88struct _Eina_RWLock 89struct _Eina_RWLock
89{ 90{
90 pthread_rwlock_t mutex; 91 pthread_rwlock_t mutex; /**< The mutex that handles the locking */
91#ifdef EINA_HAVE_DEBUG_THREADS 92#ifdef EINA_HAVE_DEBUG_THREADS
92 pthread_t lock_thread_wid; 93 pthread_t lock_thread_wid; /**< The ID of the thread that currently has the lock */
93#endif 94#endif
94}; 95};
96/** @} privatesection */
95 97
96EAPI extern Eina_Bool _eina_threads_activated; 98EAPI extern Eina_Bool _eina_threads_activated;
97 99
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 @@
25#include <windows.h> 25#include <windows.h>
26#undef WIN32_LEAN_AND_MEAN 26#undef WIN32_LEAN_AND_MEAN
27 27
28/** @privatesection @{ */
28typedef CRITICAL_SECTION Eina_Lock; 29typedef CRITICAL_SECTION Eina_Lock;
29typedef struct _Eina_Condition Eina_Condition; 30typedef struct _Eina_Condition Eina_Condition;
30typedef struct _Eina_RWLock Eina_RWLock; 31typedef struct _Eina_RWLock Eina_RWLock;
@@ -35,40 +36,40 @@ typedef Eina_Lock Eina_Spinlock;
35#if _WIN32_WINNT >= 0x0600 36#if _WIN32_WINNT >= 0x0600
36struct _Eina_Condition 37struct _Eina_Condition
37{ 38{
38 CRITICAL_SECTION *mutex; 39 CRITICAL_SECTION *mutex; /**< The locking mechanism for this condition variable */
39 CONDITION_VARIABLE condition; 40 CONDITION_VARIABLE condition; /**< The condition variable */
40}; 41};
41 42
42struct _Eina_RWLock 43struct _Eina_RWLock
43{ 44{
44 SRWLOCK mutex; 45 SRWLOCK mutex; /**< The locking mechanism */
45 46
46 Eina_Bool is_read_mode : 1; 47 Eina_Bool is_read_mode : 1; /**< Indicates if the lock is a read lock */
47}; 48};
48#else 49#else
49struct _Eina_Condition 50struct _Eina_Condition
50{ 51{
51 int waiters_count; 52 int waiters_count; /**< The count of threads that are waiting on this condition */
52 CRITICAL_SECTION waiters_count_lock; 53 CRITICAL_SECTION waiters_count_lock; /**< The locking mechanism for the waiters_count member */
53 CRITICAL_SECTION *mutex; 54 CRITICAL_SECTION *mutex; /**< The locking mechanism for the condition */
54 HANDLE semaphore; 55 HANDLE semaphore; /**< Semaphore used to coordinate waiters */
55 HANDLE waiters_done; 56 HANDLE waiters_done; /**< Event to trigger when all the waiters are done */
56 Eina_Bool was_broadcast; 57 Eina_Bool was_broadcast; /**< Indicates whether this condition has signalled its waiters */
57}; 58};
58 59
59struct _Eina_RWLock 60struct _Eina_RWLock
60{ 61{
61 LONG readers_count; 62 LONG readers_count; /**< The number of readers waiting for locks */
62 LONG writers_count; 63 LONG writers_count; /**< The number of writers waiting for locks */
63 int readers; 64 int readers; /**< The number of readers that have locks */
64 int writers; 65 int writers; /**< The number of writers that have locks */
65 66
66 Eina_Lock mutex; 67 Eina_Lock mutex; /**< The locking mechanism */
67 Eina_Condition cond_read; 68 Eina_Condition cond_read; /**< The condition for readers */
68 Eina_Condition cond_write; 69 Eina_Condition cond_write; /**< The condition for writers */
69}; 70};
70#endif 71#endif
71 72/** @} privatesection */
72 73
73EAPI extern Eina_Bool _eina_threads_activated; 74EAPI extern Eina_Bool _eina_threads_activated;
74EAPI extern Eina_Bool _eina_thread_tls_cb_register(Eina_TLS key, Eina_TLS_Delete_Cb cb); 75EAPI 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
30EAPI extern Eina_Bool _eina_thread_tls_cb_unregister(Eina_TLS key); 30EAPI extern Eina_Bool _eina_thread_tls_cb_unregister(Eina_TLS key);
31EAPI extern Eina_Bool _eina_thread_tls_key_add(Eina_TLS key); 31EAPI extern Eina_Bool _eina_thread_tls_key_add(Eina_TLS key);
32 32
33/** @privatesection @{ */
33typedef HANDLE Eina_Lock; 34typedef HANDLE Eina_Lock;
34typedef Eina_Lock Eina_Spinlock; 35typedef Eina_Lock Eina_Spinlock;
35typedef Eina_Lock Eina_RWLock; 36typedef Eina_Lock Eina_RWLock;
36typedef DWORD Eina_TLS; 37typedef DWORD Eina_TLS;
37typedef void * Eina_Semaphore; 38typedef void * Eina_Semaphore;
39/** @} privatesection */
38 40
39static inline Eina_Bool 41static inline Eina_Bool
40eina_lock_new(Eina_Lock *mutex) 42eina_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 @@
31 31
32/** 32/**
33 * @defgroup Eina_Lock_Group Lock 33 * @defgroup Eina_Lock_Group Lock
34 *
35 * The Eina lock libraries provide thread locking and sychronization capabilities
36 * similar to POISIX threads (pthreads), but it takes care of the platform specific
37 * details so you don't have to.
38 *
39 * If you know how @c pthreads work, this library will look familiar to you.
40 * If you are not familiar with @c pthreads, a good overview is available
41 * <a href="https://computing.llnl.gov/tutorials/pthreads/">here</a>
42 *
43 * The Eina lock functions are grouped into several categories to handle different
44 * thread locking and sychronization methods:
45 * @li eina_lock_* - Functions that implement locking.
46 * @li eina_condition_* - Functions that implement condition variables.
47 * @li eina_rwlock_* - Functions that implement read/write locks.
48 * @li eina_tls_* - Functions that implement thread level storage.
49 * @li eina_semaphore_* - Functions that implement semaphores.
50 * @li eina_barrier_* - Functions that implement barriers.
51 * @li eina_spinlock_* - Functions that implement spinlocks if they are available
52 * on the platform. If they are not available, these functuions degrade to plain locks.
53 *
54 *
34 * 55 *
35 * @{ 56 * @{
36 */ 57 */
37 58
59/**
60* @typedef Eina_Barrier
61* An opaque type for working with barrier locks.
62*
63*/
64/**
65* @typedef Eina_Lock
66* An opaque type for working with locks.
67*
68*/
69/**
70* @typedef Eina_Condition
71* An opaque type that represents a condition variable.
72*
73*/
74/**
75* @typedef Eina_RWLock
76* An opaque type for working with read/write locks.
77*
78*/
79/**
80* @typedef Eina_TLS
81* An opaque type for working with thread level storage.
82*
83*/
84/**
85* @typedef Eina_Semaphore
86* An opaque type for working with semaphores.
87*
88*/
89/**
90* @typedef Eina_Spinlock
91* An opaque type for working with spinlocks.
92*
93*/
94
95/**
96 * @typedef Eina_Lock_Result
97 * Return codes for lock operations.
98 */
38typedef enum 99typedef enum
39{ 100{
40 EINA_LOCK_FAIL = EINA_FALSE, 101 EINA_LOCK_FAIL = EINA_FALSE, /**< Indicates that the lock operation failed. */
41 EINA_LOCK_SUCCEED = EINA_TRUE, 102 EINA_LOCK_SUCCEED = EINA_TRUE, /**< Indicates that the lock operation succeeded. */
42 EINA_LOCK_DEADLOCK 103 EINA_LOCK_DEADLOCK /**< Indicates that the lock is deadlocked. */
43} Eina_Lock_Result; 104} Eina_Lock_Result;
44 105
106/** Type definition for deallocation callbacks for thread level sotrage data. A simple function pointer. */
45typedef void (*Eina_TLS_Delete_Cb)(void *ptr); 107typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
46 108
47#ifdef _WIN32_WCE 109#ifdef _WIN32_WCE
@@ -52,80 +114,495 @@ typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
52# include "eina_inline_lock_posix.x" 114# include "eina_inline_lock_posix.x"
53#endif 115#endif
54 116
117/** A type definition for warning that a function was called from somewhere other than the EFL main loop. */
55EAPI extern Eina_Error EINA_ERROR_NOT_MAIN_LOOP; 118EAPI extern Eina_Error EINA_ERROR_NOT_MAIN_LOOP;
56 119
57/** @relates static Eina_Bool eina_lock_new(_Eina_Lock *mutex) */ 120/**
121 * @brief Initializes a new Eina_Lock
122 *
123 * This function initializes an Eina_Lock with appropriate values.
124 * These values are platform dependent as is the structure of the Eina_Lock
125 * itself.
126 *
127 * @param mutex The Eina_Lock structure to be initialized.
128 *
129 * @return EINA_TRUE on success, else EINA_FALSE.
130 *
131 */
58static inline Eina_Bool eina_lock_new(Eina_Lock *mutex); 132static inline Eina_Bool eina_lock_new(Eina_Lock *mutex);
59/** @relates static void eina_lock_free(_Eina_Lock *mutex) */ 133
134/**
135 * @brief Deallocates an Eina_Lock
136 *
137 * This function deallocates an Eina_Lock and does any platform dependent
138 * cleanup that is required.
139 *
140 * @param mutex The Eina_Lock structure to be deallocated.
141 *
142 */
60static inline void eina_lock_free(Eina_Lock *mutex); 143static inline void eina_lock_free(Eina_Lock *mutex);
61/** @relates static Eina_Lock_Result eina_lock_take(_Eina_Lock *mutex) */ 144
145/**
146 * @brief Attempts to take a lock.
147 *
148 * This function attempts to gain a lock on the indicated Eina_Lock. If the
149 * underlying Eina_Lock is locked already, this call will block until
150 * the lock is released. This is appropriate in many cases, but consider using
151 * #eina_lock_take_try if you don't need to block.
152 *
153 * @param mutex The Eina_Lock to take.
154 *
155 * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails because
156 * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some other
157 * condition causes the take to fail, EINA_LOCK_FAIL is returned.
158 *
159 */
62static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex); 160static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
63/** @relates static Eina_Lock_Result eina_lock_take_try(_Eina_Lock *mutex) */ 161
162/**
163 * @brief Attempts to take a lock.
164 *
165 * This function attempts to gain a lock on the indicated Eina_Lock. Identical
166 * to #eina_lock_take, but returns immediately if the lock is already taken.
167 *
168 * @param mutex The Eina_Lock to take.
169 *
170 * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails because
171 * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some other
172 * condition causes the take to fail, EINA_LOCK_FAIL is returned.
173 *
174 */
64static inline Eina_Lock_Result eina_lock_take_try(Eina_Lock *mutex); 175static inline Eina_Lock_Result eina_lock_take_try(Eina_Lock *mutex);
65/** @relates static Eina_Lock_Result eina_lock_release(_Eina_Lock *mutex) */ 176
177/**
178 * @brief Releases a lock.
179 *
180 * This function will release the lock on the indicated Eina_Lock. If successful,
181 * and EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
182 * about the locking process is removed (e.g. thread number and backtrace for POSIX).
183 *
184 * @param mutex The Eina_Lock to release.
185 *
186 * @return Returns EINA_LOCK_SUCCEED on success. If it fails, EINA_LOCK_FAIL is
187 * returned.
188 *
189 */
66static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex); 190static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex);
67/** @relates static void eina_lock_debug(const _Eina_Lock *mutex) */ 191
192/**
193 * @brief Print debug information about a lock.
194 *
195 * This function will print debug information for @p mutex. The information is
196 * platform dependant. On POSIX systems it will print the address of @p mutex,
197 * lock state, thread number and a backtrace.
198 *
199 * @param mutex The Eina_Lock to print debug info for.
200 *
201 * @note If EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing.
202 * @note This function is implemented on Win32 or WinCE, but it will
203 * not produce any output, regardless of EINA_HAVE_DEBUG_THREADS being set.
204 */
68static inline void eina_lock_debug(const Eina_Lock *mutex); 205static inline void eina_lock_debug(const Eina_Lock *mutex);
69 206
70/** @relates static Eina_Bool eina_condition_new(_Eina_Condition *cond, _Eina_Lock *mutex) */ 207/**
208 * @brief Initializes a new condition variable
209 *
210 * This function initializes an Eina_Condition structure and associates it with
211 * an existing lock.
212 *
213 * Condition variables are used to coordinate actions between threads. See
214 * <a href="https://computing.llnl.gov/tutorials/pthreads/#ConVarOverview"> Condition Varable Overview </a>
215 * for an introduction to condition variables and their use.
216 *
217 * @param cond The condition variable to create.
218 * @param mutex The _Eina_Lock structure that controls access to this condition variable.
219 *
220 * @return EINA_TRUE on success, else EINA_FALSE.
221 *
222 */
71static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock *mutex); 223static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock *mutex);
72/** @relates static void eina_condition_free(_Eina_Condition *cond) */ 224
225/**
226 * @brief Deallocates a condition variable
227 *
228 * This function deallocates a condition variable and does any platform dependent
229 * cleanup that is required.
230 *
231 * @param cond The condition variable to be deallocated.
232 *
233 */
73static inline void eina_condition_free(Eina_Condition *cond); 234static inline void eina_condition_free(Eina_Condition *cond);
74/** @relates static Eina_Bool eina_condition_wait(_Eina_Condition *cond) */ 235
236/**
237 * @brief Causes a thread to wait until signaled by the condition.
238 *
239 * This function makes a thread block until a signal is sent to it via @p cond.
240 *
241 * @param cond The Eina_Condition upon which the thread will wait.
242 *
243 * @return EINA_TRUE on success, else EINA_FALSE.
244 */
75static inline Eina_Bool eina_condition_wait(Eina_Condition *cond); 245static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
76/** @relates static Eina_Bool eina_condition_timedwait(_Eina_Condition *cond, double t) */ 246
247/**
248 * @brief Causes a thread to wait until signaled by the condition or a
249 * timeout is reached.
250 *
251 * This function makes a thread block until either a signal is sent to it via
252 * @p cond or @p t seconds have passed.
253 *
254 * @param cond The Eina_Condition upon which the thread will wait.
255 * @param t The maximum amount of time to wait, in seconds.
256 *
257 * @return EINA_TRUE on success, else EINA_FALSE.
258 *
259 */
77static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double t); 260static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double t);
78/** @relates static Eina_Bool eina_condition_broadcast(_Eina_Condition *cond) */ 261
262/**
263 * @brief Signal all threads waiting for a condition.
264 *
265 * This function sends a signal to all the threads waiting on the condition @p cond.
266 * If you know for sure that there is only one thread waiting, use eina_condition_signal
267 * instead to gain a little optimization.
268 *
269 * @param cond The Eina_Condition that will signal all its waiting threads.
270 *
271 * @return EINA_TRUE on success, else EINA_FALSE.
272 *
273 */
79static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond); 274static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond);
80/** @relates static Eina_Bool eina_condition_signal(_Eina_Condition *cond) */ 275
276/**
277 * @brief Signal a thread waiting for a condition.
278 *
279 * This function sends a signal to a thread waiting on the condition @p cond.
280 * If you do not know for sure that there is only one thread waiting, use
281 * eina_condition_broadcast instead.
282 *
283 * If there is more than one thread waiting on this condition, one of them will
284 * be signalled, but which one is undefined.
285 *
286 * @param cond The Eina_Condition that will signal its waiting thread.
287 *
288 * @return EINA_TRUE on success, else EINA_FALSE.
289 *
290 */
81static inline Eina_Bool eina_condition_signal(Eina_Condition *cond); 291static inline Eina_Bool eina_condition_signal(Eina_Condition *cond);
82 292
83/** @relates static Eina_Bool eina_rwlock_new(_Eina_RWLock *mutex) */ 293
294/**
295 * @brief Initializes a new Eina_RWLock
296 *
297 * This function initializes an Eina_RWLock with appropriate values.
298 * These values are platform dependent as is the structure of the Eina_RWLock
299 * itself.
300 *
301 * @param mutex The Eina_RWLock to be initialized.
302 *
303 * @return EINA_TRUE on success, else EINA_FALSE.
304 *
305 */
84static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex); 306static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex);
85/** @relates static void eina_rwlock_free(_Eina_RWLock *mutex) */ 307
308/**
309 * @brief Deallocates an Eina_RWLock
310 *
311 * This function deallocates an Eina_RWLock and does any platform dependent
312 * cleanup that is required.
313 *
314 * @param mutex The Eina_RWLock structure to be deallocated.
315 *
316 */
86static inline void eina_rwlock_free(Eina_RWLock *mutex); 317static inline void eina_rwlock_free(Eina_RWLock *mutex);
87/** @relates static Eina_Lock_Result eina_rwlock_take_read(_Eina_RWLock *mutex) */ 318
319/**
320 * @brief Attempts to take a read lock.
321 *
322 * This function attempts to gain a read lock on the indicated Eina_RWLock. If
323 * the Eina_RWLock is write locked, this call will block until
324 * the lock is released.
325 *
326 * @param mutex The Eina_RWLock to take.
327 *
328 * @return Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
329 * @note This function will never return EINA_LOCK_DEADLOCK.
330 *
331 */
88static inline Eina_Lock_Result eina_rwlock_take_read(Eina_RWLock *mutex); 332static inline Eina_Lock_Result eina_rwlock_take_read(Eina_RWLock *mutex);
89/** @relates static Eina_Lock_Result eina_rwlock_take_write(_Eina_RWLock *mutex) */ 333
334/**
335 * @brief Attempts to take a write lock.
336 *
337 * This function attempts to gain a write lock on the indicated Eina_RWLock. If
338 * the Eina_RWLock is locked for reading or writing, this call
339 * will block until the lock is released.
340 *
341 * @param mutex The Eina_RWLock to take.
342 *
343 * @return Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
344 * @note This function will never return EINA_LOCK_DEADLOCK.
345 *
346 */
90static inline Eina_Lock_Result eina_rwlock_take_write(Eina_RWLock *mutex); 347static inline Eina_Lock_Result eina_rwlock_take_write(Eina_RWLock *mutex);
91/** @relates static Eina_Lock_Result eina_rwlock_release(_Eina_RWLock *mutex) */ 348
349/**
350 * @brief Releases a lock.
351 *
352 * This function will release the lock on the indicated Eina_RWLock.
353 *
354 * @param mutex The Eina_RWLock to release.
355 *
356 * @return Returns EINA_LOCK_SUCCEED on success. If it fails, EINA_LOCK_FAIL is
357 * returned.
358 *
359 */
92static inline Eina_Lock_Result eina_rwlock_release(Eina_RWLock *mutex); 360static inline Eina_Lock_Result eina_rwlock_release(Eina_RWLock *mutex);
93 361
94/** @relates static Eina_Bool eina_tls_new(pthread_key_t *key) */ 362/**
363 * @brief Initializes a new Eina_TLS, or thread level storage, to store thread
364 * specific data.
365 *
366 * This function initializes an Eina_TLS with @p key but does not set a
367 * callback to deallocate @p key when the thread exits. The implementation
368 * is platform dependent as is the structure of the Eina_TLS itself.
369 *
370 * @param key The Eina_TLS to be initialized.
371 *
372 * @return EINA_TRUE on success, else EINA_FALSE.
373 *
374 */
95static inline Eina_Bool eina_tls_new(Eina_TLS *key); 375static inline Eina_Bool eina_tls_new(Eina_TLS *key);
96/** @relates static Eina_Bool eina_tls_cb_new(pthread_key_t *key, Eina_TLS_Delete_Cb delete_cb) */ 376
377/**
378 * @brief Initializes a new Eina_TLS, or thread level storage, to store thread
379 * specific data.
380 *
381 * This function initializes an Eina_TLS with @p key and sets a
382 * callback to deallocate @p key when the thread exits. The implementation
383 * is platform dependent as is the structure of the Eina_TLS itself.
384 *
385 * @param key The Eina_TLS to be initialized.
386 * @param delete_cb A pointer to a function that will deallocate @p key.
387 *
388 * @return EINA_TRUE on success, else EINA_FALSE.
389 *
390 */
97static inline Eina_Bool eina_tls_cb_new(Eina_TLS *key, Eina_TLS_Delete_Cb delete_cb); 391static inline Eina_Bool eina_tls_cb_new(Eina_TLS *key, Eina_TLS_Delete_Cb delete_cb);
98/** @relates static void eina_tls_free(pthread_key_t key) */ 392
393/**
394 * @brief Frees an allocated Eina_TLS.
395 *
396 * This function frees the Eina_TLS @p key. The implementation
397 * is platform dependent.
398 *
399 * @param key The Eina_TLS to be freed.
400 *
401 */
99static inline void eina_tls_free(Eina_TLS key); 402static inline void eina_tls_free(Eina_TLS key);
100/** @relates static void eina_tls_get(pthread_key_t key) */ 403
404/**
405 * @brief Gets the value in Eina_TLS for this thread.
406 *
407 * This function gets a pointer to the data associated with Eina_TLS @p key for
408 * this thread. The implementation is platform dependent.
409 *
410 * @param key The Eina_TLS to be retrieved.
411 *
412 * @return A pointer to the data associated with @p key.
413 *
414 */
101static inline void *eina_tls_get(Eina_TLS key); 415static inline void *eina_tls_get(Eina_TLS key);
102/** @relates static Eina_Bool eina_tls_set(pthread_key_t key, const void *data) */ 416
417/**
418 * @brief Sets the value in Eina_TLS for this thread.
419 *
420 * This function sets the value associated with @p key to the pointer to the data
421 * @p data. The implementation is platform dependent.
422 *
423 * @param key The Eina_TLS to be set.
424 * @param data A pointer to the data to be stored.
425 *
426 * @return EINA_TRUE on success, else EINA_FALSE.
427 *
428 */
103static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data); 429static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data);
104/** @relates static Eina_Bool eina_semaphore_new(sem_t *sem, int count_init) */ 430
431
432/**
433 * @brief Initializes a new Eina_Semaphore
434 *
435 * This function initializes an unnamed Eina_Semaphore with appropriate values.
436 * These values are platform dependent.
437 *
438 *
439 * Be aware that the behavior of the parameter @p count_init differs by
440 * platform.
441 *
442 * @li POSIX: Indicates whether this semaphore can be shared by between processes. Greater than 0 == shared.
443 * @li Win32: Indicates the initial count of threads waiting on this semaphore.
444 *
445 * @note Semaphores are not avialable on the WinCE platform.
446 *
447 * @param sem The Eina_Semaphore to be initialized.
448 * @param count_init Behavior is platofrm specific. See above.
449 *
450 * @return EINA_TRUE on success, else EINA_FALSE.
451 *
452 */
105static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int count_init); 453static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int count_init);
106/** @relates static Eina_Bool eina_semaphore_free(sem_t *sem) */ 454
455/**
456 * @brief Frees an allocated Eina_Semaphore.
457 *
458 * This function frees the Eina_Semaphore @p sem. The implementation
459 * is platform dependent.
460 *
461 * @param sem The Eina_Semaphore to be freed.
462 *
463 * @return EINA_TRUE on success, else EINA_FALSE.
464 *
465 */
107static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem); 466static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem);
108/** @relates static Eina_Bool eina_semaphore_lock(sem_t *sem) */ 467
468/**
469 * @brief Gets a lock on an Eina_Semaphore.
470 *
471 * This function locks the Eina_Semaphore @p sem. The implementation
472 * is platform dependent.
473 *
474 * @param sem The Eina_Semaphore to lock.
475 *
476 * @return EINA_TRUE on success, else EINA_FALSE.
477 *
478 */
109static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem); 479static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem);
110/** @relates static Eina_Bool eina_semaphore_release(sem_t *sem, int count_release) */ 480
481/**
482 * @brief Releases a lock on an Eina_Semaphore.
483 *
484 * This function releases a lock on the Eina_Semaphore @p sem. The implementation
485 * is platform dependent.
486 *
487 * @param sem The Eina_Semaphore to release.
488 * @param count_release Not used.
489 *
490 * @return EINA_TRUE on success, else EINA_FALSE.
491 *
492 */
111static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int count_release); 493static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int count_release);
112 494
113/** @relates static Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed) @since 1.8 */ 495
496/**
497 * @brief Initializes a new Eina_Barrier
498 *
499 * This function initializes a new Eina_Barrier. It will set the @c needed flag
500 * to the value of @p needed, set the barrier's @c count member to 0 and will
501 * create new Eina_Lock and Eina_Condition objects for the barrier.
502 *
503 * @param barrier The Eina_Barrier to be initialized.
504 * @param needed The number of thread waits that will cause this barrier to be reset.
505 *
506 * @return EINA_TRUE on success, else EINA_FALSE.
507 *
508 */
114static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed); 509static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed);
115/** @relates static void eina_barrier_free(Eina_Barrier *barrier); @since 1.8 */ 510
511/**
512 * @brief Frees an allocated Eina_Barrier.
513 *
514 * This function frees the Eina_Barrier @p barrier.
515 *
516 * @param barrier The Eina_Barrier to be freed.
517 *
518 */
116static inline void eina_barrier_free(Eina_Barrier *barrier); 519static inline void eina_barrier_free(Eina_Barrier *barrier);
117/** @relates static Eina_Bool eina_barrier_wait(Eina_Barrier *barrier); @since 1.8 */ 520
521/**
522 * @brief Increments the count of threads that are waiting on @p barrier.
523 *
524 * When the count of threads reaches the @c needed value for the barrier, all
525 * waiting threads will be notified via eina_condition_broadcast.
526 *
527 * @param barrier The Eina_Barrier to be incremented.
528 *
529 * @return EINA_TRUE on success, else EINA_FALSE.
530 *
531 */
118static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier); 532static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier);
119 533
120/** @relates static Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock); @since 1.8 */ 534
535/**
536 * @brief Initializes a new Eina_Spinlock
537 *
538 * This function initializes a new Eina_Spinlock, if spinlocks are available. If
539 * spinlocks are not avialable, it will create a new Eina_Lock.
540 *
541 *@note Spinlocks are only implemented on the POSIX platform and are only available
542 *if EINA_HAVE_POSIX_SPINLOCK is defined. All other platforms will get a new Eina_Lock.
543 *
544 * @param spinlock The Eina_Spinlock to be initialized.
545 *
546 * @return EINA_TRUE on success, else EINA_FALSE.
547 *
548 */
121static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock); 549static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
122/** @relates static Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock); @since 1.8 */ 550
551/**
552 * @brief Attempts to take a spinlock.
553 *
554 * This function attempts to gain a lock on the indicated Eina_Spinlock. If the
555 * underlying Eina_Spinlock is locked already, this call will block until
556 * the lock is released. This is appropriate in many cases, but consider using
557 * #eina_spinlock_take_try if you don't need to block.
558 *
559 * @param spinlock The Eina_Spinlock to take.
560 *
561 * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails because
562 * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some other
563 * condition causes the take to fail, EINA_LOCK_FAIL is returned.
564 *
565 */
123static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock); 566static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
124/** @relates static Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock); @since 1.8 */ 567
568/**
569 * @brief Attempts to take a spinlock.
570 *
571 * This function attempts to gain a lock on the indicated Eina_Spinlock. Identical
572 * to #eina_lock_take, but returns immediately if the lock is already taken.
573 *
574 * @param spinlock The Eina_Spinlock to take.
575 *
576 * @return Returns EINA_LOCK_SUCCEED on success. If the operation fails because
577 * a deadlock condition exists, it will return EINA_LOCK_DEADLOCK. If some other
578 * condition causes the take to fail, EINA_LOCK_FAIL is returned.
579 *
580 */
125static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock); 581static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
126/** @relates static Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock); @since 1.8 */ 582
583/**
584 * @brief Releases a spinlock.
585 *
586 * This function will release the lock on the indicated Eina_Spinlock. If successful,
587 * and EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
588 * about the locking process is removed (e.g. thread number and backtrace for POSIX).
589 *
590 * @param spinlock The Eina_Spinlock to release.
591 *
592 * @return Returns EINA_LOCK_SUCCEED on success, else EINA_LOCK_FAIL.
593 *
594 */
127static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock); 595static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock);
128/** @relates static void eina_spinlock_free(Eina_Spinlock *spinlock); @since 1.8 */ 596
597/**
598 * @brief Deallocates an Eina_Spinlock
599 *
600 * This function deallocates an Eina_Spinlock and does any platform dependent
601 * cleanup that is required.
602 *
603 * @param spinlock The Eina_Spinlock to be deallocated.
604 *
605 */
129static inline void eina_spinlock_free(Eina_Spinlock *spinlock); 606static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
130 607
131#ifdef EINA_HAVE_DEBUG_THREADS 608#ifdef EINA_HAVE_DEBUG_THREADS