Soletta™ Framework
Framework for making IoT devices

Full online documentation | C API Index
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Typedefs | Functions
Worker Thread

Data Structures

struct  sol_worker_thread_config
 Worker thread functions and context data configuration. More...
 

Typedefs

typedef struct sol_worker_thread sol_worker_thread
 A worker thread handle. More...
 
typedef struct
sol_worker_thread_config 
sol_worker_thread_config
 Worker thread functions and context data configuration. More...
 

Functions

void sol_worker_thread_cancel (struct sol_worker_thread *thread)
 Cancel a worker thread. More...
 
void sol_worker_thread_feedback (struct sol_worker_thread *thread)
 Schedule feedback from the worker to the main thread. More...
 
bool sol_worker_thread_is_cancelled (const struct sol_worker_thread *thread)
 Check if a worker thread has been marked as cancelled. More...
 
struct sol_worker_threadsol_worker_thread_new (const struct sol_worker_thread_config *config)
 Create and run a worker thread. More...
 

Detailed Description

Typedef Documentation

A worker thread handle.

See Also
sol_worker_thread_new()

Worker thread functions and context data configuration.

Function Documentation

void sol_worker_thread_cancel ( struct sol_worker_thread thread)

Cancel a worker thread.

The cancel function will inform the thread it should stop working, there is no preemptive cancellation – both setup(), iterate() and cleanup() (see sol_worker_thread_new()) will be executed and take the time they need, meanwhile this function will block waiting. After this function is called no further calls to iterate() will be done.

If sol_worker_thread_new() was provided with a cancel() function, then that function will be called prior to any cancellation work. You may use that function to schedule work cancellation in more fine grained fashion in your own code.

Note
this function must be called from the main thread.
Parameters
threada valid worker thread handle.
See Also
sol_worker_thread_new()
void sol_worker_thread_feedback ( struct sol_worker_thread thread)

Schedule feedback from the worker to the main thread.

This function will schedule a call to feedback() function given to sol_worker_thread_new(). This call is not guaranteed to be executed and multiple calls to sol_worker_thread_feedback() will not queue, a single one will be done. If queuing is to be done, then do it on your own using locks and a list/array in the data context.

When feedback() is called from the main thread there is no locking of data and the worker thread may be executing both setup(), iterate() or cleanup().

Note
this function must be called from the worker thread.
Parameters
threada valid worker thread handle.
See Also
sol_worker_thread_new()
bool sol_worker_thread_is_cancelled ( const struct sol_worker_thread thread)

Check if a worker thread has been marked as cancelled.

Note
this function may be called from both main and worker thread.
Parameters
threada valid worker thread handle.
Returns
true if worker thread is marked cancelled or false otherwise.
See Also
sol_worker_thread_cancel()
struct sol_worker_thread* sol_worker_thread_new ( const struct sol_worker_thread_config config)

Create and run a worker thread.

Worker threads are meant to do processing that is hard to split and play nice with cooperative workloads used by the main loop (sol_idle_add(), sol_timeout_add() and sol_fd_add()). Usually this is due blocking operating system calls or third party libraries that don't allow work to be segmented.

Worker threads shouldn't impact the main thread while they execute, but this comes at the trade off of code complexity and synchronization issues. If both the worker thread and the main thread may operate on the same data simultaneously, then it may result in partial reads and writes leading to inconsistent results if locks are not properly done. The best approach is to have the worker thread to operate on its own exclusive data and after it's finished deliver that data to users from within finished callback. If this pattern cannot be used, then employ locks to segments of data that may result into race conditions.

Note
this function must be called from the main thread.
Parameters
configworker thread configuration with functions and context data to be used.
Returns
newly allocated worker thread handle on success or NULL on errors.
See Also
sol_worker_thread_config
sol_worker_thread_cancel()
sol_worker_thread_feedback()
sol_idle_add()