lws-threadpool.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lws_threadpool_create_args
struct	lws_threadpool_task_args

Enumerations
enum	lws_threadpool_task_status {   LWS_TP_STATUS_QUEUED , LWS_TP_STATUS_RUNNING , LWS_TP_STATUS_SYNCING , LWS_TP_STATUS_STOPPING ,   LWS_TP_STATUS_FINISHED , LWS_TP_STATUS_STOPPED }
enum	lws_threadpool_task_return {   LWS_TP_RETURN_CHECKING_IN , LWS_TP_RETURN_SYNC , LWS_TP_RETURN_FINISHED , LWS_TP_RETURN_STOPPED ,   LWS_TP_RETURN_FLAG_OUTLIVE = 64 }

Functions
LWS_VISIBLE LWS_EXTERN struct lws_threadpool *	lws_threadpool_create (struct lws_context *context, const struct lws_threadpool_create_args *args, const char *format,...) LWS_FORMAT(3)
LWS_VISIBLE LWS_EXTERN void	lws_threadpool_finish (struct lws_threadpool *tp)
LWS_VISIBLE LWS_EXTERN void	lws_threadpool_destroy (struct lws_threadpool *tp)
LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task *	lws_threadpool_enqueue (struct lws_threadpool *tp, const struct lws_threadpool_task_args *args, const char *format,...) LWS_FORMAT(3)
LWS_VISIBLE LWS_EXTERN int	lws_threadpool_dequeue (struct lws *wsi) LWS_WARN_DEPRECATED
LWS_VISIBLE LWS_EXTERN int	lws_threadpool_dequeue_task (struct lws_threadpool_task *task)
LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status	lws_threadpool_task_status_wsi (struct lws *wsi, struct lws_threadpool_task **task, void **user) LWS_WARN_DEPRECATED
LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status	lws_threadpool_task_status (struct lws_threadpool_task *task, void **user)
LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status	lws_threadpool_task_status_noreap (struct lws_threadpool_task *task)
LWS_VISIBLE LWS_EXTERN void	lws_threadpool_task_sync (struct lws_threadpool_task *task, int stop)
LWS_VISIBLE LWS_EXTERN void	lws_threadpool_dump (struct lws_threadpool *tp)
LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task *	lws_threadpool_get_task_wsi (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int	lws_threadpool_foreach_task_wsi (struct lws *wsi, void *user, int(*cb)(struct lws_threadpool_task *task, void *user))

---

Data Structure Documentation

lws_threadpool_create_args

struct lws_threadpool_create_args

Definition at line 68 of file lws-threadpool.h.

Collaboration diagram for lws_threadpool_create_args:

Data Fields
int	threads
int	max_queue_depth

Enumeration Type Documentation

lws_threadpool_task_status

enum lws_threadpool_task_status

Enumerator
LWS_TP_STATUS_QUEUED
LWS_TP_STATUS_RUNNING
LWS_TP_STATUS_SYNCING
LWS_TP_STATUS_STOPPING
LWS_TP_STATUS_FINISHED
LWS_TP_STATUS_STOPPED

Definition at line 41 of file lws-threadpool.h.

                                {
        LWS_TP_STATUS_QUEUED,
        LWS_TP_STATUS_RUNNING,
        LWS_TP_STATUS_SYNCING,
        LWS_TP_STATUS_STOPPING,
        LWS_TP_STATUS_FINISHED, /* lws_threadpool_task_status() frees task */
        LWS_TP_STATUS_STOPPED, /* lws_threadpool_task_status() frees task */
};

lws_threadpool_task_return

enum lws_threadpool_task_return

Enumerator
LWS_TP_RETURN_CHECKING_IN	Still work to do, just confirming not being stopped
LWS_TP_RETURN_SYNC	Still work to do, enter cond_wait until service thread syncs. This is used if you have filled your buffer(s) of data to the service thread and are blocked until the service thread completes sending at least one.
LWS_TP_RETURN_FINISHED	No more work to do...
LWS_TP_RETURN_STOPPED	Responding to request to stop
LWS_TP_RETURN_FLAG_OUTLIVE

Definition at line 50 of file lws-threadpool.h.

                                {
        LWS_TP_RETURN_CHECKING_IN,
        LWS_TP_RETURN_SYNC,
        LWS_TP_RETURN_FINISHED,
        LWS_TP_RETURN_STOPPED,
 
        /* OR on to indicate this task wishes to outlive its wsi */
        LWS_TP_RETURN_FLAG_OUTLIVE = 64
};

Function Documentation

lws_threadpool_create()

LWS_VISIBLE LWS_EXTERN struct lws_threadpool* lws_threadpool_create	(	struct lws_context *	context,
		const struct lws_threadpool_create_args *	args,
		const char *	format,
			...
	)

lws_threadpool_create() - create a pool of worker threads

Parameters

context	the lws_context the threadpool will exist inside
args	argument struct prepared by caller
format	printf-type format for the task name
...	printf type args for the task name format

Creates a pool of worker threads with threads and a queue of up to max_queue_depth waiting tasks if all the threads are busy.

Returns NULL if OOM, or a struct lws_threadpool pointer that must be destroyed by lws_threadpool_destroy().

lws_threadpool_finish()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_finish

(

struct lws_threadpool *

tp

)

lws_threadpool_finish() - Stop all pending and running tasks

Parameters

tp	the threadpool object

Marks the threadpool as under destruction. Removes everything from the pending queue and completes those tasks as LWS_TP_STATUS_STOPPED.

Running tasks will also get LWS_TP_STATUS_STOPPED as soon as they "resurface".

This doesn't reap tasks or free the threadpool, the reaping is done by the lws_threadpool_task_status() on the done task.

lws_threadpool_destroy()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_destroy

(

struct lws_threadpool *

tp

)

lws_threadpool_destroy() - Destroy a threadpool

Parameters

tp	the threadpool object

Waits for all worker threads to stop, ends the threads and frees the tp.

lws_threadpool_enqueue()

LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task* lws_threadpool_enqueue	(	struct lws_threadpool *	tp,
		const struct lws_threadpool_task_args *	args,
		const char *	format,
			...
	)

lws_threadpool_enqueue() - Queue the task and run it on a worker thread when possible

Parameters

tp	the threadpool to queue / run on
args	information about what to run
format	printf-type format for the task name
...	printf type args for the task name format

This asks for a task to run ASAP on a worker thread in threadpool tp.

The args defines the wsi, a user-private pointer, a timeout in secs and a pointer to the task function.

Returns NULL or an opaque pointer to the queued (or running, or completed) task.

Once a task is created and enqueued, it can only be destroyed by calling lws_threadpool_task_status() on it after it has reached the state LWS_TP_STATUS_FINISHED or LWS_TP_STATUS_STOPPED.

lws_threadpool_dequeue()

LWS_VISIBLE LWS_EXTERN int lws_threadpool_dequeue

(

struct lws *

wsi

)

lws_threadpool_dequeue() - Dequeue or try to stop a running task

Parameters

wsi	the wsi whose current task we want to eliminate

Returns 0 is the task was dequeued or already compeleted, or 1 if the task has been asked to stop asynchronously.

This doesn't free the task. It only shortcuts it to state LWS_TP_STATUS_STOPPED. lws_threadpool_task_status() must be performed on the task separately once it is in LWS_TP_STATUS_STOPPED to free the task.

DEPRECATED: You should use lws_threadpool_dequeue_task() with lws_threadpool_get_task_wsi() / _ss() if you know there can only be one task per connection, or call it via lws_threadpool_foreach_task_wsi() / _ss() to get the tasks bound to the connection.

lws_threadpool_dequeue_task()

LWS_VISIBLE LWS_EXTERN int lws_threadpool_dequeue_task

(

struct lws_threadpool_task *

task

)

lws_threadpool_task_status_wsi()

LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status lws_threadpool_task_status_wsi	(	struct lws *	wsi,
		struct lws_threadpool_task **	task,
		void **	user
	)

lws_threadpool_task_status() - reap completed tasks

Parameters

wsi	the wsi to query the current task of
task	receives a pointer to the opaque task
user	receives a void * pointer to the task user data

This is the equivalent of posix waitpid()... it returns the status of the task, and if the task is in state LWS_TP_STATUS_FINISHED or LWS_TP_STATUS_STOPPED, frees task. If in another state, the task continues to exist.

This is designed to be called from the service thread.

Its use is to make sure the service thread has seen the state of the task before deleting it.

DEPRECATED... use lws_threadpool_task_status() instead and get the task pointer from lws_threadpool_get_task_wsi() / _ss() if you know there can only be one, else call it via lws_threadpool_foreach_task_wsi() / _ss()

lws_threadpool_task_status()

LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status lws_threadpool_task_status	(	struct lws_threadpool_task *	task,
		void **	user
	)

lws_threadpool_task_status_noreap()

LWS_VISIBLE LWS_EXTERN enum lws_threadpool_task_status lws_threadpool_task_status_noreap

(

struct lws_threadpool_task *

task

)

lws_threadpool_task_sync()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_task_sync	(	struct lws_threadpool_task *	task,
		int	stop
	)

lws_threadpool_task_sync() - Indicate to a stalled task it may continue

Parameters

task	the task to unblock
stop	0 = run after unblock, 1 = when he unblocks, stop him

Inform the task that the service thread has finished with the shared data and that the task, if blocked in LWS_TP_RETURN_SYNC, may continue.

If the lws service context determined that the task must be aborted, it should still call this but with stop = 1, causing the task to finish.

lws_threadpool_dump()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_dump

(

struct lws_threadpool *

tp

)

lws_threadpool_dump() - dump the state of a threadpool to the log

Parameters

tp	The threadpool to dump

This locks the threadpool and then dumps the pending queue, the worker threads and the done queue, together with time information for how long the tasks have been in their current state, how long they have occupied a thread, etc.

This only does anything on lws builds with CMAKE_BUILD_TYPE=DEBUG, otherwise while it still exists, it's a NOP.

lws_threadpool_get_task_wsi()

LWS_VISIBLE LWS_EXTERN struct lws_threadpool_task* lws_threadpool_get_task_wsi

(

struct lws *

wsi

)

lws_threadpool_foreach_task_wsi()

LWS_VISIBLE LWS_EXTERN int lws_threadpool_foreach_task_wsi	(	struct lws *	wsi,
		void *	user,
		int(*)(struct lws_threadpool_task *task, void *user)	cb
	)