libwebsockets
Lightweight C library for HTML5 websockets
Threadpool related functions

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_VISIBLE LWS_EXTERN enum lws_threadpool_task_status lws_threadpool_task_status_wsi (struct lws *wsi, struct lws_threadpool_task **task, void **user)
 
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)
 

Detailed Description

Threadpool

This allows you to create one or more pool of threads which can run tasks associated with a wsi. If the pool is busy, tasks wait on a queue.

Tasks don't have to be atomic, if they will take more than a few tens of ms they should return back to the threadpool worker with a return of 0. This will allow them to abort cleanly.

Enumeration Type Documentation

◆ lws_threadpool_task_return

#include <include/libwebsockets/lws-threadpool.h>

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

49  {
62 
63  /* OR on to indicate this task wishes to outlive its wsi */
64  LWS_TP_RETURN_FLAG_OUTLIVE = 64
65 };
Definition: lws-threadpool.h:51
Definition: lws-threadpool.h:61
Definition: lws-threadpool.h:59
Definition: lws-threadpool.h:57

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,
  ... 
)

#include <include/libwebsockets/lws-threadpool.h>

lws_threadpool_create() - create a pool of worker threads

Parameters
contextthe lws_context the threadpool will exist inside
argsargument struct prepared by caller
formatprintf-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_dequeue()

LWS_VISIBLE LWS_EXTERN int lws_threadpool_dequeue ( struct lws *  wsi)

#include <include/libwebsockets/lws-threadpool.h>

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

Parameters
wsithe 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.

◆ lws_threadpool_destroy()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_destroy ( struct lws_threadpool *  tp)

#include <include/libwebsockets/lws-threadpool.h>

lws_threadpool_destroy() - Destroy a threadpool

Parameters
tpthe threadpool object

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

◆ lws_threadpool_dump()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_dump ( struct lws_threadpool *  tp)

#include <include/libwebsockets/lws-threadpool.h>

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

Parameters
tpThe 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_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,
  ... 
)

#include <include/libwebsockets/lws-threadpool.h>

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

Parameters
tpthe threadpool to queue / run on
argsinformation about what to run
formatprintf-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_finish()

LWS_VISIBLE LWS_EXTERN void lws_threadpool_finish ( struct lws_threadpool *  tp)

#include <include/libwebsockets/lws-threadpool.h>

lws_threadpool_finish() - Stop all pending and running tasks

Parameters
tpthe 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_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 
)

#include <include/libwebsockets/lws-threadpool.h>

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

Parameters
wsithe wsi to query the current task of
taskreceives a pointer to the opaque task
userreceives 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.

◆ lws_threadpool_task_sync()

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

#include <include/libwebsockets/lws-threadpool.h>

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

Parameters
taskthe task to unblock
stop0 = 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.