Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       IV_WORK_POOL_INIT,	 iv_work_pool_create,	     iv_work_pool_put,
       IV_WORK_ITEM_INIT, iv_work_pool_submit_work - ivykis worker thread man-

       #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);

       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	 nega-
       tively 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  cre-
       ated in this pool.

       Calling iv_work_pool_submit_work	on a struct iv_work_item object	previ-
       ously 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 ar-
       gument.	 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	refer-
       ence 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 call-
       backs 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 correspond-
       ing  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.

       ivykis(3), iv_thread(3)

ivykis				  2010-09-14			    iv_work(3)


Want to link to this manual page? Use this URL:

home | help