Module Name: src
Committed By: rmind
Date: Mon Oct 5 23:44:10 UTC 2009
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: callback.9
Log Message:
Add callback(9) man page. Reviewed and improved by <wiz>, thanks!
To generate a diff of this commit:
cvs rdiff -u -r1.1318 -r1.1319 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.293 -r1.294 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/callback.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1318 src/distrib/sets/lists/comp/mi:1.1319
--- src/distrib/sets/lists/comp/mi:1.1318 Mon Oct 5 14:52:36 2009
+++ src/distrib/sets/lists/comp/mi Mon Oct 5 23:44:10 2009
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1318 2009/10/05 14:52:36 njoly Exp $
+# $NetBSD: mi,v 1.1319 2009/10/05 23:44:10 rmind Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -8392,6 +8392,12 @@
./usr/share/man/cat9/cache_purge.0 comp-sys-catman .cat
./usr/share/man/cat9/cache_purgevfs.0 comp-sys-catman .cat
./usr/share/man/cat9/cache_revlookup.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback_head_init.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback_head_destroy.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback_register.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback_run_roundrobin.0 comp-sys-catman .cat
+./usr/share/man/cat9/callback_unregister.0 comp-sys-catman .cat
./usr/share/man/cat9/callout.0 comp-sys-catman .cat
./usr/share/man/cat9/callout_ack.0 comp-sys-catman .cat
./usr/share/man/cat9/callout_active.0 comp-obsolete obsolete
@@ -13824,6 +13830,12 @@
./usr/share/man/html9/cache_purge.html comp-sys-htmlman html
./usr/share/man/html9/cache_purgevfs.html comp-sys-htmlman html
./usr/share/man/html9/cache_revlookup.html comp-sys-htmlman html
+./usr/share/man/html9/callback.html comp-sys-htmlman html
+./usr/share/man/html9/callback_head_init.html comp-sys-htmlman html
+./usr/share/man/html9/callback_head_destroy.html comp-sys-htmlman html
+./usr/share/man/html9/callback_register.html comp-sys-htmlman html
+./usr/share/man/html9/callback_run_roundrobin.html comp-sys-htmlman html
+./usr/share/man/html9/callback_unregister.html comp-sys-htmlman html
./usr/share/man/html9/callout.html comp-sys-htmlman html
./usr/share/man/html9/callout_ack.html comp-sys-htmlman html
./usr/share/man/html9/callout_destroy.html comp-sys-htmlman html
@@ -19367,6 +19379,12 @@
./usr/share/man/man9/cache_purge.9 comp-sys-man .man
./usr/share/man/man9/cache_purgevfs.9 comp-sys-man .man
./usr/share/man/man9/cache_revlookup.9 comp-sys-man .man
+./usr/share/man/man9/callback.9 comp-sys-man .man
+./usr/share/man/man9/callback_head_init.9 comp-sys-man .man
+./usr/share/man/man9/callback_head_destroy.9 comp-sys-man .man
+./usr/share/man/man9/callback_register.9 comp-sys-man .man
+./usr/share/man/man9/callback_run_roundrobin.9 comp-sys-man .man
+./usr/share/man/man9/callback_unregister.9 comp-sys-man .man
./usr/share/man/man9/callout.9 comp-sys-man .man
./usr/share/man/man9/callout_ack.9 comp-sys-man .man
./usr/share/man/man9/callout_active.9 comp-obsolete obsolete
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.293 src/share/man/man9/Makefile:1.294
--- src/share/man/man9/Makefile:1.293 Fri Oct 2 18:50:13 2009
+++ src/share/man/man9/Makefile Mon Oct 5 23:44:10 2009
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.293 2009/10/02 18:50:13 elad Exp $
+# $NetBSD: Makefile,v 1.294 2009/10/05 23:44:10 rmind Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -6,8 +6,8 @@
altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \
bcdtobin.9 bcmp.9 bcopy.9 bluetooth.9 boothowto.9 \
buffercache.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 bzero.9 \
- callout.9 cardbus.9 cnmagic.9 condvar.9 config.9 cons.9 copy.9 \
- coredump_write.9 \
+ callback.9 callout.9 cardbus.9 cnmagic.9 condvar.9 config.9 \
+ cons.9 copy.9 coredump_write.9 \
cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \
cpu_lwp_fork.9 \
cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \
@@ -159,6 +159,9 @@
byteorder.9 le16dec.9 byteorder.9 le32dec.9 byteorder.9 le64dec.9 \
byteorder.9 be16enc.9 byteorder.9 be32enc.9 byteorder.9 be64enc.9 \
byteorder.9 le16enc.9 byteorder.9 le32enc.9 byteorder.9 le64enc.9
+MLINKS+=callback.9 callback_head_init.9 callback.9 callback_head_destroy.9 \
+ callback.9 callback_register.9 callback.9 callback_unregister.9 \
+ callback.9 callback_run_roundrobin.9
MLINKS+=callout.9 callout_init.9 callout.9 callout_destroy.9 \
callout.9 callout_reset.9 callout.9 callout_schedule.9 \
callout.9 callout_setfunc.9 callout.9 callout_stop.9 \
Added files:
Index: src/share/man/man9/callback.9
diff -u /dev/null src/share/man/man9/callback.9:1.1
--- /dev/null Mon Oct 5 23:44:11 2009
+++ src/share/man/man9/callback.9 Mon Oct 5 23:44:10 2009
@@ -0,0 +1,121 @@
+.\" $NetBSD: callback.9,v 1.1 2009/10/05 23:44:10 rmind Exp $
+.\"
+.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd October 6, 2009
+.Dt CALLBACK 9
+.Os
+.Sh NAME
+.Nm callback
+.Nd generic callback interface
+.Sh SYNOPSIS
+.In sys/callback.h
+.Ft void
+.Fn callback_head_init "struct callback_head *ch" "int ipl"
+.Ft void
+.Fn callback_head_destroy "struct callback_head *ch"
+.Ft void
+.Fn callback_register \
+"struct callback_head *ch" "struct callback_entry *ce" "void *obj" \
+"int (*fn)(struct callback_entry *, void *, void *)"
+.Ft void
+.Fn callback_unregister "struct callback_head *ch" "struct callback_entry *ce"
+.Ft int
+.Fn callback_run_roundrobin "struct callback_head *ch" "void *arg"
+.Sh DESCRIPTION
+The generic
+.Nm callback
+interface allows lower-level layer code to execute a registered function,
+or set of functions, from the higher-level layer.
+.Pp
+Registered functions must return one of these constants:
+.Bl -tag -width Dv
+.It Dv CALLBACK_CHAIN_CONTINUE
+Indicates that the function call was successful.
+The following functions in the chain will be called.
+.It Dv CALLBACK_CHAIN_ABORT
+Indicates a failure case in the function call.
+Any following functions in the chain will not be executed.
+.El
+.Sh FUNCTIONS
+The callback structure
+.Vt callback_head
+should be initialized and destroyed using the functions described below.
+This structure contains the list of callback entries and other internal data.
+.Pp
+The
+.Vt callback_entry
+structure is an entry, normally associated with the higher-level object.
+It contains the internal data of the callback interface.
+.Bl -tag -width compact
+.It Fn callback_head_init "ch" "ipl"
+Initialize the callback structure specified by
+.Fa ch .
+The highest IPL at which this callback can be used is specified by
+.Fa ipl .
+.It Fn callback_head_destroy "ch"
+Destroy the callback structure specified by
+.Fa ch .
+The caller must unregister all functions before destroying the callback structure.
+.It Fn callback_register "ch" "ce" "obj" "fn"
+Register the callback function in the callback structure specified by
+.Fa ch .
+.Fa ce
+should point to the entry structure of the callback object.
+The callback object itself is specified by
+.Fa obj .
+The function pointer is specified by
+.Fa fn .
+.It Fn callback_unregister "ch" "ce"
+Unregister the callback function from the structure specified by
+.Fa ch .
+The entry should be passed as
+.Fa ce .
+This function may block.
+.It Fn callback_run_roundrobin "ch" "arg"
+Executes all functions registered in the callback
+structure, specified by
+.Fa ch .
+The functions are executed in round-robin fashion.
+The entry should be passed as
+.Fa ce .
+The value of
+.Fa arg
+will be passed to the callback functions.
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
+.Nm
+interface can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+interface is implemented within the file
+.Pa sys/kern/subr_callback.c .
+.Sh SEE ALSO
+.Xr intro 9
