worker_thread.h File Reference

Threaded worker support. More...

#include <sys/cdefs.h>
#include <kos/thread.h>
#include <sys/queue.h>

Go to the source code of this file.

Data Structures
struct	kthread_job_t
	Structure describing one job for the worker. More...

Typedefs
typedef struct kthread_worker	kthread_worker_t

Functions
kthread_worker_t *	thd_worker_create_ex (const kthread_attr_t *attr, void(*routine)(void *), void *data)
	Create a new worker thread with the specific set of attributes.
static kthread_worker_t *	thd_worker_create (void(*routine)(void *), void *data)
	Create a new worker thread.
void	thd_worker_destroy (kthread_worker_t *thd)
	Stop and destroy a worker thread.
void	thd_worker_wakeup (kthread_worker_t *thd)
	Wake up a worker thread.
kthread_t *	thd_worker_get_thread (kthread_worker_t *thd)
	Get a handle to the underlying thread.
void	thd_worker_add_job (kthread_worker_t *thd, kthread_job_t *job)
	Add a new job to the worker thread.
kthread_job_t *	thd_worker_dequeue_job (kthread_worker_t *worker)
	Dequeue one job from the worker thread's to-do queue.

Detailed Description

Threaded worker support.

This file contains the threaded worker API. Threaded workers are threads that are idle most of the time, until they are notified that there is work pending; in which case they will call their associated work function.

The work function can then process any number of tasks, until it clears out all of its tasks or decides that it worked enough; in which case the function can return, and will re-start the next time it is notified, or if it was notified while it was running.

An optional API is also present, which provides a FIFO for jobs to be processed by the threaded worker. This is useful when jobs have to be processed in sequence.

Author

Paul Cercueil

See also

kos/thread.h

Typedef Documentation

kthread_worker_t

typedef struct kthread_worker kthread_worker_t

Function Documentation

thd_worker_add_job()

void thd_worker_add_job	(	kthread_worker_t *	thd,
		kthread_job_t *	job )

Add a new job to the worker thread.

This function will append the job to the worker thread's to-do queue. Note that it is the responsability of the work function (the one passed to thd_worker_create()) to dequeue and process the jobs with thd_worker_dequeue_job(). Also, this function won't automatically notify the worker thread - you still need to call thd_worker_wakeup().

Parameters

thd	The worker thread to add a job to.
job	The new job to give to the worker thread.

thd_worker_create()

static kthread_worker_t * thd_worker_create ( void(* routine )(void *), void * data )

inlinestatic

Create a new worker thread.

This function will create a thread with the default attributes that will call the given routine with the given param pointer when notified. The thread will only stop when thd_worker_destroy() is called.

Parameters

routine	The function to call in the worker thread.
data	A parameter to pass to the function called.

Returns

The new worker thread on success, NULL on failure.

See also

thd_worker_destroy, thd_worker_wakeup

thd_worker_create_ex()

kthread_worker_t * thd_worker_create_ex	(	const kthread_attr_t *	attr,
		void(*	routine )(void *),
		void *	data )

Create a new worker thread with the specific set of attributes.

This function will create a thread with the specified attributes that will call the given routine with the given param pointer when notified. The thread will only stop when thd_worker_destroy() is called.

Parameters

attr	A set of thread attributes for the created thread. Passing NULL will initialize all attributes to their default values.
routine	The function to call in the worker thread.
data	A parameter to pass to the function called.

Returns

The new worker thread on success, NULL on failure.

See also

thd_worker_destroy, thd_worker_wakeup

Referenced by kthread_worker_t::thd_worker_create().

thd_worker_dequeue_job()

kthread_job_t * thd_worker_dequeue_job

(

kthread_worker_t *

worker

)

Dequeue one job from the worker thread's to-do queue.

Use this function to dequeue one job from the worker thread, that has been previously queued using thd_worker_add_job(). This function is typically used inside the work function registered with thd_worker_create().

Parameters

worker

The worker thread to add a job to.

Returns

A new job to process, or NULL if there is none.

thd_worker_destroy()

void thd_worker_destroy

(

kthread_worker_t *

thd

)

Stop and destroy a worker thread.

This function will stop the worker thread and free its memory.

Parameters

thd	The worker thread to destroy.

See also

thd_worker_create, thd_worker_wakeup

thd_worker_get_thread()

kthread_t * thd_worker_get_thread

(

kthread_worker_t *

thd

)

Get a handle to the underlying thread.

Parameters

thd	The worker thread whose handle should be returned.

Returns

A handle to the underlying thread.

thd_worker_wakeup()

void thd_worker_wakeup

(

kthread_worker_t *

thd

)

Wake up a worker thread.

This function will wake up the worker thread, causing it to call its corresponding work function. Usually, this should be called after a new job has been added with thd_worker_add_job().

Parameters

thd	The worker thread to wake up.

See also

thd_worker_create, thd_worker_destroy, thd_worker_add_job