Worker Thread Utility

General Description

Worker thread utility that allows functions to be run a different thread context.

This utility can be used to delegate work that is not timing critical. For example, scheduling work in interrupt handlers to keep handler execution times low or if some work needs to be done at a different priority.

Data Structures
struct	cy_worker_thread_params_t
	Worker Thread Parameters. More...
struct	cy_worker_thread_info_t
	Worker Thread Information. More...

Macros
#define	CY_WORKER_THREAD_DEFAULT_NAME   "CYWorker"
	< Default worker thread name
#define	CY_WORKER_DEFAULT_ENTRIES   (16)
	Default number of work items in the queue.
#define	CY_WORKER_THREAD_ERR_THREAD_INVALID    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 32)
	Additional work cannot be enqueued because the worker thread has been terminated. More...

Typedefs
typedef void()	cy_worker_thread_func_t(void *arg)
	Worker thread function call prototype

Enumerations
enum	cy_worker_thread_state_t {   CY_WORKER_THREAD_INVALID ,   CY_WORKER_THREAD_VALID ,   CY_WORKER_THREAD_ENQUEUING ,   CY_WORKER_THREAD_TERMINATING ,   CY_WORKER_THREAD_JOIN_COMPLETE }
	Thread state enumeration. More...

Functions
cy_rslt_t	cy_worker_thread_create (cy_worker_thread_info_t *new_worker, const cy_worker_thread_params_t *params)
	Create worker thread to handle running callbacks in a separate thread. More...
cy_rslt_t	cy_worker_thread_delete (cy_worker_thread_info_t *old_worker)
	Delete worker thread. More...
cy_rslt_t	cy_worker_thread_enqueue (cy_worker_thread_info_t *worker_info, cy_worker_thread_func_t *work_func, void *arg)
	Queue work on a worker thread. More...

---

Data Structure Documentation

cy_worker_thread_params_t

struct cy_worker_thread_params_t

Data Fields
cy_thread_priority_t	priority	Requested thread priority.
uint32_t	stack_size	Size of stack for new thread. Note that this must be atleast CY_RTOS_MIN_STACK_SIZE
uint8_t *	stack	Pointer to stack. If this is NULL a stack of size stack_size will be allocated.
const char *	name	Thread name. If set to NULL, CY_WORKER_THREAD_DEFAULT_NAME will be used.
uint32_t	num_entries	Maximum number of enteries the worker thread can queue. If set to 0, CY_WORKER_DEFAULT_ENTRIES will be used.

cy_worker_thread_info_t

struct cy_worker_thread_info_t

Data Fields
cy_queue_t	event_queue	Event Queue for this thread.
uint32_t	enqueue_count	Number of conccurent enqueue requests.
cy_thread_t	thread	Thread object
cy_worker_thread_state_t	state	State of the worker thread

Macro Definition Documentation

CY_WORKER_THREAD_ERR_THREAD_INVALID

#define CY_WORKER_THREAD_ERR_THREAD_INVALID    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 32)

Additional work cannot be enqueued because the worker thread has been terminated.

This can occur if cy_worker_thread_create was not called or cy_worker_thread_delete was called before calling cy_worker_thread_enqueue

Enumeration Type Documentation

cy_worker_thread_state_t

enum cy_worker_thread_state_t

Thread state enumeration.

Enumerator
CY_WORKER_THREAD_INVALID	Worker Thread is in invalid state
CY_WORKER_THREAD_VALID	Worker Thread is in valid state
CY_WORKER_THREAD_ENQUEUING	Worker Thread is adding to the queue
CY_WORKER_THREAD_TERMINATING	Worker Thread is starting to terminate.
CY_WORKER_THREAD_JOIN_COMPLETE	Worker Thread join is complete

Function Documentation

cy_worker_thread_create()

cy_rslt_t cy_worker_thread_create	(	cy_worker_thread_info_t *	new_worker,
		const cy_worker_thread_params_t *	params
	)

Create worker thread to handle running callbacks in a separate thread.

Note

Calling this function twice on the same thread object ( cy_worker_thread_info_t) without calling cy_worker_thread_delete will cause memory leakage.

Parameters

[out]	new_worker	pointer to cy_worker_thread_info_t structure to be filled when created.
[in]	params	pointer to requested parameters for starting worker thread.

Returns

The status of the worker thread creation request.

cy_worker_thread_delete()

cy_rslt_t cy_worker_thread_delete

(

cy_worker_thread_info_t *

old_worker

)

Delete worker thread.

Note

This function will wait for the thread to complete all pending work in the queue and exit before returning.

Parameters

[in]

old_worker

pointer to cy_worker_thread_info_t structure to be deleted.

Returns

The status of the deletion of the worker thread.

cy_worker_thread_enqueue()

cy_rslt_t cy_worker_thread_enqueue	(	cy_worker_thread_info_t *	worker_info,
		cy_worker_thread_func_t *	work_func,
		void *	arg
	)

Queue work on a worker thread.

Call the given function in the worker thread context.

Note

If the thread priority is below that of the current thread, you must yield to allow the worker thread to run. This can be done by calling cy_rtos_delay_milliseconds or by waiting on an RTOS object in all higher priority threads.

Parameters

[in]	worker_info	pointer to worker_thread used to run function
[in]	work_func	function to run
[in]	arg	opaque arg to be used in function call

Returns

The status of the queueing of work.