workqueue_create(9) [netbsd man page]

WORKQUEUE(9)						   BSD Kernel Developer's Manual					      WORKQUEUE(9)

NAME

     workqueue -- simple do-it-in-thread-context framework

SYNOPSIS

     #include <sys/workqueue.h>

     int
     workqueue_create(struct workqueue **wqp, const char *name, void (*func)(struct work *, void *), void *arg, pri_t prio, int ipl, int flags);

     void
     workqueue_enqueue(struct workqueue *wq, struct work *wk, struct cpu_info *ci);

     void
     workqueue_destroy(struct workqueue *wq);

DESCRIPTION

     The workqueue utility routines are provided to defer work which is needed to be processed in a thread context.

     workqueue_create() creates a workqueue.  It takes the following arguments:

     wqp    Specify where to store the created workqueue.

     name   The name of the workqueue.

     func   The function to be called for each work.

     arg    An argument to be passed as a second argument of func.

     prio   The priority level for the worker threads.

     ipl    The highest IPL at which this workqueue is used.

     flags  The value of 0 indicates a standard create operation, however the following flags may be bitwise ORed together:

	    WQ_MPSAFE  Specifies that the workqueue is multiprocessor safe and does its own locking, otherwise the kernel lock will be held while
		       work will be processed.

	    WQ_PERCPU  Specifies that the workqueue should have a separate queue for each CPU, thus the work could be enqueued on concrete CPUs.

     workqueue_enqueue() enqueues the work wk into the workqueue wq.

     If the WQ_PERCPU flag was set on workqueue creation, the ci argument may be used to specify the CPU on which the work should be enqueued.
     Also it may be NULL, then work will be enqueued on the current CPU.  If WQ_PERCPU flag was not set, ci must be NULL.

     The enqueued work will be processed in a thread context.  A work must not be enqueued again until the callback is called by the workqueue
     framework.

     workqueue_destroy() destroys a workqueue and frees associated resources.  The caller should ensure that the workqueue has no work enqueued
     beforehand.

RETURN VALUES

     workqueue_create() returns 0 on success.  Otherwise, it returns an errno(2).

CODE REFERENCES

     The workqueue subsystem is implemented within the file sys/kern/subr_workqueue.c.

SEE ALSO

     callout(9), condvar(9), kthread(9), softint(9)

BSD
								 October 24, 2011							       BSD

PTHREAD_WORKQUEUE(3)					   BSD Library Functions Manual 				      PTHREAD_WORKQUEUE(3)

NAME

     pthread_workqueue_init_np, pthread_workqueue_create_np, pthread_workqueue_additem_np -- thread workqueue operations

     pthread_workqueue_attr_init_np, pthread_workqueue_attr_destroy_np, pthread_workqueue_attr_getovercommit_np,
     pthread_workqueue_attr_setovercommit_np, pthread_workqueue_attr_getqueuepriority_np, pthread_workqueue_attr_setqueuepriority_np -- thread
     workqueue attribute operations

SYNOPSIS

     #include <pthread_workqueue.h>

     int
     pthread_workqueue_init_np(void);

     int
     pthread_workqueue_create_np(pthread_workqueue_t *workqp, const pthread_workqueue_attr_t * attr);

     int
     pthread_workqueue_additem_np(pthread_workqueue_t workq, void ( *workitem_func)(void *), void * workitem_arg,
	 pthread_workitem_handle_t * itemhandlep, unsigned int *gencountp);

     int
     pthread_workqueue_attr_init_np(pthread_workqueue_attr_t *attr);

     int
     pthread_workqueue_attr_destroy_np(pthread_workqueue_attr_t *attr);

     int
     pthread_workqueue_attr_getovercommit_np(pthread_workqueue_attr_t *attr, int *ocommp);

     int
     pthread_workqueue_attr_setovercommit_np(pthread_workqueue_attr_t *attr, int ocomm);

     int
     pthread_workqueue_attr_getqueuepriority_np(pthread_workqueue_attr_t *attr, int *qpriop);

     int
     pthread_workqueue_attr_setqueuepriority_np(pthread_workqueue_attr_t *attr, int qprio);

DESCRIPTION

     The pthread_workqueue_*_np() functions are used to create and submit work items to a thread pool.

     The user may create multiple work queues of different priority and manually overcommit the available resources.

     pthread_workqueue_init_np() allocates and initializes the thread workqueue subsystem.

     pthread_workqueue_create_np() creates a new thread workqueue with the attributes given by attr.  If attr is NULL then the default attributes
     are used.	A workqueue handle is returned in the workqp parameter.

     Thread workqueue attributes are used to specify parameters to pthread_workqueue_create_np().  One attribute object can be used in multiple
     calls to pthread_workqueue_create_np(), with or without modifications between calls.

     pthread_workqueue_additem_np() is used to submit work items to the thread pool specified by workq parameter.  The work item function and
     function argument are given by workitem_func and workitem_arg.  The work item handle is returned in itemhandlep.

     The pthread_workqueue_attr_init_np() function initializes attr with all the default thread workqueue attributes.

     The pthread_workqueue_attr_destroy_np() function destroys attr.

     The pthread_workqueue_attr_set*_np() functions set the attribute that corresponds to each function name.
     pthread_workqueue_attr_setovercommit_np() can be used to set the overcommit flag.	If the overcommit flag is set then more threads will be
     started, if needed, which may overcommit the physical resources of the system.  pthread_workqueue_attr_setqueuepriority_np() sets the queue
     priority attribute of the thread work queue and must be set to one of the following values:

     WORKQ_HIGH_PRIOQUEUE	 Work items in the queue with this attribute will be given higher priority by the thread scheduler.

     WORKQ_DEFAULT_PRIOQUEUE	 Work items in the queue with this attribute are given the default priority.

     WORKQ_LOW_PRIOQUEUE	 Work items in the queue with this attribute will be given lower priority by the thread scheduler.

     The pthread_workqueue_attr_get*_np() functions copy the value of the attribute that corresponds to each function name to the location pointed
     to by the second function parameter.

RETURN VALUES

     If successful, these functions return 0.  Otherwise, an error number is returned to indicate the error.

ERRORS

     The pthread_workqueue_init_np() function will fail if:

     [ENOMEM]		Out of memory.

     The pthread_workqueue_create_np() function will fail if:

     [ENOMEM]		Out of memory.

     The pthread_workqueue_additem_np() function will fail if:

     [EINVAL]		Invalid workqueue handle.

     [ENOMEM]		Out of memory.

     [ESRCH]		Can not find workqueue.

     The pthread_workqueue_attr_init_np() function will fail if:

     [ENOMEM]		Out of memory.

     The pthread_workqueue_attr_destroy_np() function will fail if:

     [EINVAL]		Invalid value for attr.

     The pthread_workqueue_attr_setqueuepriority_np() function will fail if:

     [EINVAL]		Invalid value for attr or for qprio.

     The pthread_workqueue_attr_setovercommit_np(), pthread_workqueue_attr_getovercommit_np() and pthread_workqueue_attr_getqueuepriority_np()
     functions will fail if:

     [EINVAL]		Invalid value for attr.

SEE ALSO

     pthread(3), sysctl(3)

BUGS

     There is no way, currently, to remove or destory work queues and pending work items other than exiting the process.

     All worker threads run at the same thread priority; however, items placed on high-priority workqueues will be executed before those on lower-
     priority workqueues.

HISTORY

     This thread workqueues code was created to support Grand Central Dispatch (GCD or libdispatch) and first appeared in FreeBSD 8.0.

AUTHORS

     Mark Heily <mark@heily.com>.

     Based on earlier work by
     Stacey Son <sson@FreeBSD.org> and
     Apple, Inc.

BSD
								 December 12, 2009							       BSD