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

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

NAME

     kthread_create, kthread_destroy, kthread_exit, kthread_join -- kernel threads

SYNOPSIS

     #include <sys/kthread.h>

     int
     kthread_create(pri_t pri, int flags, struct cpu_info *ci, void (*func)(void *), void *arg, lwp_t **newlp, const char *fmt, ...);

     void
     kthread_destroy(lwp_t *l);

     void
     kthread_exit(int ecode);

     int
     kthread_join(lwp_t *l);

DESCRIPTION

     Kernel threads are light-weight processes which execute entirely within the kernel.

     Any process can request the creation of a new kernel thread.  Kernel threads are not swapped out during memory congestion.  The VM space and
     limits are shared with proc0 (usually swapper).

FUNCTIONS

     kthread_create(pri, flags, ci, func, arg, newlp, fmt, ...)
	      Create a kernel thread.  The arguments are as follows.

	      pri      Priority level for the thread.  If no priority level is desired specify PRI_NONE, causing kthread_create() to select the
		       default priority level.

	      flags    Flags that can be logically ORed together to alter the thread's behaviour.

	      ci       If non-NULL, the thread will be created bound to the CPU specified by ci, meaning that it will only ever execute on that
		       CPU.  By default, the threads are free to execute on any CPU in the system.

	      func     A function to be called when the thread begins executing.  This function must not return.  If the thread runs to comple-
		       tion, it must call kthread_exit() to properly terminate itself.

	      arg      An argument to be passed to func().  May be NULL if not required.

	      newlp    A pointer to receive the new LWP structure for the kernel thread.  May be NULL, unless KTHREAD_MUSTJOIN is specified in
		       flags.

	      fmt      A string containing format information used to display the kernel thread name.  Must not be NULL.

	      The following flags are defined.

	      KTHREAD_IDLE	Causes the thread to be created in the LSIDL (idle) state.  By default, the threads are created in the LSRUN
				(runnable) state, meaning they will begin execution shortly after creation.

	      KTHREAD_MPSAFE	Specifies that the thread does its own locking and so is multiprocessor safe.  If not specified, the global kernel
				lock will be held whenever the thread is running (unless explicitly dropped by the thread).

	      KTHREAD_INTR	Specifies that the thread services device interrupts.  This flag is intended for kernel internal use and should
				not normally be specified.

	      KTHREAD_TS	Causes the kthread to be created in the SCHED_OTHER class (timeshared).  The thread's priority will be dynamically
				adjusted by the scheduler.  Increased activity by the kthread will cause its priority to fall; decreased activity
				will cause its priority to rise.  By default, kthreads are created in the SCHED_RR class, with a fixed priority
				specified by pri.  Threads in the SCHED_RR class do not have their priority dynamically adjusted by the scheduler.

	      KTHREAD_MUSTJOIN	Indicates that created kthread must be joined.	In such case kthread_exit() will wait until kthread_join() will be
				called.

     kthread_destroy(l)
	      From another thread executing in the kernel, cause a kthread to exit.  The kthread must be in the LSIDL (idle) state.

     kthread_exit(ecode)
	      Exit from a kernel thread.  Must only be called by a kernel thread.

     kthread_join(l)
	      Suspend execution of calling thread until the target kthread terminates.	Conceptually the function can be compared to the user
	      space pthread_join(3), however it must be called only once for kernel thread which was created using the KTHREAD_MUSTJOIN flag and
	      would wait on kthread_exit.

RETURN VALUES

     Upon successful completion, kthread_create() returns 0.  Otherwise, the following error values are returned:

     [EAGAIN]  The limit on the total number of system processes would be exceeded.

     [EAGAIN]  The limit RLIMIT_NPROC on the total number of processes under execution by this user id would be exceeded.

CODE REFERENCES

     The kthread framework itself is implemented within the file sys/kern/kern_kthread.c.  Data structures and function prototypes for the frame-
     work are located in sys/sys/kthread.h.

SEE ALSO

     condvar(9), driver(9), softint(9), workqueue(9)

HISTORY

     The kthread framework appeared in NetBSD 1.4.

BSD
								  August 7, 2011							       BSD