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)