Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add callback(9) man page. Reviewed and improved by <wiz>, thanks!

Browse Source
This commit is contained in:
rmind 2009-10-05 23:44:10 +00:00
parent ac8f63538a
commit 43533de20b
3 changed files with 146 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
distrib/sets/lists/comp/mi
View File

@ -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

9
share/man/man9/Makefile
View File

@ -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 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \
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 @@ MLINKS+=byteorder.9 bswap16.9 byteorder.9 bswap32.9 byteorder.9 bswap64.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 \

121
share/man/man9/callback.9 Normal file
View File

@ -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