NAME¶
IV_WORK_POOL_INIT, iv_work_pool_create, iv_work_pool_put, IV_WORK_ITEM_INIT,
iv_work_pool_submit_work - ivykis worker thread management
SYNOPSIS¶
#include <iv_work.h>
struct iv_work_pool {
int max_threads;
void *cookie;
void (*thread_start)(void *cookie);
void (*thread_stop)(void *cookie);
};
struct iv_work_item {
void *cookie;
void (*work)(void *cookie);
void (*completion)(void *cookie);
};
void IV_WORK_POOL_INIT(struct iv_work_pool *this);
int iv_work_pool_create(struct iv_work_pool *this);
int iv_work_pool_put(struct iv_work_pool *this);
void IV_WORK_ITEM_INIT(struct iv_work_item *work);
int iv_work_pool_submit_work(struct iv_work_pool *this, struct
iv_work_item *work);
DESCRIPTION¶
Calling
iv_work_pool_create on a
struct iv_work_pool object
previously initialised by
IV_WORK_POOL_INIT creates a pool of worker
threads that can be used to offload CPU intensive tasks to, so as to prevent
negatively influencing event handling latency in the calling thread, and to
enable the use of multiple host CPUs for CPU intensive tasks.
iv_work dynamically adjusts the number of threads in the pool to the
amount of work there is to do. The
->max_threads member of
struct
iv_work_pool specifies the maximum number of threads that will be created
in this pool.
Calling
iv_work_pool_submit_work on a
struct iv_work_item object
previously initialised by
IV_WORK_ITEM_INIT submits a work item to a
pool. The
->work member of
struct iv_work_item specifies the
function that will be called in one of the worker threads in the pool
specified by
->this, with
->cookie as its sole argument.
When the work function has completed,
iv_work will call the
->completion callback to indicate this, also with
->cookie
as its sole argument, in the thread that
iv_work_pool_create was called
in for this pool object.
As a special case, calling
iv_work_pool_submit_work with a
NULL
work pool pointer will cause the work item to be processed in the local
thread, from an
iv_task(3) callback.
If the
->thread_start function pointer specified in
struct
iv_work_pool is not NULL, it will be called upon creation of a new worker
thread, in the context of the created worker thread, with
->cookie
as its sole argument. Calls to
->thread_start are not explicitly
serialised, which should be kept in mind when manipulating state shared
between threads from within that callback function.
Similarly, if
iv_work decides to terminate a worker thread, for example
due to inactivity,
->thread_stop will be called in the context of
the terminating thread, with
->cookie as its sole argument. Calls to
->thread_stop are also not explicitly serialised.
iv_work_pool_submit_work can only be called from the thread that
iv_work_pool_create for this pool object was called in.
There is no way to cancel submitted work items.
There is no guaranteed order, FIFO or otherwise, between different work items
submitted to the same worker thread pool.
When the user has no more work items to submit to the pool, its reference to the
pool can be dropped by calling
iv_work_pool_put.
If there are still pending or running work items assigned to this pool when
iv_work_pool_put is called, those work items will not be canceled, but
will be allowed to run to completion, and their
->completion
callbacks will be called as usual. A similar thing holds for the
->thread_start and
->thread_stop callbacks -- they can
also still be called after
iv_work_pool_put returns. Even so, the
memory corresponding to the
struct iv_work_pool can immediately be
freed or reused by the user upon return of the
iv_work_pool_put call.
Internally,
iv_work uses
iv_thread(3) for its thread management.
SEE ALSO¶
ivykis(3),
iv_thread(3)