Thread
Eina » Tools

Abstracts platform threads, providing a uniform API. More...

## Macros

#define | EINA_THREAD_CLEANUP_PUSH(cleanup, data)
| Pushes a cleanup function to be executed when the thread is canceled.
#define | EINA_THREAD_CLEANUP_POP(exec_cleanup)
| Pops a cleanup function to be executed when the thread is canceled.

## Typedefs

typedef uintptr_t | Eina_Thread
| Type for a generic thread.
typedef void *(* | Eina_Thread_Cb) (void *data, Eina_Thread t)
| Type for the definition of a thread callback function.
typedef void(* | Eina_Thread_Cleanup_Cb) (void *data)
| Type for the definition of a thread cleanup function.
typedef enum _Eina_Thread_Priority | Eina_Thread_Priority
| Type to enumerate different thread priorities.
typedef void *(* | Eina_Thread_Cancellable_Run_Cb) (void *data)
| Type for the definition of a cancellable callback to run.

## Enumerations

enum | _Eina_Thread_Priority { EINA_THREAD_URGENT , EINA_THREAD_NORMAL , EINA_THREAD_BACKGROUND , EINA_THREAD_IDLE }

## Functions

EINA_API Eina_Thread | eina_thread_self (void)
| Returns identifier of the current thread.
EINA_API Eina_Bool | eina_thread_equal (Eina_Thread t1, Eina_Thread t2)
| Checks if two thread identifiers are the same.
EINA_API 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.
EINA_API void * | eina_thread_join (Eina_Thread t)
| Joins a currently running thread, waiting until it finishes.
EINA_API Eina_Bool | eina_thread_name_set (Eina_Thread t, const char *name)
| Sets the name of a given thread for debugging purposes.
EINA_API Eina_Bool | eina_thread_cancel (Eina_Thread t)
| Attempts to cancel a running thread.
EINA_API Eina_Bool | eina_thread_cancellable_set (Eina_Bool cancellable, Eina_Bool *was_cancellable)
| Enables or disables if the current thread can be canceled.
EINA_API void | eina_thread_cancel_checkpoint (void)
| If the current thread is cancellable, this introduces a cancellation check point.
EINA_API void * | eina_thread_cancellable_run (Eina_Thread_Cancellable_Run_Cb cb, Eina_Free_Cb cleanup_cb, void *data)
| This function will setup cleanup callback, turn the thread cancellable, execute the given callback, reset the cancellable state to its old value, run the cleanup callback and then return the callback return value.
EINA_API void | eina_sched_prio_drop (void)
| Lowers the priority of the current thread.

## Variables

EINA_API const void * | EINA_THREAD_JOIN_CANCELED
| The return value of eina_thread_join() if it was canceled with eina_thread_cancel().

## Detailed Description

Abstracts platform threads, providing a uniform API.

It's modeled after POSIX THREADS (pthreads), on Linux they are almost 1:1 mapping.

See also
  Lock for mutex/locking abstraction.

Since
  1.8

## Macro Definition Documentation

## EINA_THREAD_CLEANUP_PUSH

#define EINA_THREAD_CLEANUP_PUSH | ( |  | cleanup,
|  |  | data )

Value:
pthread_cleanup_push(cleanup, data)

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] | cleanup | The function to execute on cancellation.
  [in] | data | The context to give to cleanup function.

See also
  eina_thread_cancellable_run()

Since
  1.19

Referenced by eina_thread_cancellable_run().

## EINA_THREAD_CLEANUP_POP

#define EINA_THREAD_CLEANUP_POP | ( |  | exec_cleanup | ) |

Value:
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_cleanup | if EINA_TRUE, the function registered with EINA_THREAD_CLEANUP_PUSH() will be executed.

See also
  eina_thread_cancellable_run()

Since
  1.19

Referenced by eina_thread_cancellable_run().

## Typedef Documentation

## Eina_Thread_Cancellable_Run_Cb

typedef void *(* Eina_Thread_Cancellable_Run_Cb) (void *data)

Type for the definition of a cancellable callback to run.

Since
  1.19

## Enumeration Type Documentation

## _Eina_Thread_Priority

enum _Eina_Thread_Priority

Enumerator
EINA_THREAD_URGENT | Higher than average process priority.
EINA_THREAD_NORMAL | Standard process priority.
EINA_THREAD_BACKGROUND | Lower than average process priority.
EINA_THREAD_IDLE | Thread to be executed only when the processor is idle.

## Function Documentation

## eina_thread_self()

EINA_API Eina_Thread eina_thread_self | ( | void |  | ) |

Returns identifier of the current thread.

Returns
  identifier of current thread.

Since
  1.8

References eina_array_new(), and EINA_TRUE.

Referenced by ecore_thread_name_set(), eina_sched_prio_drop(), eina_thread_cancel_checkpoint(), and eina_thread_cancellable_set().

## eina_thread_equal()

EINA_API Eina_Bool eina_thread_equal | ( | Eina_Thread | t1,
|  | Eina_Thread | t2 )

Checks if two thread identifiers are the same.

Parameters

  [in] | t1 | first thread identifier to compare.
  [in] | t2 | second thread identifier to compare.

Returns
  EINA_TRUE if they are equal, EINA_FALSE otherwise.

Since
  1.8

## eina_thread_create()

EINA_API 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] | t | where to return the thread identifier. Must not be `NULL`.
  [in] | prio | thread priority to use, usually EINA_THREAD_BACKGROUND
  [in] | affinity | thread affinity to use. To not set affinity use `-1`.
  [in] | func | function to run in the thread. Must not be `NULL`.
  [in] | data | context data to provide to func as first argument.

Returns
  EINA_TRUE if thread was created, EINA_FALSE on errors.

Since
  1.8

References eina_array_free(), eina_array_new(), EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_THREAD_BACKGROUND, EINA_THREAD_IDLE, EINA_THREAD_URGENT, and EINA_TRUE.

## eina_thread_join()

EINA_API void * eina_thread_join | ( | Eina_Thread | t | ) |

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] | t | thread 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
  1.8

References eina_array_free().

## eina_thread_name_set()

EINA_API 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] | t | thread to set the name of
  [in] | name | a string to name the thread - this cannot be NULL

Returns
  EINA_TRUE if it succeeds in setting the name or EINA_FALSE otherwise.

Since
  1.16

References EINA_FALSE, and EINA_TRUE.

Referenced by ecore_thread_name_set().

## eina_thread_cancel()

EINA_API Eina_Bool eina_thread_cancel | ( | Eina_Thread | t | ) |

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] | t | Thread 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
  1.19

References EINA_FALSE, and EINA_TRUE.

Referenced by ecore_thread_cancel().

## eina_thread_cancellable_set()

EINA_API Eina_Bool eina_thread_cancellable_set | ( | Eina_Bool | cancellable,
|  | Eina_Bool * | was_cancellable )

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] | cancellable | If EINA_TRUE, this thread will be accept cancellation requests. If EINA_FALSE – the default, it will ignore cancellation requests.
  [in] | was_cancellable | If 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
  1.19

References eina_thread_self(), and EINA_TRUE.

Referenced by eina_thread_cancellable_run().

## eina_thread_cancel_checkpoint()

EINA_API void eina_thread_cancel_checkpoint | ( | void |  | ) |

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
  1.19

References eina_array_count(), eina_array_pop(), EINA_THREAD_JOIN_CANCELED, and eina_thread_self().

## eina_thread_cancellable_run()

EINA_API void * eina_thread_cancellable_run | ( | Eina_Thread_Cancellable_Run_Cb | cb,
|  | Eina_Free_Cb | cleanup_cb,
|  | void * | data )

This function will setup cleanup callback, turn the thread cancellable, execute the given callback, reset the cancellable state to its old value, run the cleanup callback and then return the callback return value.

Note
  cleanup_cb is configured before the thread is made cancellable, thus it will be executed while cb may not in the case the thread was already canceled and that was pending.

This helper does exactly the following code. Should you need a slightly different behavior, use the base calls yourself.

Eina_Bool old = EINA_FALSE;
void *ret;
EINA_THREAD_CLEANUP_PUSH(cleanup_cb, data);
eina_thread_cancellable_set(EINA_TRUE, &old); // is a cancellation point
ret = cb(data); // may not run if was previously canceled
EINA_THREAD_CLEANUP_POP(EINA_TRUE);
eina_thread_cancellable_set(old, NULL);
return ret;
eina_thread_cancellable_set
EINA_API Eina_Bool eina_thread_cancellable_set(Eina_Bool cancellable, Eina_Bool *was_cancellable)
Enables or disables if the current thread can be canceled.
Definition eina_thread_posix.c:285
EINA_THREAD_CLEANUP_PUSH
#define EINA_THREAD_CLEANUP_PUSH(cleanup, data)
Pushes a cleanup function to be executed when the thread is canceled.
Definition eina_thread.h:264
EINA_THREAD_CLEANUP_POP
#define EINA_THREAD_CLEANUP_POP(exec_cleanup)
Pops a cleanup function to be executed when the thread is canceled.
Definition eina_thread.h:302
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition eina_types.h:533
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition eina_types.h:527

Parameters

  [in] | cb | a cancellable callback to possibly run. The callback may not be executed if the thread had a pending cancellation request. During its execution the callback may be canceled at explicit cancellation points using eina_thread_cancel_checkpoint(), as well as some syscalls defined in man:pthreads(7).
  [in] | cleanup_cb | a cleanup callback to be executed regardless of the thread being canceled or not. This function will be executed even if cb wasn't.
  [in] | data | context to give to both cb and cleanup_cb.

Returns
  the return value of cb. If the thread was canceled, this function will not return.

Since
  1.19

References EINA_FALSE, eina_thread_cancellable_set(), EINA_THREAD_CLEANUP_POP, EINA_THREAD_CLEANUP_PUSH, and EINA_TRUE.

## eina_sched_prio_drop()

EINA_API void eina_sched_prio_drop | ( | void |  | ) |

Lowers the priority of the current thread.

It's used by worker threads so that they use up the background CPU and do not stall the main thread. If the current thread is running with real-time priority, we decrease our priority by `RTNICENESS`. This is done in a portable way.

Otherwise, (we are running with the SCHED_OTHER policy) there's no portable way to set the nice level on the current thread. In Linux, it does work and it's the only one that is implemented as of now. In this case, the nice level is incremented on this thread by `NICENESS`.

References EINA_LOG_ERR, EINA_LOG_INFO, eina_thread_self(), and EINA_UNLIKELY.

## Variable Documentation

## EINA_THREAD_JOIN_CANCELED

EINA_API const void* EINA_THREAD_JOIN_CANCELED

extern

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
  1.19

Referenced by eina_thread_cancel_checkpoint().