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

FreeBSD Manual Pages

  
 
  

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_con-
       tinuation - 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 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.

       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  own-
       ing iv_work, iv_work_pool_submit_continuation can be called from	any of
       the worker threads. The ->completion callback of	these jobs will	be ex-
       ecuted 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 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.
       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	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.

SEE ALSO
       ivykis(3), iv_thread(3)

ivykis				  2010-09-14			    iv_work(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=iv_work_pool_submit_work&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help