Return to callback.9 CVS log

Up to [cvs.NetBSD.org] / src / share / man / man9

Remove boilerplate in CODE REFERENCES on file paths.
Describe in intro(9) how to read paths in the CODE REFERENCES section.

.\"	$NetBSD: callback.9,v 1.5 2010/12/02 12:54:13 wiz 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 28, 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 value of
.Fa arg
will be passed to the callback functions.
.El
.Sh CODE REFERENCES
The
.Nm
interface is implemented within the file
.Pa sys/kern/subr_callback.c .
.Sh SEE ALSO
.Xr intro 9