Mon Aug 3 23:03:05 2009 UTC ()
Merge workqueue_create(9), workqueue_destroy(9) and workqueue_enqueue(9)
into a single workqueue(9) man page.


(rmind)
diff -r1.286 -r1.287 src/share/man/man9/Makefile
diff -r1.5 -r1.6 src/share/man/man9/workqueue.9
diff -r1.11 -r0 src/share/man/man9/workqueue_create.9
diff -r1.2 -r0 src/share/man/man9/workqueue_destroy.9
diff -r1.4 -r0 src/share/man/man9/workqueue_enqueue.9
cvs diff -r1.286 -r1.287 src/share/man/man9/Makefile (expand / switch to unified diff)

--- src/share/man/man9/Makefile 2009/08/03 22:16:01 1.286
+++ src/share/man/man9/Makefile 2009/08/03 23:03:05 1.287
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1# $NetBSD: Makefile,v 1.286 2009/08/03 22:16:01 wiz Exp $ 1# $NetBSD: Makefile,v 1.287 2009/08/03 23:03:05 rmind Exp $
2 2
3# Makefile for section 9 (kernel function and variable) manual pages. 3# Makefile for section 9 (kernel function and variable) manual pages.
4 4
5MAN= accept_filter.9 accf_data.9 accf_http.9 \ 5MAN= accept_filter.9 accf_data.9 accf_http.9 \
6 altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \ 6 altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \
7 bcdtobin.9 bcmp.9 bcopy.9 bluetooth.9 bzero.9 \ 7 bcdtobin.9 bcmp.9 bcopy.9 bluetooth.9 bzero.9 \
8 buffercache.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \ 8 buffercache.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \
9 callout.9 cardbus.9 cnmagic.9 condvar.9 config.9 cons.9 copy.9 \ 9 callout.9 cardbus.9 cnmagic.9 condvar.9 config.9 cons.9 copy.9 \
10 coredump_write.9 \ 10 coredump_write.9 \
11 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \ 11 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \
12 cpu_lwp_fork.9 \ 12 cpu_lwp_fork.9 \
13 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \ 13 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \
14 cpu_number.9 cpu_reboot.9 cpu_rootconf.9 \ 14 cpu_number.9 cpu_reboot.9 cpu_rootconf.9 \
@@ -46,29 +46,28 @@ MAN= accept_filter.9 accf_data.9 accf_ht @@ -46,29 +46,28 @@ MAN= accept_filter.9 accf_data.9 accf_ht
46 sched_4bsd.9 scsipi.9 \ 46 sched_4bsd.9 scsipi.9 \
47 secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \ 47 secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \
48 setjmp.9 shutdownhook_establish.9 \ 48 setjmp.9 shutdownhook_establish.9 \
49 signal.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \ 49 signal.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \
50 store.9 suspendsched.9 \ 50 store.9 suspendsched.9 \
51 sysctl.9 sysmon_envsys.9 tc.9 tcp_congctl.9 timecounter.9 \ 51 sysctl.9 sysmon_envsys.9 tc.9 tcp_congctl.9 timecounter.9 \
52 time_second.9 todr.9 tvtohz.9 uiomove.9 ucom.9 userret.9 \ 52 time_second.9 todr.9 tvtohz.9 uiomove.9 ucom.9 userret.9 \
53 vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \ 53 vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
54 video.9 vme.9 \ 54 video.9 vme.9 \
55 vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \ 55 vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
56 ubc.9 usbdi.9 uvm.9 \ 56 ubc.9 usbdi.9 uvm.9 \
57 vmem.9 vmem_alloc.9 vmem_create.9 vmem_destroy.9 vmem_free.9 \ 57 vmem.9 vmem_alloc.9 vmem_create.9 vmem_destroy.9 vmem_free.9 \
58 vmem_xalloc.9 vmem_xfree.9 \ 58 vmem_xalloc.9 vmem_xfree.9 \
59 wdc.9 \ 59 wdc.9 workqueue.9 \
60 workqueue.9 workqueue_create.9 workqueue_destroy.9 \ 60 wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9
61 workqueue_enqueue.9 wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 
62 61
63MAN+= dmover.9 62MAN+= dmover.9
64MLINKS+=dmover.9 dmover_backend_register.9 \ 63MLINKS+=dmover.9 dmover_backend_register.9 \
65 dmover.9 dmover_backend_unregister.9 \ 64 dmover.9 dmover_backend_unregister.9 \
66 dmover.9 dmover_session_create.9 \ 65 dmover.9 dmover_session_create.9 \
67 dmover.9 dmover_session_destroy.9 \ 66 dmover.9 dmover_session_destroy.9 \
68 dmover.9 dmover_request_alloc.9 \ 67 dmover.9 dmover_request_alloc.9 \
69 dmover.9 dmover_request_free.9 \ 68 dmover.9 dmover_request_free.9 \
70 dmover.9 dmover_process.9 \ 69 dmover.9 dmover_process.9 \
71 dmover.9 dmover_done.9 70 dmover.9 dmover_done.9
72 71
73MAN+= KASSERT.9 72MAN+= KASSERT.9
74MLINKS+=KASSERT.9 KDASSERT.9 73MLINKS+=KASSERT.9 KDASSERT.9
@@ -800,26 +799,29 @@ MLINKS+=vnfileops.9 vn_closefile.9 \ @@ -800,26 +799,29 @@ MLINKS+=vnfileops.9 vn_closefile.9 \
800MLINKS+=vnsubr.9 vn_bwrite.9 \ 799MLINKS+=vnsubr.9 vn_bwrite.9 \
801 vnsubr.9 vn_close.9 \ 800 vnsubr.9 vn_close.9 \
802 vnsubr.9 vn_default_error.9 \ 801 vnsubr.9 vn_default_error.9 \
803 vnsubr.9 vn_isunder.9 \ 802 vnsubr.9 vn_isunder.9 \
804 vnsubr.9 vn_lock.9 \ 803 vnsubr.9 vn_lock.9 \
805 vnsubr.9 vn_markexec.9 \ 804 vnsubr.9 vn_markexec.9 \
806 vnsubr.9 vn_marktext.9 \ 805 vnsubr.9 vn_marktext.9 \
807 vnsubr.9 vn_restorerecurse.9 \ 806 vnsubr.9 vn_restorerecurse.9 \
808 vnsubr.9 vn_rdwr.9 \ 807 vnsubr.9 vn_rdwr.9 \
809 vnsubr.9 vn_setrecurse.9 \ 808 vnsubr.9 vn_setrecurse.9 \
810 vnsubr.9 vn_stat.9 \ 809 vnsubr.9 vn_stat.9 \
811 vnsubr.9 vn_open.9 \ 810 vnsubr.9 vn_open.9 \
812 vnsubr.9 vn_writechk.9 811 vnsubr.9 vn_writechk.9
 812MLINKS+=workqueue.9 workqueue_create.9 \
 813 workqueue.9 workqueue_enqueue.9 \
 814 workqueue.9 workqueue_destroy.9
813MLINKS+=wsdisplay.9 wsdisplay_switchtoconsole.9 \ 815MLINKS+=wsdisplay.9 wsdisplay_switchtoconsole.9 \
814 wsdisplay.9 wsdisplay_cnattach.9 \ 816 wsdisplay.9 wsdisplay_cnattach.9 \
815 wsdisplay.9 wsdisplaydevprint.9 \ 817 wsdisplay.9 wsdisplaydevprint.9 \
816 wsdisplay.9 wsemuldisplaydevprint.9 818 wsdisplay.9 wsemuldisplaydevprint.9
817MLINKS+=wsfont.9 wsfont_init.9 \ 819MLINKS+=wsfont.9 wsfont_init.9 \
818 wsfont.9 wsfont_matches.9 \ 820 wsfont.9 wsfont_matches.9 \
819 wsfont.9 wsfont_find.9 \ 821 wsfont.9 wsfont_find.9 \
820 wsfont.9 wsfont_add.9 \ 822 wsfont.9 wsfont_add.9 \
821 wsfont.9 wsfont_remove.9 \ 823 wsfont.9 wsfont_remove.9 \
822 wsfont.9 wsfont_enum.9 \ 824 wsfont.9 wsfont_enum.9 \
823 wsfont.9 wsfont_lock.9 \ 825 wsfont.9 wsfont_lock.9 \
824 wsfont.9 wsfont_unlock.9 \ 826 wsfont.9 wsfont_unlock.9 \
825 wsfont.9 wsfont_getflg.9 \ 827 wsfont.9 wsfont_getflg.9 \
cvs diff -r1.5 -r1.6 src/share/man/man9/workqueue.9 (expand / switch to unified diff)

--- src/share/man/man9/workqueue.9 2007/07/14 10:52:49 1.5
+++ src/share/man/man9/workqueue.9 2009/08/03 23:03:05 1.6
@@ -1,61 +1,147 @@ @@ -1,61 +1,147 @@
1.\" $NetBSD: workqueue.9,v 1.5 2007/07/14 10:52:49 ad Exp $ 1.\" $NetBSD: workqueue.9,v 1.6 2009/08/03 23:03:05 rmind Exp $
2.\" 2.\"
3.\" Copyright (c)2005 YAMAMOTO Takashi, 3.\" Copyright (c)2005 YAMAMOTO Takashi,
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE. 25.\" SUCH DAMAGE.
26.\" 26.\"
27.\" ------------------------------------------------------------ 27.\" ------------------------------------------------------------
28.Dd September 15, 2006 28.Dd August 3, 2009
29.Dt WORKQUEUE 9 29.Dt WORKQUEUE 9
30.Os 30.Os
31.\" ------------------------------------------------------------ 31.\" ------------------------------------------------------------
32.Sh NAME 32.Sh NAME
33.Nm workqueue 33.Nm workqueue
34.Nd simple do-it-in-thread-context framework 34.Nd simple do-it-in-thread-context framework
35.\" ------------------------------------------------------------ 35.\" ------------------------------------------------------------
 36.Sh SYNOPSIS
 37.In sys/workqueue.h
 38.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 39.Ft int
 40.Fn workqueue_create \
 41"struct workqueue **wqp" "const char *name" \
 42"void (*func)(struct work *, void *)" "void *arg" \
 43"pri_t prio" "int ipl" "int flags"
 44.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 45.Ft void
 46.Fn workqueue_enqueue \
 47"struct workqueue *wq" "struct work *wk" "struct cpu_info *ci"
 48.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 49.Ft void
 50.Fn workqueue_destroy \
 51"struct workqueue *wq"
 52.\" ------------------------------------------------------------
36.Sh DESCRIPTION 53.Sh DESCRIPTION
37The 54The
38.Nm 55.Nm
39utility routines are provided to defer work which is needed to be 56utility routines are provided to defer work which is needed to be
40processed in a thread context. 57processed in a thread context.
 58.Pp
 59.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 60.Fn workqueue_create
 61creates a workqueue.
 62It takes the following arguments:
 63.Bl -tag -width flags
 64.It Fa wqp
 65Specify where to store the created workqueue.
 66.It Fa name
 67The name of the workqueue.
 68.It Fa func
 69The function to be called for each
 70.Fa work .
 71.It Fa arg
 72An argument to be passed as a second argument of
 73.Fa func .
 74.It Fa prio
 75The process priority to be used when sleeping to wait requests.
 76.It Fa ipl
 77The highest IPL at which this workqueue is used.
 78.It Fa flags
 79The value of 0 indicates a standard create operation, however the following
 80flags may be bitwise ORed together:
 81.Bl -tag -width WQ_MPSAFE
 82.It Dv WQ_MPSAFE
 83Specifies that the workqueue is multiprocessor safe and does its own locking,
 84otherwise the kernel lock will be held while work will be processed.
 85.It Dv WQ_PERCPU
 86Specifies that the workqueue should have a separate queue for each CPU,
 87thus the work could be enqueued on concrete CPUs.
 88.El
 89.El
 90.Pp
 91.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 92.Fn workqueue_enqueue
 93enqueues the work
 94.Fa wk
 95into the workqueue
 96.Fa wq .
 97.Pp
 98If the
 99.Dv WQ_PERCPU
 100flag was set on workqueue creation, the
 101.Fa ci
 102argument may be used to specify the CPU on which the work should
 103be enqueued.
 104Also it may be
 105.Dv NULL ,
 106then work will be enqueued on the current CPU.
 107If
 108.Dv WQ_PERCPU
 109flag was not set,
 110.Fa ci
 111must be
 112.Dv NULL .
 113.Pp
 114The enqueued work will be processed in a thread context.
 115A work must not be enqueued again until the callback is called by
 116the
 117.Xr workqueue 9
 118framework.
 119.Pp
 120.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 121.Fn workqueue_destroy
 122destroys a workqueue and frees associated resources.
 123The caller should ensure that the workqueue has no work enqueued beforehand.
 124.\" ------------------------------------------------------------
 125.Sh RETURN VALUES
 126.Fn workqueue_create
 127returns 0 on success.
 128Otherwise, it returns an
 129.Xr errno 2 .
41.\" ------------------------------------------------------------ 130.\" ------------------------------------------------------------
42.Sh CODE REFERENCES 131.Sh CODE REFERENCES
43This section describes places within the 132This section describes places within the
44.Nx 133.Nx
45source tree where actual code implementing the 134source tree where actual code implementing the
46.Nm 135.Nm
47subsystem 136subsystem
48can be found. 137can be found.
49All pathnames are relative to 138All pathnames are relative to
50.Pa /usr/src . 139.Pa /usr/src .
51.Pp 140.Pp
52The 141The
53.Nm 142.Nm
54subsystem is implemented within the file 143subsystem is implemented within the file
55.Pa sys/kern/subr_workqueue.c . 144.Pa sys/kern/subr_workqueue.c .
56.\" ------------------------------------------------------------ 145.\" ------------------------------------------------------------
57.Sh SEE ALSO 146.Sh SEE ALSO
58.Xr intro 9 , 147.Xr intro 9
59.Xr workqueue_create 9 , 
60.Xr workqueue_destroy 9 , 
61.Xr workqueue_enqueue 9 
File Deleted: src/share/man/man9/Attic/workqueue_create.9
File Deleted: src/share/man/man9/Attic/workqueue_destroy.9
File Deleted: src/share/man/man9/Attic/workqueue_enqueue.9