Ecore Thread functions
Ecore » Ecore main loop

Facilities to run heavy tasks in different threads to avoid blocking the main loop. More...

## Typedefs

typedef struct _Ecore_Thread | Ecore_Thread
| A handle for threaded jobs.
typedef void(* | Ecore_Thread_Cb) (void *data, Ecore_Thread *thread)
| A callback used by Ecore_Thread helper.
typedef void(* | Ecore_Thread_Notify_Cb) (void *data, Ecore_Thread *thread, void *msg_data)
| A callback used by the main loop to receive data sent by an Ecore Thread functions.

## Functions

Ecore_Thread * | ecore_thread_run (Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data)
| Schedules a task to run in a parallel thread to avoid locking the main loop.
Ecore_Thread * | ecore_thread_feedback_run (Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data, Eina_Bool try_no_queue)
| Launches a thread to run a task that can talk back to the main thread.
Eina_Bool | ecore_thread_cancel (Ecore_Thread *thread)
| Cancels a running thread.
Eina_Bool | ecore_thread_wait (Ecore_Thread *thread, double wait)
| Blocks the main loop until the thread execution is over.
Eina_Bool | ecore_thread_check (Ecore_Thread *thread)
| Checks if a thread is pending cancellation.
Eina_Bool | ecore_thread_feedback (Ecore_Thread *thread, const void *msg_data)
| Sends data from the worker thread to the main loop.
Eina_Bool | ecore_thread_reschedule (Ecore_Thread *thread)
| Asks for the function in the thread to be called again at a later time.
int | ecore_thread_active_get (void)
| Gets the number of active threads running jobs.
int | ecore_thread_pending_get (void)
| Gets the number of short jobs waiting for a thread to run.
int | ecore_thread_pending_feedback_get (void)
| Gets the number of feedback jobs waiting for a thread to run.
int | ecore_thread_pending_total_get (void)
| Gets the total number of pending jobs.
int | ecore_thread_max_get (void)
| Gets the maximum number of threads that can run simultaneously.
void | ecore_thread_max_set (int num)
| Sets the maximum number of threads allowed to run simultaneously.
void | ecore_thread_max_reset (void)
| Resets the maximum number of concurrently running threads to the default.
int | ecore_thread_available_get (void)
| Gets the number of threads available for running tasks.
Eina_Bool | ecore_thread_name_set (Ecore_Thread *thread, const char *name)
| Sets the name of a given thread for debugging purposes.
Eina_Bool | ecore_thread_local_data_add (Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct)
| Adds some data to a hash local to the thread.
void * | ecore_thread_local_data_set (Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb)
| Sets some data in the hash local to the given thread.
void * | ecore_thread_local_data_find (Ecore_Thread *thread, const char *key)
| Gets data stored in the hash local to the given thread.
Eina_Bool | ecore_thread_local_data_del (Ecore_Thread *thread, const char *key)
| Deletes from the thread's hash the data corresponding to the given key.
Eina_Bool | ecore_thread_global_data_add (const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct)
| Adds some data to a hash shared by all threads.
void * | ecore_thread_global_data_set (const char *key, void *value, Eina_Free_Cb cb)
| Sets some data in the hash shared by all threads.
void * | ecore_thread_global_data_find (const char *key)
| Gets data stored in the hash shared by all threads.
Eina_Bool | ecore_thread_global_data_del (const char *key)
| Deletes from the shared hash the data corresponding to the given key.
void * | ecore_thread_global_data_wait (const char *key, double seconds)
| Gets data stored in the shared hash, or wait for it if it doesn't exist.

## Detailed Description

Facilities to run heavy tasks in different threads to avoid blocking the main loop.

The EFL is, for the most part, not thread safe. This means that if you have some task running in another thread and you have, for example, an Evas object to show the status progress of this task, you cannot update the object from within the thread. This can only be done from the main thread, the one running the main loop. This problem can be solved by running a thread that sends messages to the main one using an Ecore_Pipe, but when you need to handle other things like cancelling the thread, your code grows in complexity and gets much harder to maintain.

Ecore Thread is here to solve that problem. It is not a simple wrapper around standard POSIX threads (or the equivalent in other systems) and it's not meant to be used to run parallel tasks throughout the entire duration of the program, especially when these tasks are performance critical, as Ecore manages these tasks using a pool of threads based on system configuration.

What Ecore Thread does, is make it a lot easier to dispatch a worker function to perform some heavy task and then get the result once it completes, without blocking the application's UI. In addition, cancelling and rescheduling comes practically for free and the developer needs not worry about how many threads are launched, since Ecore will schedule them according to the number of processors the system has and maximum amount of concurrent threads set for the application.

At the system level, Ecore will start a new thread on an as-needed basis until the maximum set is reached. When no more threads can be launched, new worker functions will be queued in a waiting list until a thread becomes available. This way, system threads will be shared throughout different worker functions, but running only one at a time. At the same time, a worker function that is rescheduled may be run on a different thread the next time.

The Ecore_Thread handler has two meanings, depending on what context it is on. The one returned when starting a worker with any of the functions ecore_thread_run() or ecore_thread_feedback_run() is an identifier of that specific instance of the function and can be used from the main loop with the ecore_thread_cancel() and ecore_thread_check() functions. This handler must not be shared with the worker function function running in the thread. This same handler will be the one received on the `end`, `cancel` and `feedback` callbacks.

The worker function, that's the one running in the thread, also receives an Ecore_Thread handler that can be used with ecore_thread_cancel() and ecore_thread_check(), sharing the flag with the main loop. But this handler is also associated with the thread where the function is running. This has strong implications when working with thread local data.

There are two kinds of worker threads Ecore handles: simple, or short, workers and feedback workers.

The first kind is for simple functions that perform a usually small but time consuming task. Ecore will run this function in a thread as soon as one becomes available and notify the calling user of its completion once the task is done.

The following image shows the flow of a program running four tasks on a pool of two threads.

For larger tasks that may require continuous communication with the main program, the feedback workers provide the same functionality plus a way for the function running in the thread to send messages to the main thread.

The next diagram omits some details shown in the previous one regarding how threads are spawned and tasks are queued, but illustrates how feedback jobs communicate with the main loop and the special case of threads running out of pool.

See an overview example in Ecore_Thread - API overview.

## Function Documentation

## ecore_thread_run()

Ecore_Thread * ecore_thread_run | ( | Ecore_Thread_Cb | func_blocking,
|  | Ecore_Thread_Cb | func_end,
|  | Ecore_Thread_Cb | func_cancel,
|  | const void * | data )

Schedules a task to run in a parallel thread to avoid locking the main loop.

Parameters

  func_blocking | The function that should run in another thread.
  func_end | Function to call from main loop when `func_blocking` completes its task successfully (may be NULL)
  func_cancel | Function to call from main loop if the thread running `func_blocking` is cancelled or fails to start (may be NULL)
  data | User context data to pass to all callbacks.

Returns
  A new thread handler, or `NULL` on failure.

This function will try to create a new thread to run `func_blocking` in, or if the maximum number of concurrent threads has been reached, will add it to the pending list, where it will wait until a thread becomes available. The return value will be an Ecore_Thread handle that can be used to cancel the thread before its completion.

Note
  This function should always return immediately, but in the rare case that Ecore is built with no thread support, `func_blocking` will be called here, actually blocking the main loop.

Once a thread becomes available, `func_blocking` will be run in it until it finishes, then `func_end` is called from the thread containing the main loop to inform the user of its completion. While in `func_blocking`, no functions from the EFL can be used, except for those from Eina that are marked to be thread-safe. Even for the latter, caution needs to be taken if the data is shared across several threads.

`func_end` will be called from the main thread when `func_blocking` ends, so here it's safe to use anything from the EFL freely.

The thread can also be cancelled before its completion calling ecore_thread_cancel(), either from the main thread or `func_blocking`. In this case, `func_cancel` will be called, also from the main thread to inform of this happening. If the thread could not be created, this function will be called and it's `thread` parameter will be NULL. It's also safe to call any EFL function here, as it will be running in the main thread.

Inside `func_blocking`, it's possible to call ecore_thread_reschedule() to tell Ecore that this function should be called again.

Be aware that no assumptions can be made about the order in which the `func_end` callbacks for each task will be called. Once the function is running in a different thread, it's the OS that will handle its running schedule, and different functions may take longer to finish than others. Also remember that just starting several tasks together doesn't mean they will be running at the same time. Ecore will schedule them based on the number of threads available for the particular system it's running in, so some of the jobs started may be waiting until another one finishes before it can execute its own `func_blocking`.

See also
  ecore_thread_feedback_run()
  ecore_thread_cancel()
  ecore_thread_reschedule()
  ecore_thread_max_set()

Examples
  ecore_thread_example.c, and efl_thread_6.c.

References EINA_FALSE, eina_list_append(), eina_list_remove(), EINA_MAIN_LOOP_CHECK_RETURN_VAL, eina_threads_init(), eina_threads_shutdown(), and EINA_TRUE.

Referenced by ethumb_client_thumb_exists().

## ecore_thread_feedback_run()

Ecore_Thread * ecore_thread_feedback_run | ( | Ecore_Thread_Cb | func_heavy,
|  | Ecore_Thread_Notify_Cb | func_notify,
|  | Ecore_Thread_Cb | func_end,
|  | Ecore_Thread_Cb | func_cancel,
|  | const void * | data,
|  | Eina_Bool | try_no_queue )

Launches a thread to run a task that can talk back to the main thread.

Parameters

  func_heavy | The function that should run in another thread.
  func_notify | Function that receives the data sent from the thread
  func_end | Function to call from main loop when `func_heavy` completes its task successfully
  func_cancel | Function to call from main loop if the thread running `func_heavy` is cancelled or fails to start
  data | User context data to pass to all callback.
  try_no_queue | If you want to run outside of the thread pool.

Returns
  A new thread handler, or `NULL` on failure.

See ecore_thread_run() for a general description of this function.

The difference with the above is that ecore_thread_run() is meant for tasks that don't need to communicate anything until they finish, while this function is provided with a new callback, `func_notify`, that will be called from the main thread for every message sent from `func_heavy` with ecore_thread_feedback().

Like ecore_thread_run(), a new thread will be launched to run `func_heavy` unless the maximum number of simultaneous threads has been reached, in which case the function will be scheduled to run whenever a running task ends and a thread becomes free. But if `try_no_queue` is set, Ecore will first try to launch a thread outside of the pool to run the task. If it fails, it will revert to the normal behaviour of using a thread from the pool as if `try_no_queue` had not been set.

Keep in mind that Ecore handles the thread pool based on the number of CPUs available, but running a thread outside of the pool doesn't count for this, so having too many of them may have drastic effects over the program's performance.

See also
  ecore_thread_feedback()
  ecore_thread_run()
  ecore_thread_cancel()
  ecore_thread_reschedule()
  ecore_thread_max_set()

Examples
  ecore_thread_example.c, and efl_thread_5.c.

References EINA_FALSE, eina_list_append(), eina_list_remove(), EINA_MAIN_LOOP_CHECK_RETURN_VAL, eina_threads_init(), eina_threads_shutdown(), and EINA_TRUE.

Referenced by elm_store_filesystem_directory_set(), and elput_input_init().

## ecore_thread_cancel()

Eina_Bool ecore_thread_cancel | ( | Ecore_Thread * | thread | ) |

Cancels a running thread.

Parameters

  thread | The thread to cancel.

Returns
  Will return `EINA_TRUE` if the thread has been cancelled, `EINA_FALSE` if it is pending.

This function can be called both in the main loop or in the running thread.

This function cancels a running thread. If `thread` can be immediately cancelled (it's still pending execution after creation or rescheduling), then the `cancel` callback will be called, `thread` will be freed and the function will return `EINA_TRUE`.

If the thread is already running, then this function returns `EINA_FALSE` after marking the `thread` as pending cancellation. For the thread to actually be terminated, it needs to return from the user function back into Ecore control. This can happen in several ways:

- The function ends and returns normally. If it hadn't been cancelled, `func_end` would be called here, but instead `func_cancel` will happen.
- The function returns after requesting to be rescheduled with ecore_thread_reschedule().
- The function is prepared to leave early by checking if ecore_thread_check() returns `EINA_TRUE`.

- The function marks the thread as cancellable using eina_thread_cancellable_set(), allowing the thread to be terminated at explicit cancellation points defined with eina_thread_cancel_checkpoint() or with syscalls mentioned at man:pthreads(7). This allows blocking operations such as network or disk access to be stopped without polling ecore_thread_check(). Note that a cancelled thread may leak resources if no cleanup function is registered with EINA_THREAD_CLEANUP_PUSH(). Consider running such code using eina_thread_cancellable_run().

The user function can cancel itself by calling ecore_thread_cancel(), but it should always use the Ecore_Thread handle passed to it and never share it with the main loop thread by means of shared user data or any other way.

`thread` will be freed and should not be used again if this function returns `EINA_TRUE` or after the `func_cancel` callback returns.

See also
  ecore_thread_check()
  eina_thread_cancellable_run()

Examples
  ecore_thread_example.c, efl_thread_5.c, and efl_thread_6.c.

References EINA_FALSE, EINA_LIST_FOREACH, eina_list_remove_list(), eina_thread_cancel(), and EINA_TRUE.

Referenced by eio_file_cancel(), eio_shutdown(), elm_store_filesystem_directory_set(), elm_store_free(), elput_input_shutdown(), elput_manager_disconnect(), and ethumb_client_thumb_exists_cancel().

## ecore_thread_wait()

Eina_Bool ecore_thread_wait | ( | Ecore_Thread * | thread,
|  | double | wait )

Blocks the main loop until the thread execution is over.

Since
  1.13.0

Parameters

  thread | The thread to wait on.
  wait | Maximum time to wait before exiting anyway.

Returns
  EINA_TRUE if the thread execution is over.

Note: This function should only be called in the main loop.

References ecore_main_loop_thread_safe_call_wait(), ecore_time_get(), EINA_FALSE, and EINA_TRUE.

Referenced by eio_shutdown().

## ecore_thread_check()

Eina_Bool ecore_thread_check | ( | Ecore_Thread * | thread | ) |

Checks if a thread is pending cancellation.

Parameters

  thread | The thread to test.

Returns
  `EINA_TRUE` if the thread is pending cancellation, `EINA_FALSE` if it is not.

This function can be called both in the main loop or in the running thread.

When ecore_thread_cancel() is called on an already running task, the thread is marked as pending cancellation. This function returns `EINA_TRUE` if this mark is set for the given `thread` and can be used from the main loop thread to check if a still active thread has been cancelled, or from the user function running in the thread to check if it should stop doing what it's doing and return early, effectively cancelling the task.

See also
  ecore_thread_cancel()

Examples
  ecore_thread_example.c, efl_thread_5.c, and efl_thread_6.c.

References EINA_TRUE.

Referenced by eio_file_check(), and ethumb_client_thumb_exists_check().

## ecore_thread_feedback()

Eina_Bool ecore_thread_feedback | ( | Ecore_Thread * | thread,
|  | const void * | msg_data )

Sends data from the worker thread to the main loop.

Parameters

  thread | The current Ecore_Thread context to send data from
  msg_data | Data to be transmitted to the main loop

Returns
  `EINA_TRUE` if `msg_data` was successfully sent to main loop, `EINA_FALSE` if anything goes wrong.

You should use this function only in the `func_heavy` call.

Only the address to `msg_data` will be sent and once this function returns `EINA_TRUE`, the job running in the thread should never touch the contents of it again. The data sent should be malloc()'ed or something similar, as long as it's not memory local to the thread that risks being overwritten or deleted once it goes out of scope or the thread finishes.

Care must be taken that `msg_data` is properly freed in the `func_notify` callback set when creating the thread.

See also
  ecore_thread_feedback_run()

Examples
  ecore_thread_example.c, and efl_thread_5.c.

References ecore_main_loop_thread_safe_call_async(), EINA_FALSE, and EINA_TRUE.

## ecore_thread_reschedule()

Eina_Bool ecore_thread_reschedule | ( | Ecore_Thread * | thread | ) |

Asks for the function in the thread to be called again at a later time.

Parameters

  thread | The current Ecore_Thread context to rescheduled

Returns
  `EINA_TRUE` if the task was successfully rescheduled, `EINA_FALSE` if anything goes wrong.

This function should be called only from the same function represented by `thread`.

Calling this function will mark the thread for a reschedule, so as soon as it returns, it will be added to the end of the list of pending tasks. If no other tasks are waiting or there are sufficient threads available, the rescheduled task will be launched again immediately.

This should never return `EINA_FALSE`, unless it was called from the wrong thread or with the wrong arguments.

The `func_end` callback set when the thread is created will not be called until the function in the thread returns without being rescheduled. Similarly, if the `thread` is cancelled, the reschedule will not take effect.

Examples
  ecore_thread_example.c.

References EINA_FALSE, and EINA_TRUE.

## ecore_thread_active_get()

int ecore_thread_active_get | ( | void |  | ) |

Gets the number of active threads running jobs.

Returns
  Number of active threads running jobs

This returns the number of threads currently running jobs of any type through the Ecore_Thread API.

Note
  Jobs started through the ecore_thread_feedback_run() function with the `try_no_queue` parameter set to `EINA_TRUE` will not be accounted for in the return of this function unless the thread creation fails and it falls back to using one from the pool.

Examples
  ecore_thread_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_thread_pending_get()

int ecore_thread_pending_get | ( | void |  | ) |

Gets the number of short jobs waiting for a thread to run.

Returns
  Number of pending threads running "short" jobs

This returns the number of tasks started with ecore_thread_run() that are pending, waiting for a thread to become available to run them.

Examples
  ecore_thread_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_thread_pending_feedback_get()

int ecore_thread_pending_feedback_get | ( | void |  | ) |

Gets the number of feedback jobs waiting for a thread to run.

Returns
  Number of pending threads running "feedback" jobs

This returns the number of tasks started with ecore_thread_feedback_run() that are pending, waiting for a thread to become available to run them.

Examples
  ecore_thread_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_thread_pending_total_get()

int ecore_thread_pending_total_get | ( | void |  | ) |

Gets the total number of pending jobs.

Returns
  Number of pending threads running jobs

Same as the sum of ecore_thread_pending_get() and ecore_thread_pending_feedback_get().

Examples
  ecore_thread_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_thread_max_get()

int ecore_thread_max_get | ( | void |  | ) |

Gets the maximum number of threads that can run simultaneously.

Returns
  Max possible number of Ecore_Thread's running concurrently

This returns the maximum number of Ecore_Thread's that may be running at the same time. If this number is reached, new jobs started by either ecore_thread_run() or ecore_thread_feedback_run() will be added to the respective pending queue until one of the running threads finishes its task and becomes available to run a new one.

By default, this will be the proportional to the number of CPU cores found, and will be at least 1 so at least 1 worker can run through the quque of work to do.

See also
  ecore_thread_max_set()
  ecore_thread_max_reset()

Examples
  ecore_thread_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_thread_max_set()

void ecore_thread_max_set | ( | int | num | ) |

Sets the maximum number of threads allowed to run simultaneously.

Parameters

  num | The new maximum

This sets a new value for the maximum number of concurrently running Ecore_Thread's. It must an interger of at least 1 and may be limited to a reasonable value as to not overload the system too much with too many workers. This limit may change based on the number of CPU cores detected.

See also
  ecore_thread_max_get()
  ecore_thread_max_reset()

Examples
  ecore_thread_example.c.

References eina_cpu_count(), and EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_thread_max_reset()

void ecore_thread_max_reset | ( | void |  | ) |

Resets the maximum number of concurrently running threads to the default.

This resets the value returned by ecore_thread_max_get() back to its default.

See also
  ecore_thread_max_get()
  ecore_thread_max_set()

References eina_cpu_count(), and EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_thread_available_get()

int ecore_thread_available_get | ( | void |  | ) |

Gets the number of threads available for running tasks.

Returns
  The number of available threads

Same as doing ecore_thread_max_get() - ecore_thread_active_get().

This function may return a negative number only in the case the user changed the maximum number of running threads while other tasks are running.

Examples
  ecore_thread_example.c.

## ecore_thread_name_set()

Eina_Bool ecore_thread_name_set | ( | Ecore_Thread * | thread,
|  | const char * | name )

Sets the name of a given thread for debugging purposes.

This function will only succeed if called from the named thread.

Parameters

  thread | The thread context to set the name of
  name | The string to name the thread - this cannot be NULL

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

Since
  1.26

References EINA_FALSE, eina_thread_name_set(), and eina_thread_self().

## ecore_thread_local_data_add()

Eina_Bool ecore_thread_local_data_add | ( | Ecore_Thread * | thread,
|  | const char * | key,
|  | void * | value,
|  | Eina_Free_Cb | cb,
|  | Eina_Bool | direct )

Adds some data to a hash local to the thread.

Parameters

  thread | The thread context the data belongs to
  key | The name under which the data will be stored
  value | The data to add
  cb | Function to free the data when removed from the hash
  direct | If `true`, this will not copy the key string (like eina_hash_direct_add())

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure.

Ecore Thread has a mechanism to share data across several worker functions that run on the same system thread. That is, the data is stored per thread and for a worker function to have access to it, it must be run by the same thread that stored the data.

When there are no more workers pending, the thread will be destroyed along with the internal hash and any data left in it will be freed with the `cb` function given.

This set of functions is useful to share things around several instances of a function when that thing is costly to create and can be reused, but may only be used by one function at a time.

For example, if you have a program doing requisitions to a database, these requisitions can be done in threads so that waiting for the database to respond doesn't block the UI. Each of these threads will run a function, and each function will be dependent on a connection to the database, which may not be able to handle more than one request at a time so for each running function you will need one connection handle. The options then are:

- Each function opens a connection when it's called, does the work and closes the connection when it finishes. This may be costly, wasting a lot of time on resolving hostnames, negotiating permissions and allocating memory.
- Open the connections in the main loop and pass it to the threads using the data pointer. Even worse, it's just as costly as before and now it may even be kept with connections open doing nothing until a thread becomes available to run the function.
- Have a way to share connection handles, so that each instance of the function can check if an available connection exists, and if it doesn't, create one and add it to the pool. When no more connections are needed, they are all closed.

The last option is the most efficient, but it requires a lot of work to implement properly. Using thread local data helps to achieve the same result while avoiding doing all the tracking work on your code. The way to use it would be, at the worker function, to ask for the connection with ecore_thread_local_data_find() and if it doesn't exist, then open a new one and save it with ecore_thread_local_data_add(). Do the work and forget about the connection handle, when everything is done the function just ends. The next worker to run on that thread will check if a connection exists and find that it does, so the process of opening a new one has been spared. When no more workers exist, the thread is destroyed and the callback used when saving the connection will be called to close it.

This function adds the data `value` to the thread data under the given `key`. No other value in the hash may have the same `key`. If you need to change the value under a `key`, or you don't know if one exists already, you can use ecore_thread_local_data_set().

Neither `key` nor `value` may be `NULL` and `key` will be copied in the hash, unless `direct` is set, in which case the string used should not be freed until the data is removed from the hash.

The `cb` function will be called when the data in the hash needs to be freed, be it because it got deleted with ecore_thread_local_data_del() or because `thread` was terminated and the hash destroyed. This parameter may be NULL, in which case `value` needs to be manually freed after removing it from the hash with either ecore_thread_local_data_del() or ecore_thread_local_data_set(), but it's very unlikely that this is what you want.

This function, and all of the others in the `ecore_thread_local_data` family of functions, can only be called within the worker function running in the thread. Do not call them from the main loop or from a thread other than the one represented by `thread`.

See also
  ecore_thread_local_data_set()
  ecore_thread_local_data_find()
  ecore_thread_local_data_del()

Examples
  ecore_thread_example.c.

References EINA_FALSE, eina_hash_add(), eina_hash_direct_add(), and eina_hash_string_small_new().

## ecore_thread_local_data_set()

void * ecore_thread_local_data_set | ( | Ecore_Thread * | thread,
|  | const char * | key,
|  | void * | value,
|  | Eina_Free_Cb | cb )

Sets some data in the hash local to the given thread.

Parameters

  thread | The thread context the data belongs to
  key | The name under which the data will be stored
  value | The data to add
  cb | Function to free the data when removed from the hash

If no data exists in the hash under the `key`, this function adds `value` in the hash under the given `key` and returns NULL. The key itself is copied.

If the hash already contains something under `key`, the data will be replaced by `value` and the old value will be returned.

`NULL` will also be returned if either `key` or `value` are `NULL`, or if an error occurred.

This function, and all of the others in the `ecore_thread_local_data` family of functions, can only be called within the worker function running in the thread. Do not call them from the main loop or from a thread other than the one represented by `thread`.

See also
  ecore_thread_local_data_add()
  ecore_thread_local_data_del()
  ecore_thread_local_data_find()

References eina_hash_set(), and eina_hash_string_small_new().

## ecore_thread_local_data_find()

void * ecore_thread_local_data_find | ( | Ecore_Thread * | thread,
|  | const char * | key )

Gets data stored in the hash local to the given thread.

Parameters

  thread | The thread context the data belongs to
  key | The name under which the data is stored

Returns
  The value under the given key, or `NULL` on error.

Finds and return the data stored in the shared hash under the key `key`.

This function, and all of the others in the `ecore_thread_local_data` family of functions, can only be called within the worker function running in the thread. Do not call them from the main loop or from a thread other than the one represented by `thread`.

See also
  ecore_thread_local_data_add()
  ecore_thread_local_data_wait()

Examples
  ecore_thread_example.c.

References eina_hash_find().

## ecore_thread_local_data_del()

Eina_Bool ecore_thread_local_data_del | ( | Ecore_Thread * | thread,
|  | const char * | key )

Deletes from the thread's hash the data corresponding to the given key.

Parameters

  thread | The thread context the data belongs to
  key | The name under which the data is stored

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure.

If there's any data stored associated with `key` in the global hash, this function will remove it from it and return `EINA_TRUE`. If no data exists or an error occurs, it returns `EINA_FALSE`.

If the data was added to the hash with a free function, then it will also be freed after removing it from the hash, otherwise it requires to be manually freed by the user, which means that if no other reference to it exists before calling this function, it will result in a memory leak.

This function, and all of the others in the `ecore_thread_local_data` family of functions, can only be called within the worker function running in the thread. Do not call them from the main loop or from a thread other than the one represented by `thread`.

See also
  ecore_thread_local_data_add()

Examples
  ecore_thread_example.c.

References EINA_FALSE, and eina_hash_del_by_key().

## ecore_thread_global_data_add()

Eina_Bool ecore_thread_global_data_add | ( | const char * | key,
|  | void * | value,
|  | Eina_Free_Cb | cb,
|  | Eina_Bool | direct )

Adds some data to a hash shared by all threads.

Parameters

  key | The name under which the data will be stored
  value | The data to add
  cb | Function to free the data when removed from the hash
  direct | If `true`, this will not copy the key string (like eina_hash_direct_add())

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure.

Ecore Thread keeps a hash that can be used to share data across several threads, including the main loop one, without having to manually handle mutexes to do so safely.

This function adds the data `value` to this hash under the given `key`. No other value in the hash may have the same `key`. If you need to change the value under a `key`, or you don't know if one exists already, you can use ecore_thread_global_data_set().

Neither `key` nor `value` may be `NULL` and `key` will be copied in the hash, unless `direct` is set, in which case the string used should not be freed until the data is removed from the hash.

The `cb` function will be called when the data in the hash needs to be freed, be it because it got deleted with ecore_thread_global_data_del() or because Ecore Thread was shut down and the hash destroyed. This parameter may be NULL, in which case `value` needs to be manually freed after removing it from the hash with either ecore_thread_global_data_del() or ecore_thread_global_data_set().

Manually freeing any data that was added to the hash with a `cb` function is likely to produce a segmentation fault, or any other strange happenings, later on in the program.

See also
  ecore_thread_global_data_del()
  ecore_thread_global_data_set()
  ecore_thread_global_data_find()

Examples
  ecore_thread_example.c.

References EINA_FALSE, eina_hash_add(), eina_hash_direct_add(), and eina_hash_string_small_new().

## ecore_thread_global_data_set()

void * ecore_thread_global_data_set | ( | const char * | key,
|  | void * | value,
|  | Eina_Free_Cb | cb )

Sets some data in the hash shared by all threads.

Parameters

  key | The name under which the data will be stored
  value | The data to add
  cb | Function to free the data when removed from the hash

If no data exists in the hash under the `key`, this function adds `value` in the hash under the given `key` and returns NULL. The key itself is copied.

If the hash already contains something under `key`, the data will be replaced by `value` and the old value will be returned.

`NULL` will also be returned if either `key` or `value` are `NULL`, or if an error occurred.

See also
  ecore_thread_global_data_add()
  ecore_thread_global_data_del()
  ecore_thread_global_data_find()

References eina_hash_set(), and eina_hash_string_small_new().

## ecore_thread_global_data_find()

void * ecore_thread_global_data_find | ( | const char * | key | ) |

Gets data stored in the hash shared by all threads.

Parameters

  key | The name under which the data is stored

Returns
  The value under the given key, or `NULL` on error.

Finds and return the data stored in the shared hash under the key `key`.

Keep in mind that the data returned may be used by more than one thread at the same time and no reference counting is done on it by Ecore. Freeing the data or modifying its contents may require additional precautions to be considered, depending on the application's design.

See also
  ecore_thread_global_data_add()
  ecore_thread_global_data_wait()

Examples
  ecore_thread_example.c.

References eina_hash_find().

## ecore_thread_global_data_del()

Eina_Bool ecore_thread_global_data_del | ( | const char * | key | ) |

Deletes from the shared hash the data corresponding to the given key.

Parameters

  key | The name under which the data is stored

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure.

If there's any data stored associated with `key` in the global hash, this function will remove it from it and return `EINA_TRUE`. If no data exists or an error occurs, it returns `EINA_FALSE`.

If the data was added to the hash with a free function, then it will also be freed after removing it from the hash, otherwise it requires to be manually freed by the user, which means that if no other reference to it exists before calling this function, it will result in a memory leak.

Note, also, that freeing data that other threads may be using will result in a crash, so appropriate care must be taken by the application when that possibility exists.

See also
  ecore_thread_global_data_add()

Examples
  ecore_thread_example.c.

References EINA_FALSE, and eina_hash_del_by_key().

## ecore_thread_global_data_wait()

void * ecore_thread_global_data_wait | ( | const char * | key,
|  | double | seconds )

Gets data stored in the shared hash, or wait for it if it doesn't exist.

Parameters

  key | The name under which the data is stored
  seconds | The amount of time in seconds to wait for the data.

Returns
  The value under the given key, or `NULL` on error.

Finds and return the data stored in the shared hash under the key `key`.

If there's nothing in the hash under the given `key`, the function will block and wait up to `seconds` seconds for some other thread to add it with either ecore_thread_global_data_add() or ecore_thread_global_data_set(). If after waiting there's still no data to get, `NULL` will be returned.

If `seconds` is 0, then no waiting will happen and this function works like ecore_thread_global_data_find(). If `seconds` is less than 0, then the function will wait indefinitely.

Keep in mind that the data returned may be used by more than one thread at the same time and no reference counting is done on it by Ecore. Freeing the data or modifying its contents may require additional precautions to be considered, depending on the application's design.

See also
  ecore_thread_global_data_add()
  ecore_thread_global_data_find()

References ecore_time_get(), EINA_DBL_EQ, and eina_hash_find().