Tizen Native API  5.5

Abstracts platform threads, providing a uniform API. It's modeled after POSIX THREADS (pthreads), on Linux they are almost 1:1 mapping.

See also:
Eina_Lock_Group for mutex/locking abstraction.
Since (EFL) :
1.8

Functions

Eina_Thread eina_thread_self (void)
 Returns identifier of the current thread.
Eina_Bool eina_thread_equal (Eina_Thread t1, Eina_Thread t2)
 Checks if two thread identifiers are the same.
Eina_Bool eina_thread_create (Eina_Thread *t, Eina_Thread_Priority prio, int affinity, Eina_Thread_Cb func, const void *data)
 Creates a new thread, setting its priority and affinity.
void * eina_thread_join (Eina_Thread t)
 Joins a currently running thread, waiting until it finishes.
Eina_Bool eina_thread_name_set (Eina_Thread t, const char *name)
 Sets the name of a given thread for debugging purposes.

Typedefs

typedef uintptr_t Eina_Thread
typedef void *(* Eina_Thread_Cb )(void *data, Eina_Thread t)
typedef enum _Eina_Thread_Priority Eina_Thread_Priority
typedef void *(* Eina_Thread_Cancellable_Run_Cb )(void *data)

Defines

#define EINA_THREAD_CLEANUP_PUSH(cleanup, data)   pthread_cleanup_push(cleanup, data)
 Attempts to cancel a running thread.
#define EINA_THREAD_CLEANUP_POP(exec_cleanup)   pthread_cleanup_pop(exec_cleanup)
 Pops a cleanup function to be executed when the thread is canceled.

Define Documentation

#define EINA_THREAD_CLEANUP_POP (   exec_cleanup)    pthread_cleanup_pop(exec_cleanup)

Pops a cleanup function to be executed when the thread is canceled.

This macro will remove a previously pushed cleanup function, thus if the thread is canceled with eina_thread_cancel() and the thread was previously marked as cancellable with eina_thread_cancellable_set(), that cleanup won't be executed anymore.

It must be paired with EINA_THREAD_CLEANUP_PUSH() in the same code block as they will expand to do {} while ()!

Note:
If the block within EINA_THREAD_CLEANUP_PUSH() and EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will not be executed even if exec_cleanup is EINA_TRUE! To avoid problems prefer to use eina_thread_cancellable_run()!
Parameters:
[in]exec_cleanupif EINA_TRUE, the function registered with EINA_THREAD_CLEANUP_PUSH() will be executed.
See also:
eina_thread_cancellable_run()
Since (EFL) :
1.19
#define EINA_THREAD_CLEANUP_PUSH (   cleanup,
  data 
)    pthread_cleanup_push(cleanup, data)

Attempts to cancel a running thread.

This function sends a cancellation request to the thread, however that request is only fulfilled if the thread is cancellable (eina_thread_cancellable_set() with EINA_TRUE as first parameter) and it will wait for a cancellation point, be eina_thread_cancel_checkpoint() or some syscall as defined in man:pthreads(7).

A thread that was canceled will return EINA_THREAD_JOIN_CANCELED when eina_thread_join() is called.

Parameters:
[in]tThread to cancel.
Returns:
EINA_FALSE if thread was not running, EINA_TRUE otherwise. Note that if a thread is not cancellable and it is running, this function will return EINA_TRUE!
Since (EFL) :
1.19 Enables or disables if the current thread can be canceled.

By default eina_thread_create() will return a thread with cancellation disabled. One can enable the cancellation by using EINA_TRUE in cancellable.

Eina threads follow pthread_setcanceltype() PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait for a cancellation point, usually a syscall defined in man:pthreads(7) or an explicit cancellation point defined with eina_thread_cancel_checkpoint().

In order to provide cleanup around critical blocks use EINA_THREAD_CLEANUP_PUSH() and EINA_THREAD_CLEANUP_POP() macros (which maps to pthread_cleanup_push() and pthread_cleanup_pop()), or the helper function eina_thread_cancellable_run() which does the pair for you.

Parameters:
[in]cancellableIf EINA_TRUE, this thread will be accept cancellation requests. If EINA_FALSE -- the default, it will ignore cancellation requests.
[in]was_cancellableIf non-NULL, will return the previous state, shall you want to restore.
Returns:
EINA_TRUE if it succeeds in setting the cancellable state or EINA_FALSE otherwise.
See also:
eina_thread_cancel_checkpoint()
EINA_THREAD_CLEANUP_PUSH()
EINA_THREAD_CLEANUP_POP()
eina_thread_cancellable_run()
eina_thread_cancel()
Since (EFL) :
1.19 If the current thread is cancellable, this introduces a cancellation check point. Otherwise it's a no-operation.

Eina threads follow pthread_setcanceltype() PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait for a cancellation point, usually a syscall defined in man:pthreads(7) or an explicit cancellation point defined with this function.

See also:
eina_thread_cancel_checkpoint()
Since (EFL) :
1.19

Pushes a cleanup function to be executed when the thread is canceled.

This macro will schedule a function cleanup(data) to be executed if the thread is canceled with eina_thread_cancel() and the thread was previously marked as cancellable with eina_thread_cancellable_set().

It must be paired with EINA_THREAD_CLEANUP_POP() in the same code block as they will expand to do {} while ()!

The cleanup function may also be executed if EINA_THREAD_CLEANUP_POP(EINA_TRUE) is used.

Note:
If the block within EINA_THREAD_CLEANUP_PUSH() and EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will not be executed! To avoid problems prefer to use eina_thread_cancellable_run()!
Parameters:
[in]cleanupThe function to execute on cancellation.
[in]dataThe context to give to cleanup function.
See also:
eina_thread_cancellable_run()
Since (EFL) :
1.19

Typedef Documentation

Type for a generic thread.

Type for the definition of a cancellable callback to run.

Since (EFL) :
1.19

Type for the definition of a thread callback function

Type to enumerate different thread priorities


Function Documentation

Eina_Bool eina_thread_create ( Eina_Thread t,
Eina_Thread_Priority  prio,
int  affinity,
Eina_Thread_Cb  func,
const void *  data 
)

Creates a new thread, setting its priority and affinity.

Parameters:
[out]twhere to return the thread identifier. Must not be NULL.
[in]priothread priority to use, usually EINA_THREAD_BACKGROUND
[in]affinitythread affinity to use. To not set affinity use -1.
[in]funcfunction to run in the thread. Must not be NULL.
[in]datacontext data to provide to func as first argument.
Returns:
EINA_TRUE if thread was created, EINA_FALSE on errors.
Since (EFL) :
1.8
Since :
3.0f(2.3.1)

Checks if two thread identifiers are the same.

Parameters:
[in]t1first thread identifier to compare.
[in]t2second thread identifier to compare.
Returns:
EINA_TRUE if they are equal, EINA_FALSE otherwise.
Since (EFL) :
1.8
Since :
3.0f(2.3.1)

Joins a currently running thread, waiting until it finishes.

This function will block the current thread until t finishes. The returned value is the one returned by t func() and may be NULL on errors. See Error to identify problems.

Parameters:
[in]tthread identifier to wait.
Returns:
value returned by t creation function func() or NULL on errors. Check error with Error. If the thread was canceled, it will return EINA_THREAD_JOIN_CANCELED.
Since (EFL) :
1.8
Since :
3.0f(2.3.1)
Eina_Bool eina_thread_name_set ( Eina_Thread  t,
const char *  name 
)

Sets the name of a given thread for debugging purposes.

This maps to the pthread_setname_np() GNU extension or similar if available. The name may be limited in size (possibly 16 characters including the null byte terminator). This is useful for debugging to name a thread so external tools can display a meaningful name attached to the thread.

Parameters:
[in]tthread to set the name of
[in]namea string to name the thread - this cannot be NULL
Returns:
EINA_TRUE if it succeeds in setting the name or EINA_FALSE otherwise.
Since (EFL) :
1.16
Since :
3.0f(2.3.1)

Returns identifier of the current thread.

Returns:
identifier of current thread.
Since (EFL) :
1.8
Since :
3.0f(2.3.1)

Variable Documentation

The return value of eina_thread_join() if it was canceled with eina_thread_cancel().

A thread must be explicitly flagged as cancellable with eina_thread_cancellable_set(), by default it's not and this value shouldn't be returned.

See also:
eina_thread_join()
Since (EFL) :
1.19