Likewise Base Runtime Library
|
Event-triggered task subsystem. More...
Typedefs | |
typedef struct _LW_THREAD_POOL | LW_THREAD_POOL |
Thread pool. More... | |
typedef struct _LW_THREAD_POOL * | PLW_THREAD_POOL |
typedef struct _LW_TASK_GROUP | LW_TASK_GROUP |
Task group. More... | |
typedef struct _LW_TASK_GROUP * | PLW_TASK_GROUP |
typedef struct _LW_TASK | LW_TASK |
Task. More... | |
typedef struct _LW_TASK * | PLW_TASK |
typedef struct _LW_THREAD_POOL_ATTRIBUTES | LW_THREAD_POOL_ATTRIBUTES |
Thread pool attributes. More... | |
typedef struct _LW_THREAD_POOL_ATTRIBUTES * | PLW_THREAD_POOL_ATTRIBUTES |
typedef enum _LW_TASK_EVENT_MASK * | PLW_TASK_EVENT_MASK |
typedef struct _LW_WORK_ITEM | LW_WORK_ITEM |
Work item structure. More... | |
typedef struct _LW_WORK_ITEM * | PLW_WORK_ITEM |
typedef LW_VOID(* | LW_TASK_FUNCTION )(LW_IN PLW_TASK pTask, LW_IN LW_PVOID pContext, LW_IN LW_TASK_EVENT_MASK WakeMask, LW_IN LW_OUT LW_TASK_EVENT_MASK *pWaitMask, LW_IN LW_OUT LW_LONG64 *pllTime) |
Main task function. More... | |
typedef LW_VOID(* | LW_WORK_ITEM_FUNCTION )(PLW_WORK_ITEM pWorkItem, PVOID pContext) |
Work item function. More... | |
Functions | |
LW_NTSTATUS | LwRtlCreateTask (LW_IN PLW_THREAD_POOL pPool, LW_OUT PLW_TASK *ppTask, LW_IN LW_OPTIONAL PLW_TASK_GROUP pGroup, LW_IN LW_TASK_FUNCTION pfnFunc, LW_IN LW_PVOID pContext) |
Create a new task. More... | |
LW_NTSTATUS | LwRtlCreateTaskGroup (LW_IN PLW_THREAD_POOL pPool, LW_OUT PLW_TASK_GROUP *ppGroup) |
Create a new task group. More... | |
LW_VOID | LwRtlReleaseTask (LW_IN LW_OUT PLW_TASK *ppTask) |
Release task. More... | |
LW_VOID | LwRtlFreeTaskGroup (LW_IN LW_OUT PLW_TASK_GROUP *ppGroup) |
Free task group. More... | |
LW_NTSTATUS | LwRtlSetTaskFd (LW_IN PLW_TASK pTask, LW_IN int Fd, LW_IN LW_TASK_EVENT_MASK Mask) |
Configure file descriptor for wakeup events. More... | |
LW_NTSTATUS | LwRtlQueryTaskFd (LW_IN PLW_TASK pTask, LW_IN int Fd, LW_OUT PLW_TASK_EVENT_MASK pMask) |
Query file descriptor trigger mask. More... | |
LW_NTSTATUS | LwRtlSetTaskUnixSignal (LW_IN PLW_TASK pTask, LW_IN int Sig, LW_IN LW_BOOLEAN bSubscribe) |
Configure UNIX signal wakeup events. More... | |
LW_BOOLEAN | LwRtlNextTaskUnixSignal (LW_IN PLW_TASK pTask, LW_OUT siginfo_t *pInfo) |
Get next UNIX signal delivered to task. More... | |
LW_VOID | LwRtlWakeTask (LW_IN PLW_TASK pTask) |
Manually wake task. More... | |
LW_VOID | LwRtlCancelTask (LW_IN PLW_TASK pTask) |
Cancel task. More... | |
LW_VOID | LwRtlWaitTask (LW_IN PLW_TASK pTask) |
Wait for task completion. More... | |
LW_VOID | LwRtlWakeTaskGroup (LW_IN PLW_TASK_GROUP pGroup) |
Wake task group. More... | |
LW_VOID | LwRtlCancelTaskGroup (LW_IN PLW_TASK_GROUP pGroup) |
Cancel task group. More... | |
LW_VOID | LwRtlWaitTaskGroup (LW_IN PLW_TASK_GROUP pGroup) |
Wait for task group to complete. More... | |
LW_NTSTATUS | LwRtlCreateWorkItem (LW_IN PLW_THREAD_POOL pPool, LW_OUT PLW_WORK_ITEM *ppWorkItem, LW_IN LW_WORK_ITEM_FUNCTION pfnFunc, LW_IN PVOID pContext) |
Create work item. More... | |
LW_VOID | LwRtlFreeWorkItem (LW_IN LW_OUT PLW_WORK_ITEM *ppWorkItem) |
Free work item. More... | |
LW_VOID | LwRtlScheduleWorkItem (LW_IN PLW_WORK_ITEM pWorkItem, LW_IN LW_SCHEDULE_FLAGS Flags) |
Schedule blocking work item. More... | |
LW_VOID | LwRtlWaitWorkItems (LW_IN PLW_THREAD_POOL pPool) |
Wait for scheduled work items to complete. More... | |
LW_NTSTATUS | LwRtlCreateThreadPoolAttributes (LW_OUT PLW_THREAD_POOL_ATTRIBUTES *ppAttrs) |
Create thread pool attributes structure. More... | |
LW_NTSTATUS | LwRtlSetThreadPoolAttribute (LW_IN LW_OUT PLW_THREAD_POOL_ATTRIBUTES pAttrs, LW_IN LW_THREAD_POOL_OPTION Option,...) |
Set thread pool attribute. More... | |
VOID | LwRtlFreeThreadPoolAttributes (LW_IN LW_OUT PLW_THREAD_POOL_ATTRIBUTES *ppAttrs) |
Free thread pool attributes. More... | |
LW_NTSTATUS | LwRtlCreateThreadPool (LW_OUT PLW_THREAD_POOL *ppPool, LW_IN LW_OPTIONAL PLW_THREAD_POOL_ATTRIBUTES pAttrs) |
Create new thread pool. More... | |
LW_VOID | LwRtlFreeThreadPool (LW_IN LW_OUT PLW_THREAD_POOL *ppPool) |
Free thread pool. More... | |
LW_NTSTATUS | LwRtlMain (LW_VOID) |
Main signal loop. More... | |
LW_VOID | LwRtlExitMain (LW_NTSTATUS Status) |
Exit main loop. More... | |
LW_NTSTATUS | LwRtlBlockSignals (VOID) |
Block all signals in the current thread. More... | |
The thread pool API exposes a simple interface for creating asynchronous tasks that wake up (run) whenever certain trigger conditions are met, such as a file descriptor becoming readable or a timeout expiring. The thread pool interface abstracts away the underlying event polling mechanism and thread architecture.
typedef struct _LW_THREAD_POOL LW_THREAD_POOL |
An opaque structure representing a particular thread pool. All tasks and task groups are created within the context of a thread pool which is responsible for their implementation and lifecycle.
typedef struct _LW_TASK_GROUP LW_TASK_GROUP |
An opaque structure which represents a group of related tasks. Task groups allow multiple tasks to be triggered, cancelled, or waited upon simultaneously
typedef struct _LW_TASK LW_TASK |
An opaque structure representing a single task. Each task has an associated LW_TASK_FUNCTION which is run whenever the conditions for task wakeup are met.
typedef struct _LW_THREAD_POOL_ATTRIBUTES LW_THREAD_POOL_ATTRIBUTES |
An opaque data structure which can be used to specify a set of custom attributes when creating a thread pool
typedef struct _LW_WORK_ITEM LW_WORK_ITEM |
Opaque structure representing a work item
typedef LW_VOID(* LW_TASK_FUNCTION)(LW_IN PLW_TASK pTask, LW_IN LW_PVOID pContext, LW_IN LW_TASK_EVENT_MASK WakeMask, LW_IN LW_OUT LW_TASK_EVENT_MASK *pWaitMask, LW_IN LW_OUT LW_LONG64 *pllTime) |
A function which is run whenever the trigger conditions of a task are met. Before returning, the function should set the pWaitMask parameter to the mask of conditions under which it should next wake up, and the pllTime parameter to the next timeout.
If a non-zero time is set and the task is woken before the time expires, on the next call to the function the pllTime parameter will contain how much time was remaining. Note that the time parameter will be updated in this manner even if LW_TASK_EVENT_TIME is not one of the trigger conditions. Once the time reaches 0, it will not decrease further.
Several trigger flags have special significance:
[in] | pTask | the task |
[in] | pContex | user context pointer |
[in] | WakeMask | the mask of trigger conditions which woke the task |
[in,out] | pWaitMask | the mask of trigger conditions to wait for before the next wakeup |
[in,out] | pllTime | the time remaining until the next timeout (in nanoseconds). |
typedef LW_VOID(* LW_WORK_ITEM_FUNCTION)(PLW_WORK_ITEM pWorkItem, PVOID pContext) |
A function which is called to run a work item created with LwRtlCreateWorkItem(). A work item function – unlike a task function – may safely block.
[in] | pWorkItem | the work item |
[in] | pContext | the user context pointer |
enum LW_TASK_EVENT_MASK |
A bitmask representing a set of events.
Enumerator | |
---|---|
LW_TASK_EVENT_COMPLETE |
A special value which indicates that the task is complete when returned by an LW_TASK_FUNCTION through the pWaitMask parameter. |
LW_TASK_EVENT_INIT |
A special bit which indicates that a task has been run for the first time when passed as WakeMask parameter to an LW_TASK_FUNCTION |
LW_TASK_EVENT_EXPLICIT |
Indicates that the task was explicitly woken by an external caller, such as through LwRtlWakeTask() or LwRtlCancelTask() |
LW_TASK_EVENT_CANCEL |
Indicates that the task has been cancelled. Once cancelled, this bit will continue to be set on the WakeMask parameter of the LW_TASK_FUNCTION for all subsequent wakeups until the task completes. |
LW_TASK_EVENT_TIME |
Indicates that the last set timeout has expired. |
LW_TASK_EVENT_FD_READABLE |
Indicates that a file descriptor has become readable. |
LW_TASK_EVENT_FD_WRITABLE |
Indicates that a file descriptor has become writable. |
LW_TASK_EVENT_FD_EXCEPTION |
Indicates that an exception event occurred on a file descriptor. |
LW_TASK_EVENT_YIELD |
Indicates that the task should be immediately run again after other tasks have had a chance to run. |
LW_TASK_EVENT_UNIX_SIGNAL |
Indicates that one or more UNIX signals which the task subscribes to have arrived. |
enum LW_SCHEDULE_FLAGS |
An option that can be set on a LW_THREAD_POOL_ATTRIBUTES structure. Each option documents the types of the trailing arguments that should be passed to LwRtlSetThreadPoolAttribute().
LW_NTSTATUS LwRtlCreateTask | ( | LW_IN PLW_THREAD_POOL | pPool, |
LW_OUT PLW_TASK * | ppTask, | ||
LW_IN LW_OPTIONAL PLW_TASK_GROUP | pGroup, | ||
LW_IN LW_TASK_FUNCTION | pfnFunc, | ||
LW_IN LW_PVOID | pContext | ||
) |
Creates a new task with the specified thread pool within the specified group. The task will be immediately ready to run but will not be woken until an explicit trigger is caused by LwRtlWakeTask() or similar. On first wakeup, the LW_TASK_EVENT_INIT bit will be set on WakeMask parameter to the LW_TASK_FUNCTION.
When the task is no longer referenced externally (outside of the LW_TASK_FUNCTION itself), it should be released with LwRtlReleaseTask(). The task will not be completely freed until it has been released and the LW_TASK_FUNCTION has indicated completion by setting a wake mask of LW_TASK_EVENT_COMPLETE.
[in] | pPool | the thread pool |
[out] | ppTask | the created task |
[in] | pGroup | an optional task group for the task |
[in] | pfnFunc | the task wakeup function |
[in] | pContext | the user context pointer passed to pfnFunc |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
#LW_STATUS_CANCELLED | the specified task group was cancelled |
LW_NTSTATUS LwRtlCreateTaskGroup | ( | LW_IN PLW_THREAD_POOL | pPool, |
LW_OUT PLW_TASK_GROUP * | ppGroup | ||
) |
Creates a new task group. Whenever tasks are created, they may optionally be assigned to a task group. All tasks in a group can be conveniently woken, cancelled, or waited upon simultaneously.
[in] | pPool | the thread pool |
[out] | ppGroup | the created task |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
LW_VOID LwRtlReleaseTask | ( | LW_IN LW_OUT PLW_TASK * | ppTask | ) |
Indicates that the given task will no longer be externally referenced (i.e. outside of its own LW_TASK_FUNCTION). This function may safely be called with *ppTask equal to NULL. It sets *ppTask to NULL if it was not already.
[in,out] | ppTask | a pointer to the task pointer to release |
LW_VOID LwRtlFreeTaskGroup | ( | LW_IN LW_OUT PLW_TASK_GROUP * | ppGroup | ) |
Deletes the given task group. This function may safely be called with *ppGroup equal to NULL. It sets *ppGroup to NULL if it was not already.
[in,out] | ppGroup | a pointer to the group pointer to free |
LW_NTSTATUS LwRtlSetTaskFd | ( | LW_IN PLW_TASK | pTask, |
LW_IN int | Fd, | ||
LW_IN LW_TASK_EVENT_MASK | Mask | ||
) |
Configures a file descriptor for subsequent wakeup events. A file descriptor remains configured until it is explictly unconfigured by calling this function with an empty trigger mask. A wakeup on a given file descriptor trigger condition (e.g. LW_TASK_EVENT_FD_READ) will occur only when the condition is set both on the mask passed to this function and in the mask specified when the LW_TASK_FUNCTION returns.
[in] | pTask | the task |
[in] | Fd | the file descriptor |
[in] | Mask | the mask of trigger conditions which for which wakeups will be generated for the given descriptor |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
#LW_STATUS_INVALID_HANDLE | the provided fd was invalid |
LW_NTSTATUS LwRtlQueryTaskFd | ( | LW_IN PLW_TASK | pTask, |
LW_IN int | Fd, | ||
LW_OUT PLW_TASK_EVENT_MASK | pMask | ||
) |
Queries for the most recent mask of trigger conditions which are set for the given file descriptor.
[in] | pTask | the task |
[in] | Fd | the file descriptor |
[out] | pMask | the mask of trigger conditions which were true for the given fd on this wakeup |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INVALID_HANDLE | the provided fd was invalid or was not previously set on the given task |
LW_NTSTATUS LwRtlSetTaskUnixSignal | ( | LW_IN PLW_TASK | pTask, |
LW_IN int | Sig, | ||
LW_IN LW_BOOLEAN | bSubscribe | ||
) |
Configures whether the given task will be notified when the specified UNIX signal is delivered to the process.
Note that if a task is configured to receive any UNIX signals, it must wait for the LW_TASK_EVENT_UNIX_SIGNAL event and reap any delivered signals with LwRtlNextTaskUnixSignal(). Failure to do so can cause the main signal dispatch loop to hang.
[in,out] | pTask | the task |
[in] | Sig | the signal number |
[in] | bSubscribe | whether the task should be notified |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INVALID_PARAMETER | the provided signal was invalid |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
LW_BOOLEAN LwRtlNextTaskUnixSignal | ( | LW_IN PLW_TASK | pTask, |
LW_OUT siginfo_t * | pInfo | ||
) |
Gets the next UNIX signal which was delivered to the specified task. Because LW_TASK_EVENT_UNIX_SIGNAL events are edge-triggered, you should continue calling this function as long as it returns TRUE in order to ensure that no signals are missed.
[in,out] | pTask | the task |
[out] | pInfo | information about the UNIX signal |
TRUE | a signal was pending, and information about it was placed in pInfo |
FALSE | no signal was pending |
LW_VOID LwRtlWakeTask | ( | LW_IN PLW_TASK | pTask | ) |
Causes the specified task to wake up immediately with the LW_TASK_EVENT_EXPLICIT flag set.
[in] | pTask | the task |
LW_VOID LwRtlCancelTask | ( | LW_IN PLW_TASK | pTask | ) |
Cancels the specified task. In addition to having the same immediate effects as LwRtlWakeTask(), the LW_TASK_EVENT_CANCEL flag will be set on all task wakeups until the task completes.
[in] | pTask | the task |
LW_VOID LwRtlWaitTask | ( | LW_IN PLW_TASK | pTask | ) |
Blocks until the specified task completes by setting LW_TASK_EVENT_COMPLETE as its wait mask.
[in] | pTask | the task |
LW_VOID LwRtlWakeTaskGroup | ( | LW_IN PLW_TASK_GROUP | pGroup | ) |
Equivalent to calling LwRtlWakeTask() on all tasks in the given task group.
[in] | pGroup | the task group |
LW_VOID LwRtlCancelTaskGroup | ( | LW_IN PLW_TASK_GROUP | pGroup | ) |
All tasks in the task group are cancelled as if by LwRtlCancelTask(). In addition, any subsequent attempts to create a task within the group will fail with #LW_STATUS_CANCELLED.
[in] | pGroup | the task group |
LW_VOID LwRtlWaitTaskGroup | ( | LW_IN PLW_TASK_GROUP | pGroup | ) |
Equivalent to calling LwRtlWaitTask() on all tasks in the given task group.
[in] | pGroup | the task group |
LW_NTSTATUS LwRtlCreateWorkItem | ( | LW_IN PLW_THREAD_POOL | pPool, |
LW_OUT PLW_WORK_ITEM * | ppWorkItem, | ||
LW_IN LW_WORK_ITEM_FUNCTION | pfnFunc, | ||
LW_IN PVOID | pContext | ||
) |
Creates a work item which can be scheduled to run with LwRtlScheduleWorkItem(). Work items – unlike tasks – may block.
[in] | pPool | thread pool which will own the work item |
[out] | ppWorkItem | set to the created work item |
[in] | pfnFunc | work item function to run |
[in] | pContext | user context to pass to the callback |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
LW_VOID LwRtlFreeWorkItem | ( | LW_IN LW_OUT PLW_WORK_ITEM * | ppWorkItem | ) |
Frees a work item. Once a work item has been scheduled, this function may only be called safely from the work item function.
[in,out] | ppWorkItem | if *ppWorkItem is not NULL, it is freed and set to NULL |
LW_VOID LwRtlScheduleWorkItem | ( | LW_IN PLW_WORK_ITEM | pWorkItem, |
LW_IN LW_SCHEDULE_FLAGS | Flags | ||
) |
Schedules a work item to be run with the specified scheduling flags.
[in] | pWorkItem | the work item |
[in] | Flags | scheduling control flags |
LW_VOID LwRtlWaitWorkItems | ( | LW_IN PLW_THREAD_POOL | pPool | ) |
Blocks until all scheduled work items have finished running.
LW_NTSTATUS LwRtlCreateThreadPoolAttributes | ( | LW_OUT PLW_THREAD_POOL_ATTRIBUTES * | ppAttrs | ) |
Creates a new thread pool attributes structure.
[out] | ppAttrs | the created structure |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
LW_NTSTATUS LwRtlSetThreadPoolAttribute | ( | LW_IN LW_OUT PLW_THREAD_POOL_ATTRIBUTES | pAttrs, |
LW_IN LW_THREAD_POOL_OPTION | Option, | ||
... | |||
) |
Sets the specified option on the given thread pool attributes structure. See the documentation for LW_THREAD_POOL_OPTION for available options and the variable argument types for each.
[in,out] | pAttrs | the attributes structure |
[in] | Option | the option to set |
[in] | ... | parameters for the particular option |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_NOT_SUPPORTED | the thread pool implementation does not support that particular option |
VOID LwRtlFreeThreadPoolAttributes | ( | LW_IN LW_OUT PLW_THREAD_POOL_ATTRIBUTES * | ppAttrs | ) |
Frees a thread pool attributes structure.
[in,out] | ppAttrs | a reference to the pointer to free. *ppAttrs may be NULL when called and will be set to NULL before returning. |
LW_NTSTATUS LwRtlCreateThreadPool | ( | LW_OUT PLW_THREAD_POOL * | ppPool, |
LW_IN LW_OPTIONAL PLW_THREAD_POOL_ATTRIBUTES | pAttrs | ||
) |
Creates a new thread pool.
[out] | ppPool | the created pool |
[in] | pAttrs | optional thread pool attributes |
#LW_STATUS_SUCCESS | success |
#LW_STATUS_INSUFFICIENT_RESOURCES | out of memory |
LW_VOID LwRtlFreeThreadPool | ( | LW_IN LW_OUT PLW_THREAD_POOL * | ppPool | ) |
Frees the given thread pool. It is safe for *ppPool to be NULL. This function will set *ppPool to NULL if it was not already.
[in,out] | ppPool | a pointer to the thread pool pointer |
LW_NTSTATUS LwRtlMain | ( | LW_VOID | ) |
Runs the threadpool main signal loop. You must call this function from your program's main thread if you wish to use UNIX signal events with your threadpool tasks.
This function will not return until LwRtlExitMain() is called.
LW_VOID LwRtlExitMain | ( | LW_NTSTATUS | Status | ) |
Causes LwRtlMain() to return with the specified status code
[in] | Status | the status that LwRtlMain() should return |
LW_NTSTATUS LwRtlBlockSignals | ( | VOID | ) |
Blocks all signals in the current thread. It is recommended that your application call this function from the main thread before creating any other threads. This guarantees that all signals will be properly delivered to LwRtlMain().
LW_STATUS_SUCCESS | success |