Tizen Native API  3.0

This group provides thread locking and synchronization 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 pthreads work, this library will look familiar to you. If you are not familiar with pthreads, a good overview is available here

The Eina lock functions are grouped into several categories to handle different thread locking and synchronization methods:

  • eina_lock_* - Functions that implement locking.
  • eina_condition_* - Functions that implement condition variables.
  • eina_rwlock_* - Functions that implement read/write locks.
  • eina_tls_* - Functions that implement thread level storage.
  • eina_semaphore_* - Functions that implement semaphores.
  • eina_barrier_* - Functions that implement barriers.
  • eina_spinlock_* - Functions that implement spinlocks if they are available on the platform. If they are not available, these functions degrade to plain locks.

Functions

static Eina_Bool eina_lock_new (Eina_Lock *mutex)
 Initializes a new #Eina_Lock.
static void eina_lock_free (Eina_Lock *mutex)
 Deallocates an #Eina_Lock.
static Eina_Lock_Result eina_lock_take (Eina_Lock *mutex)
 Attempts to take a lock.
static Eina_Lock_Result eina_lock_take_try (Eina_Lock *mutex)
 Attempts to take a lock if possible.
static Eina_Lock_Result eina_lock_release (Eina_Lock *mutex)
 Releases a lock.
static void eina_lock_debug (const Eina_Lock *mutex)
 Prints debug information about a lock.
static Eina_Bool eina_condition_new (Eina_Condition *cond, Eina_Lock *mutex)
 Initializes a new condition variable.
static void eina_condition_free (Eina_Condition *cond)
 Deallocates a condition variable.
static Eina_Bool eina_condition_wait (Eina_Condition *cond)
 Causes a thread to wait until signaled by the condition.
static Eina_Bool eina_condition_timedwait (Eina_Condition *cond, double t)
 Causes a thread to wait until signalled by the condition or a timeout is reached.
static Eina_Bool eina_condition_broadcast (Eina_Condition *cond)
 Signals all threads waiting for a condition.
static Eina_Bool eina_condition_signal (Eina_Condition *cond)
 Signals a thread waiting for a condition.
static Eina_Bool eina_rwlock_new (Eina_RWLock *mutex)
 Initializes a new #Eina_RWLock.
static void eina_rwlock_free (Eina_RWLock *mutex)
 Deallocates an #Eina_RWLock.
static Eina_Lock_Result eina_rwlock_take_read (Eina_RWLock *mutex)
 Attempts to take a read lock.
static Eina_Lock_Result eina_rwlock_take_write (Eina_RWLock *mutex)
 Attempts to take a write lock.
static Eina_Lock_Result eina_rwlock_release (Eina_RWLock *mutex)
 Releases a lock.
static Eina_Bool eina_tls_new (Eina_TLS *key)
 Initializes a new #Eina_TLS, or thread level storage, to store thread specific data.
static Eina_Bool eina_tls_cb_new (Eina_TLS *key, Eina_TLS_Delete_Cb delete_cb)
 Initializes a new #Eina_TLS, or thread level storage, to store thread specific data.
static void eina_tls_free (Eina_TLS key)
 Frees an allocated #Eina_TLS.
static void * eina_tls_get (Eina_TLS key)
 Gets the value in #Eina_TLS for this thread.
static Eina_Bool eina_tls_set (Eina_TLS key, const void *data)
 Sets the value in Eina_TLS for this thread.
static Eina_Bool eina_semaphore_new (Eina_Semaphore *sem, int count_init)
 Initializes a new #Eina_Semaphore.
static Eina_Bool eina_semaphore_free (Eina_Semaphore *sem)
 Frees an allocated #Eina_Semaphore.
static Eina_Bool eina_semaphore_lock (Eina_Semaphore *sem)
 Gets a lock on an #Eina_Semaphore.
static Eina_Bool eina_semaphore_release (Eina_Semaphore *sem, int count_release)
 Releases a lock on an #Eina_Semaphore.
static Eina_Bool eina_barrier_new (Eina_Barrier *barrier, int needed)
 Initializes a new #Eina_Barrier.
static void eina_barrier_free (Eina_Barrier *barrier)
 Frees an allocated #Eina_Barrier.
static Eina_Bool eina_barrier_wait (Eina_Barrier *barrier)
 Increments the count of threads that are waiting on barrier.
static Eina_Bool eina_spinlock_new (Eina_Spinlock *spinlock)
 Initializes a new #Eina_Spinlock.
static Eina_Lock_Result eina_spinlock_take (Eina_Spinlock *spinlock)
 Attempts to take a spinlock.
static Eina_Lock_Result eina_spinlock_take_try (Eina_Spinlock *spinlock)
 Attempts to take a spinlock if possible.
static Eina_Lock_Result eina_spinlock_release (Eina_Spinlock *spinlock)
 Releases a spinlock.
static void eina_spinlock_free (Eina_Spinlock *spinlock)
 Deallocates an #Eina_Spinlock.

Typedefs

typedef void(* Eina_TLS_Delete_Cb )(void *ptr)
 A callback type for deallocation of thread level storage data.

Defines

#define EINA_MAIN_LOOP_CHECK_RETURN_VAL(val)
 Definition for the macro that doesn't do anything unless EINA_HAVE_DEBUG_THREADS is defined.
#define EINA_MAIN_LOOP_CHECK_RETURN
 Definition for the macro that doesn't do anything unless EINA_HAVE_DEBUG_THREADS is defined.

Define Documentation

Definition for the macro that doesn't do anything unless EINA_HAVE_DEBUG_THREADS is defined.

Parameters:
[in]valThe value to be returned

Enumeration Type Documentation

Return codes for lock operations.

Enumerator:
EINA_LOCK_FAIL 

Indicates that the lock operation failed.

EINA_LOCK_SUCCEED 

Indicates that the lock operation succeeded.

EINA_LOCK_DEADLOCK 

Indicates that the lock is deadlocked.


Function Documentation

static void eina_barrier_free ( Eina_Barrier *  barrier) [static]

Frees an allocated #Eina_Barrier.

This function frees the #Eina_Barrier barrier.

Parameters:
[in]barrierThe #Eina_Barrier to be freed.
See also:
eina_barrier_new()
static Eina_Bool eina_barrier_new ( Eina_Barrier *  barrier,
int  needed 
) [static]

Initializes a new #Eina_Barrier.

This function initializes a new #Eina_Barrier. It sets the needed flag to the value of needed, sets the barrier's count member to 0 and creates new #Eina_Lock and #Eina_Condition objects for the barrier.

Parameters:
[in]barrierThe #Eina_Barrier to be initialized.
[in]neededThe number of thread waits that causes this barrier to be reset.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_barrier_free()
static Eina_Bool eina_barrier_wait ( Eina_Barrier *  barrier) [static]

Increments the count of threads that are waiting on barrier.

When the count of threads reaches the needed value for the barrier, all waiting threads are notified via eina_condition_broadcast().

Parameters:
[in]barrierThe #Eina_Barrier to be incremented.
Returns:
EINA_TRUE on success, else EINA_FALSE otherwise.
static Eina_Bool eina_condition_broadcast ( Eina_Condition *  cond) [static]

Signals all threads waiting for a condition.

This function sends a signal to all the threads waiting on the condition cond. If you know for sure that there is only one thread waiting, use eina_condition_signal() instead to gain a little optimization.

Parameters:
[in]condThe #Eina_Condition that signals all its waiting threads.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_condition_signal()
static void eina_condition_free ( Eina_Condition *  cond) [static]

Deallocates a condition variable.

This function deallocates a condition variable and does any platform dependent cleanup that is required.

Parameters:
[in]condThe condition variable to be deallocated.
See also:
eina_condition_new()
Examples:
ecore_thread_example.c.
static Eina_Bool eina_condition_new ( Eina_Condition *  cond,
Eina_Lock *  mutex 
) [static]

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.

Parameters:
[in]condThe condition variable to create
[in]mutexThe #Eina_Lock structure that controls access to this condition variable
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_condition_free()
Examples:
ecore_thread_example.c.
static Eina_Bool eina_condition_signal ( Eina_Condition *  cond) [static]

Signals a thread waiting for a condition.

This function sends a signal to a thread waiting on the condition cond. If you do not know for sure that there is only one thread waiting, use eina_condition_broadcast() instead.

Parameters:
[in]condThe #Eina_Condition that signals its waiting thread.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
Note:
If there is more than one thread waiting on this condition, one of them is signalled, but which one is undefined.
See also:
eina_condition_broadcast()
Examples:
ecore_thread_example.c.
static Eina_Bool eina_condition_timedwait ( Eina_Condition *  cond,
double  t 
) [static]

Causes a thread to wait until signalled by the condition or a timeout is reached.

This function makes a thread block until either a signal is sent to it via cond or t seconds have passed.

Parameters:
[in]condThe #Eina_Condition upon which the thread waits.
[in]tThe maximum amount of time to wait, in seconds.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_condition_wait()
static Eina_Bool eina_condition_wait ( Eina_Condition *  cond) [static]

Causes a thread to wait until signaled by the condition.

This function makes a thread block until a signal is sent to it via cond.

Parameters:
[in]condThe #Eina_Condition upon which the thread waits.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_condition_timedwait()
Examples:
ecore_thread_example.c.
static void eina_lock_debug ( const Eina_Lock *  mutex) [static]

Prints debug information about a lock.

This function prints debug information for mutex. The information is platform dependant. On POSIX systems it prints the address of mutex, lock state, thread number and a backtrace.

Parameters:
[in]mutexThe #Eina_Lock to print debug info for.
Note:
If EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing.
This function is implemented on Win32 or WinCE, but it does not not produce any output, regardless of EINA_HAVE_DEBUG_THREADS being set.
static void eina_lock_free ( Eina_Lock *  mutex) [static]

Deallocates an #Eina_Lock.

This function deallocates an #Eina_Lock allocated by eina_lock_new() and does any platform dependent cleanup that is required.

Parameters:
[in]mutexThe #Eina_Lock structure to be deallocated
See also:
eina_lock_new()
Examples:
ecore_thread_example.c.
static Eina_Bool eina_lock_new ( Eina_Lock *  mutex) [static]

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.

Parameters:
[in]mutexThe #Eina_Lock structure to be initialized
Returns:
EINA_TRUE on success, EINA_FALSE otherwise
See also:
eina_lock_free()
Examples:
ecore_thread_example.c.
static Eina_Lock_Result eina_lock_release ( Eina_Lock *  mutex) [static]

Releases a lock.

This function releases the lock on the indicated #Eina_Lock. If successful, and EINA_HAVE_DEBUG_THREADS is defined, mutex is updated and information about the locking process is removed (e.g. thread number and backtrace for POSIX).

Parameters:
[in]mutexThe #Eina_Lock to release
Returns:
Returns EINA_LOCK_SUCCEED on success, If it fails, EINA_LOCK_FAIL is returned.
See also:
eina_lock_take()
eina_lock_take_try()
Examples:
ecore_thread_example.c.
static Eina_Lock_Result eina_lock_take ( Eina_Lock *  mutex) [static]

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 can be blocked 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.

Parameters:
[in]mutexThe #Eina_Lock to take
Returns:
Returns EINA_LOCK_SUCCEED on success. If the operation fails because a deadlock condition exists, it returns EINA_LOCK_DEADLOCK. If some other condition causes the take to fail, EINA_LOCK_FAIL is returned.
See also:
eina_lock_take_try()
eina_lock_release()
Examples:
ecore_thread_example.c.
static Eina_Lock_Result eina_lock_take_try ( Eina_Lock *  mutex) [static]

Attempts to take a lock if possible.

This function attempts to gain a lock on the indicated #Eina_Lock. Identical eina_lock_take(), but returns immediately if the lock is already taken.

Parameters:
[in]mutexThe #Eina_Lock to take
Returns:
Returns EINA_LOCK_SUCCEED on success. If the operation fails because a deadlock condition exists, it returns EINA_LOCK_DEADLOCK. If some other condition causes the take to fail, EINA_LOCK_FAIL is returned.
See also:
eina_lock_take()
eina_lock_release()
Examples:
ecore_thread_example.c.
static void eina_rwlock_free ( Eina_RWLock *  mutex) [static]

Deallocates an #Eina_RWLock.

This function deallocates an #Eina_RWLock and does any platform dependent cleanup that is required.

Parameters:
[in]mutexThe #Eina_RWLock structure to be deallocated.
See also:
eina_rwlock_new()
static Eina_Bool eina_rwlock_new ( Eina_RWLock *  mutex) [static]

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.

Parameters:
[in]mutexThe #Eina_RWLock to be initialized.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_rwlock_free()
static Eina_Lock_Result eina_rwlock_release ( Eina_RWLock *  mutex) [static]

Releases a lock.

This function releases the lock on the indicated #Eina_RWLock.

Parameters:
[in]mutexThe #Eina_RWLock to release.
Returns:
Returns EINA_LOCK_SUCCEED on success. If it fails, EINA_LOCK_FAIL is returned.
See also:
eina_rwlock_take_read()
eina_rwlock_take_write()
static Eina_Lock_Result eina_rwlock_take_read ( Eina_RWLock *  mutex) [static]

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 can be blocked until the lock is released.

Parameters:
[in]mutexThe #Eina_RWLock to take.
Returns:
Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
Note:
This function never return EINA_LOCK_DEADLOCK.
See also:
eina_rwlock_release()
static Eina_Lock_Result eina_rwlock_take_write ( Eina_RWLock *  mutex) [static]

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 can be blocked until the lock is released.

Parameters:
[in]mutexThe #Eina_RWLock to take.
Returns:
Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL on failure.
Note:
This function never return EINA_LOCK_DEADLOCK.
See also:
eina_rwlock_release()
static Eina_Bool eina_semaphore_free ( Eina_Semaphore *  sem) [static]

Frees an allocated #Eina_Semaphore.

This function frees the #Eina_Semaphore sem. The implementation is platform dependent.

Parameters:
[in]semThe #Eina_Semaphore to be freed.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_semaphore_new()
static Eina_Bool eina_semaphore_lock ( Eina_Semaphore *  sem) [static]

Gets a lock on an #Eina_Semaphore.

This function locks the #Eina_Semaphore sem. The implementation is platform dependent.

Parameters:
[in]semThe #Eina_Semaphore to lock.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_semaphore_release()
static Eina_Bool eina_semaphore_new ( Eina_Semaphore *  sem,
int  count_init 
) [static]

Initializes a new #Eina_Semaphore.

This function initializes an unnamed #Eina_Semaphore with appropriate values. These values are platform dependent.

Parameters:
[in]semThe #Eina_Semaphore to be initialized.
[in]count_initIndicates the initial count of threads waiting on this semaphore.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
Note:
Semaphores are not avialable on the WinCE platform.
See also:
eina_semaphore_free()
static Eina_Bool eina_semaphore_release ( Eina_Semaphore *  sem,
int  count_release 
) [static]

Releases a lock on an #Eina_Semaphore.

This function releases a lock on the #Eina_Semaphore sem. The implementation is platform dependent.

Parameters:
[in]semThe #Eina_Semaphore to release.
[in]count_releaseNot used.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_semaphore_lock()
static void eina_spinlock_free ( Eina_Spinlock *  spinlock) [static]

Deallocates an #Eina_Spinlock.

This function deallocates an #Eina_Spinlock and does any platform dependent cleanup that is required.

Parameters:
[in]spinlockThe #Eina_Spinlock to be deallocated.
static Eina_Bool eina_spinlock_new ( Eina_Spinlock *  spinlock) [static]

Initializes a new #Eina_Spinlock.

This function initializes a new #Eina_Spinlock, if spinlocks are available. If spinlocks are not available, it creates a new #Eina_Lock.

Parameters:
[in]spinlockThe #Eina_Spinlock to be initialized.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
Note:
Spinlocks are only implemented on the POSIX platform and are only available if #EINA_HAVE_POSIX_SPINLOCK is defined. you get a new #Eina_Lock on All other platforms.
See also:
eina_spinlock_free()
static Eina_Lock_Result eina_spinlock_release ( Eina_Spinlock *  spinlock) [static]

Releases a spinlock.

This function will release the lock on the indicated #Eina_Spinlock. If successful, and EINA_HAVE_DEBUG_THREADS is defined, mutex is updated and information about the locking process is removed (e.g. thread number and backtrace for POSIX).

Parameters:
[in]spinlockThe #Eina_Spinlock to release.
Returns:
Returns EINA_LOCK_SUCCEED on success, EINA_LOCK_FAIL otherwise.
See also:
eina_spinlock_take()
eina_spinlock_take_try()
static Eina_Lock_Result eina_spinlock_take ( Eina_Spinlock *  spinlock) [static]

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 can be blocked 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.

Parameters:
[in]spinlockThe #Eina_Spinlock to take.
Returns:
Returns EINA_LOCK_SUCCEED on success. If the operation fails because a deadlock condition exists, it returns EINA_LOCK_DEADLOCK. If some other condition causes the take to fail, EINA_LOCK_FAIL is returned.
See also:
eina_spinlock_take_try()
eina_spinlock_release()
static Eina_Lock_Result eina_spinlock_take_try ( Eina_Spinlock *  spinlock) [static]

Attempts to take a spinlock if possible.

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.

Parameters:
[in]spinlockThe #Eina_Spinlock to take.
Returns:
Returns EINA_LOCK_SUCCEED on success. If the operation fails because a deadlock condition exists, it returns EINA_LOCK_DEADLOCK. If some other condition causes the take to fail, EINA_LOCK_FAIL is returned.
See also:
eina_spinlock_take_try()
eina_spinlock_release()
static Eina_Bool eina_tls_cb_new ( Eina_TLS *  key,
Eina_TLS_Delete_Cb  delete_cb 
) [static]

Initializes a new #Eina_TLS, or thread level storage, to store thread specific data.

This function initializes an #Eina_TLS with key and sets a callback to deallocate key when the thread exits. The implementation is platform dependent as is the structure of the #Eina_TLS itself.

Parameters:
[in]keyThe #Eina_TLS to be initialized.
[in]delete_cbA pointer to a function that deallocates key.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_tls_new()
eina_tls_free()
static void eina_tls_free ( Eina_TLS  key) [static]

Frees an allocated #Eina_TLS.

This function frees the #Eina_TLS key. The implementation is platform dependent.

Parameters:
[in]keyThe #Eina_TLS to be freed.
See also:
eina_tls_new()
eina_tls_cb_new()
static void* eina_tls_get ( Eina_TLS  key) [static]

Gets the value in #Eina_TLS for this thread.

This function gets a pointer to the data associated with #Eina_TLS key for this thread. The implementation is platform dependent.

Parameters:
[in]keyThe #Eina_TLS to be retrieved.
Returns:
A pointer to the data associated with key.
See also:
eina_tls_set()
static Eina_Bool eina_tls_new ( Eina_TLS *  key) [static]

Initializes a new #Eina_TLS, or thread level storage, to store thread specific data.

This function initializes an #Eina_TLS with key but does not set a callback to deallocate key when the thread exits. The implementation is platform dependent as is the structure of the #Eina_TLS itself.

Parameters:
[in]keyThe #Eina_TLS to be initialized.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
Note:
use eina_tls_cb_new() instead to set a callback for deallocating key.
See also:
eina_tls_cb_new()
eina_tls_free()
static Eina_Bool eina_tls_set ( Eina_TLS  key,
const void *  data 
) [static]

Sets the value in Eina_TLS for this thread.

This function sets the value associated with key to the pointer to the data data. The implementation is platform dependent.

Parameters:
[in]keyThe #Eina_TLS to be set.
[in]dataA pointer to the data to be stored.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.
See also:
eina_tls_get()

Variable Documentation

A type definition for warning that a function was called from somewhere other than the EFL main loop.

Since :
2.3