1.\" $NetBSD: callback.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ 2.\" 3.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd October 28, 2009 28.Dt CALLBACK 9 29.Os 30.Sh NAME 31.Nm callback 32.Nd generic callback interface 33.Sh SYNOPSIS 34.In sys/callback.h 35.Ft void 36.Fn callback_head_init "struct callback_head *ch" "int ipl" 37.Ft void 38.Fn callback_head_destroy "struct callback_head *ch" 39.Ft void 40.Fn callback_register \ 41"struct callback_head *ch" "struct callback_entry *ce" "void *obj" \ 42"int (*fn)(struct callback_entry *, void *, void *)" 43.Ft void 44.Fn callback_unregister "struct callback_head *ch" "struct callback_entry *ce" 45.Ft int 46.Fn callback_run_roundrobin "struct callback_head *ch" "void *arg" 47.Sh DESCRIPTION 48The generic 49.Nm callback 50interface allows lower-level layer code to execute a registered function, 51or set of functions, from the higher-level layer. 52.Pp 53Registered functions must return one of these constants: 54.Bl -tag -width Dv 55.It Dv CALLBACK_CHAIN_CONTINUE 56Indicates that the function call was successful. 57The following functions in the chain will be called. 58.It Dv CALLBACK_CHAIN_ABORT 59Indicates a failure case in the function call. 60Any following functions in the chain will not be executed. 61.El 62.Sh FUNCTIONS 63The callback structure 64.Vt callback_head 65should be initialized and destroyed using the functions described below. 66This structure contains the list of callback entries and other internal data. 67.Pp 68The 69.Vt callback_entry 70structure is an entry, normally associated with the higher-level object. 71It contains the internal data of the callback interface. 72.Bl -tag -width compact 73.It Fn callback_head_init "ch" "ipl" 74Initialize the callback structure specified by 75.Fa ch . 76The highest IPL at which this callback can be used is specified by 77.Fa ipl . 78.It Fn callback_head_destroy "ch" 79Destroy the callback structure specified by 80.Fa ch . 81The caller must unregister all functions before destroying the callback structure. 82.It Fn callback_register "ch" "ce" "obj" "fn" 83Register the callback function in the callback structure specified by 84.Fa ch . 85.Fa ce 86should point to the entry structure of the callback object. 87The callback object itself is specified by 88.Fa obj . 89The function pointer is specified by 90.Fa fn . 91.It Fn callback_unregister "ch" "ce" 92Unregister the callback function from the structure specified by 93.Fa ch . 94The entry should be passed as 95.Fa ce . 96This function may block. 97.It Fn callback_run_roundrobin "ch" "arg" 98Executes all functions registered in the callback 99structure, specified by 100.Fa ch . 101The functions are executed in round-robin fashion. 102The value of 103.Fa arg 104will be passed to the callback functions. 105.El 106.Sh CODE REFERENCES 107The 108.Nm 109interface is implemented within the file 110.Pa sys/kern/subr_callback.c . 111.Sh SEE ALSO 112.Xr intro 9 113