Ecore Thread functions
[Ecore - Main Loop and Job Functions.]

These functions allow for ecore-managed threads which integrate with ecore's main loop. More...

Functions

EAPI Ecore_Thread * ecore_thread_run (Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data)
 Run some blocking code in a parallel thread to avoid locking the main loop.
EAPI 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)
 Run some heavy code in a parallel thread to avoid locking the main loop.
EAPI Eina_Bool ecore_thread_cancel (Ecore_Thread *thread)
 Cancel a running thread.
EAPI Eina_Bool ecore_thread_check (Ecore_Thread *thread)
 Tell if a thread was canceled or not.
EAPI Eina_Bool ecore_thread_feedback (Ecore_Thread *thread, const void *data)
 Send data to main loop from worker thread.
EAPI int ecore_thread_active_get (void)
 Get number of active thread jobs.
EAPI int ecore_thread_pending_get (void)
 Get number of pending (short) thread jobs.
EAPI int ecore_thread_pending_feedback_get (void)
 Get number of pending feedback thread jobs.
EAPI int ecore_thread_pending_total_get (void)
 Get number of pending thread jobs.
EAPI int ecore_thread_max_get (void)
 Get the max number of threads that can run simultaneously.
EAPI void ecore_thread_max_set (int num)
 Set the max number of threads that can run simultaneously.
EAPI void ecore_thread_max_reset (void)
 Reset the max number of threads that can run simultaneously This resets the maximum number of threads that ecore will try to run simultaneously to the number of active cpus.
EAPI int ecore_thread_available_get (void)
 Get the number of threads which are available to be used.
EAPI Eina_Bool ecore_thread_local_data_add (Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct)
 Add data to the thread for subsequent use.
EAPI void * ecore_thread_local_data_set (Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb)
 Modify data in the thread, or add if not found.
EAPI void * ecore_thread_local_data_find (Ecore_Thread *thread, const char *key)
 Find data in the thread's data.
EAPI Eina_Bool ecore_thread_local_data_del (Ecore_Thread *thread, const char *key)
 Delete data from the thread's data.
EAPI Eina_Bool ecore_thread_global_data_add (const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct)
 Add data to the global data.
EAPI void * ecore_thread_global_data_set (const char *key, void *value, Eina_Free_Cb cb)
 Add data to the global data.
EAPI void * ecore_thread_global_data_find (const char *key)
 Find data in the global data.
EAPI Eina_Bool ecore_thread_global_data_del (const char *key)
 Delete data from the global data.
EAPI void * ecore_thread_global_data_wait (const char *key, double seconds)
 Find data in the global data and optionally wait for the data if not found.

Detailed Description

These functions allow for ecore-managed threads which integrate with ecore's main loop.


Function Documentation

EAPI int ecore_thread_active_get ( void   ) 

Get number of active thread jobs.

Returns:
Number of active threads running jobs This returns the number of threads currently running jobs through the ecore_thread api.
EAPI int ecore_thread_available_get ( void   ) 

Get the number of threads which are available to be used.

Returns:
The number of available threads This returns the number of threads slots that ecore has currently available. Assuming that you haven't changed the max number of threads with ecore_thread_max_set this should be equal to (num_cpus - (active_running + active_feedback_running))
EAPI Eina_Bool ecore_thread_cancel ( Ecore_Thread *  thread  ) 

Cancel 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.

ecore_thread_cancel give the possibility to cancel a task still running. It will return EINA_FALSE, if the destruction is delayed or EINA_TRUE if it is cancelled after this call.

This function work in the main loop and in the thread, but you should not pass the Ecore_Thread variable from main loop to the worker thread in any structure. You should always use the one passed to the Ecore_Thread_Heavy_Cb.

func_end, func_cancel will destroy the handler, so don't use it after. And if ecore_thread_cancel return EINA_TRUE, you should not use Ecore_Thread also.

EAPI Eina_Bool ecore_thread_check ( Ecore_Thread *  thread  ) 

Tell if a thread was canceled or not.

Parameters:
thread The thread to test.
Returns:
EINA_TRUE if the thread is cancelled, EINA_FALSE if it is not.

You can use this function in main loop and in the thread.

EAPI Eina_Bool ecore_thread_feedback ( Ecore_Thread *  thread,
const void *  data 
)

Send data to main loop from worker thread.

Parameters:
thread The current Ecore_Thread context to send data from
data Data to be transmitted to the main loop
Returns:
EINA_TRUE if data was successfully send to main loop, EINA_FALSE if anything goes wrong.

After a succesfull call, the data should be considered owned by the main loop.

You should use this function only in the func_heavy call.

References ecore_pipe_write().

EAPI 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 
)

Run some heavy code in a parallel thread to avoid locking the main loop.

Parameters:
func_heavy The function that should run in another thread.
func_notify The function that will receive the data send by func_heavy in the main loop.
func_end The function that will be called in the main loop if the thread terminate correctly.
func_cancel The function that will be called in the main loop if the thread is cancelled.
data User context data to pass to all callback.
try_no_queue If you wan't to run outside of the thread pool.
Returns:
A reference to the newly created thread instance, or NULL if it failed.

ecore_thread_feedback_run provide a facility for easily managing heavy task in a parallel thread. You should provide four functions. The first one, func_heavy, that will do the heavy work in another thread (so you should not use the EFL in it except Eina and Eet if you are careful). The second one, func_notify, will receive the data send from the thread function (func_heavy) by ecore_thread_notify in the main loop (and so, can use all the EFL). Tje third, func_end, that will be called in Ecore main loop when func_heavy is done. So you can use all the EFL inside this function. The last one, func_cancel, will be called in the main loop also, if the thread is cancelled or could not run at all.

Be aware, that you can't make assumption on the result order of func_end after many call to ecore_feedback_run, as we start as much thread as the host CPU can handle.

If you set try_no_queue, it will try to run outside of the thread pool, this can bring the CPU down, so be careful with that. Of course if it can't start a new thread, it will try to use one from the pool.

References ecore_pipe_add(), and ecore_pipe_del().

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

Add data to the global data.

Parameters:
key The name string to add the data with
value The data to add
cb The optional callback to free the data with once ecore is shut down
direct If true, this will not copy the key string (like eina_hash_direct_add)
Returns:
EINA_TRUE on success, EINA_FALSE on failure This adds data to the global thread data, and will return EINA_FALSE in any case but success. All data added to global can be manually freed, or a callback can be provided with cb which will be called upon ecore_thread shutting down. Note that if you have manually freed data that a callback was specified for, you will most likely encounter a segv later on.
EAPI Eina_Bool ecore_thread_global_data_del ( const char *  key  ) 

Delete data from the global data.

Parameters:
key The name string the data is associated with
Returns:
EINA_TRUE on success, EINA_FALSE on failure This deletes the data pointer from the global data which was previously added with ecore_thread_global_data_add This function will return EINA_FALSE in any case but success. Note that this WILL free the data if an Eina_Free_Cb was specified when the data was added.
EAPI void * ecore_thread_global_data_find ( const char *  key  ) 

Find data in the global data.

Parameters:
key The name string the data is associated with
Returns:
The value, or NULL on error This finds data in the global data that has been previously added with ecore_thread_global_data_add This function will return NULL in any case but success. All data added to global can be manually freed, or a callback can be provided with cb which will be called upon ecore_thread shutting down. Note that if you have manually freed data that a callback was specified for, you will most likely encounter a segv later on.
Note:
Keep in mind that the data returned can be used by multiple threads at a time, so you will most likely want to mutex if you will be doing anything with it.
EAPI void * ecore_thread_global_data_set ( const char *  key,
void *  value,
Eina_Free_Cb  cb 
)

Add data to the global data.

Parameters:
key The name string to add the data with
value The data to add
cb The optional callback to free the data with once ecore is shut down
Returns:
An Ecore_Thread_Data on success, NULL on failure This adds data to the global thread data and returns NULL, or replaces the previous data associated with key and returning the previous data if it existed. To see if an error occurred, one must use eina_error_get. All data added to global can be manually freed, or a callback can be provided with cb which will be called upon ecore_thread shutting down. Note that if you have manually freed data that a callback was specified for, you will most likely encounter a segv later on.
EAPI void * ecore_thread_global_data_wait ( const char *  key,
double  seconds 
)

Find data in the global data and optionally wait for the data if not found.

Parameters:
key The name string the data is associated with
seconds The amount of time in seconds to wait for the data. If 0, the call will be async and not wait for data. If < 0 the call will wait indefinitely for the data.
Returns:
The value, or NULL on failure This finds data in the global data that has been previously added with ecore_thread_global_data_add This function will return NULL in any case but success. Use seconds to specify the amount of time to wait. Use > 0 for an actual wait time, 0 to not wait, and < 0 to wait indefinitely.
Note:
Keep in mind that the data returned can be used by multiple threads at a time, so you will most likely want to mutex if you will be doing anything with it.

References ecore_time_get().

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

Add data to the thread for subsequent use.

Parameters:
thread The thread context to add to
key The name string to add the data with
value The data to add
cb The callback to free the data with
direct If true, this will not copy the key string (like eina_hash_direct_add)
Returns:
EINA_TRUE on success, EINA_FALSE on failure This adds data to the thread context, allowing the thread to retrieve and use it without complicated mutexing. This function can only be called by a *_run thread INSIDE the thread and will return EINA_FALSE in any case but success. All data added to the thread will be freed with its associated callback (if present) upon thread termination. If no callback is specified, it is expected that the user will free the data, but this is most likely not what you want.
EAPI Eina_Bool ecore_thread_local_data_del ( Ecore_Thread *  thread,
const char *  key 
)

Delete data from the thread's data.

Parameters:
thread The thread context
key The name string the data is associated with
Returns:
EINA_TRUE on success, EINA_FALSE on failure This deletes the data pointer from the thread context which was previously added with ecore_thread_local_data_add This function can only be called by a *_run thread INSIDE the thread, and will return EINA_FALSE in any case but success. Note that this WILL free the data if a callback was specified.
EAPI void * ecore_thread_local_data_find ( Ecore_Thread *  thread,
const char *  key 
)

Find data in the thread's data.

Parameters:
thread The thread context
key The name string the data is associated with
Returns:
The value, or NULL on error This finds data in the thread context that has been previously added with ecore_thread_local_data_add This function can only be called by a *_run thread INSIDE the thread, and will return NULL in any case but success.
EAPI void * ecore_thread_local_data_set ( Ecore_Thread *  thread,
const char *  key,
void *  value,
Eina_Free_Cb  cb 
)

Modify data in the thread, or add if not found.

Parameters:
thread The thread context
key The name string to add the data with
value The data to add
cb The callback to free the data with
Returns:
The old data associated with key on success if modified, NULL if added This adds/modifies data in the thread context, adding only if modify fails. This function can only be called by a *_run thread INSIDE the thread. All data added to the thread pool will be freed with its associated callback (if present) upon thread termination. If no callback is specified, it is expected that the user will free the data, but this is most likely not what you want.
EAPI int ecore_thread_max_get ( void   ) 

Get the max number of threads that can run simultaneously.

Returns:
Max number of threads ecore will run This returns the total number of threads that ecore will attempt to run simultaneously.
EAPI void ecore_thread_max_set ( int  num  ) 

Set the max number of threads that can run simultaneously.

Parameters:
num The new maximum This sets the maximum number of threads that ecore will try to run simultaneously. This number cannot be < 1 or >= 2x the number of active cpus.
EAPI int ecore_thread_pending_feedback_get ( void   ) 

Get number of pending feedback thread jobs.

Returns:
Number of pending threads running "feedback" jobs This returns the number of threads currently running jobs through the ecore_thread_feedback_run api call.
EAPI int ecore_thread_pending_get ( void   ) 

Get number of pending (short) thread jobs.

Returns:
Number of pending threads running "short" jobs This returns the number of threads currently running jobs through the ecore_thread_run api call.
EAPI int ecore_thread_pending_total_get ( void   ) 

Get number of pending thread jobs.

Returns:
Number of pending threads running jobs This returns the number of threads currently running jobs through the ecore_thread_run and ecore_thread_feedback_run api calls combined.
EAPI Ecore_Thread * ecore_thread_run ( Ecore_Thread_Cb  func_blocking,
Ecore_Thread_Cb  func_end,
Ecore_Thread_Cb  func_cancel,
const void *  data 
)

Run some blocking code in a parallel thread to avoid locking the main loop.

Parameters:
func_blocking The function that should run in another thread.
func_end The function that will be called in the main loop if the thread terminate correctly.
func_cancel The function that will be called in the main loop if the thread is cancelled.
data User context data to pass to all callback.
Returns:
A reference to the newly created thread instance, or NULL if it failed.

ecore_thread_run provide a facility for easily managing blocking task in a parallel thread. You should provide three function. The first one, func_blocking, that will do the blocking work in another thread (so you should not use the EFL in it except Eina if you are careful). The second one, func_end, that will be called in Ecore main loop when func_blocking is done. So you can use all the EFL inside this function. The last one, func_cancel, will be called in the main loop if the thread is cancelled or could not run at all.

Be aware, that you can't make assumption on the result order of func_end after many call to ecore_thread_run, as we start as much thread as the host CPU can handle.