home | help 
iv_work(3)		   ivykis programmer's manual		      iv_work(3)

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_continua-
     tion - 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 ini-
     tialised 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 influ-
     encing 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  sub-
     mitting  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 terminat-
     ing 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_sub-
     mit_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)

ivykis				   2010-09-14			      iv_work(3)
home | help