NAME

       IV_WORK_POOL_INIT,  iv_work_pool_create,  iv_work_pool_put,  IV_WORK_ITEM_INIT, iv_work_pool_submit_work,
       iv_work_pool_submit_continuation - 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);
       int iv_work_pool_submit_continuation(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.

       Calling iv_work_pool_submit_continuation from a worker thread allows submitting a work item similarly  to
       iv_work_pool_submit_work.   But  while iv_work_pool_submit_work can only be called from the thread owning
       iv_work, iv_work_pool_submit_continuation can be called from any of the worker threads. The  ->completion
       callback of these jobs will be executed from the thread owning iv_work.

       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.  iv_work_pool_submit_continuation can called from any of the worker threads.

       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)