share/man/man9/callback.9

   1 .\"     $NetBSD: callback.9,v 1.3 2009/10/28 18:20:41 njoly 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
  48 The generic
  49 .Nm callback
  50 interface allows lower-level layer code to execute a registered function,
  51 or set of functions, from the higher-level layer.
  52 .Pp
  53 Registered functions must return one of these constants:
  54 .Bl -tag -width Dv
  55 .It Dv CALLBACK_CHAIN_CONTINUE
  56 Indicates that the function call was successful.
  57 The following functions in the chain will be called.
  58 .It Dv CALLBACK_CHAIN_ABORT
  59 Indicates a failure case in the function call.
  60 Any following functions in the chain will not be executed.
  61 .El
  62 .Sh FUNCTIONS
  63 The callback structure
  64 .Vt callback_head
  65 should be initialized and destroyed using the functions described below.
  66 This structure contains the list of callback entries and other internal data.
  67 .Pp
  68 The
  69 .Vt callback_entry
  70 structure is an entry, normally associated with the higher-level object.
  71 It contains the internal data of the callback interface.
  72 .Bl -tag -width compact
  73 .It Fn callback_head_init "ch" "ipl"
  74 Initialize the callback structure specified by
  75 .Fa ch .
  76 The highest IPL at which this callback can be used is specified by
  77 .Fa ipl .
  78 .It Fn callback_head_destroy "ch"
  79 Destroy the callback structure specified by
  80 .Fa ch .
  81 The caller must unregister all functions before destroying the callback structure.
  82 .It Fn callback_register "ch" "ce" "obj" "fn"
  83 Register the callback function in the callback structure specified by
  84 .Fa ch .
  85 .Fa ce
  86 should point to the entry structure of the callback object.
  87 The callback object itself is specified by
  88 .Fa obj .
  89 The function pointer is specified by
  90 .Fa fn .
  91 .It Fn callback_unregister "ch" "ce"
  92 Unregister the callback function from the structure specified by
  93 .Fa ch .
  94 The entry should be passed as
  95 .Fa ce .
  96 This function may block.
  97 .It Fn callback_run_roundrobin "ch" "arg"
  98 Executes all functions registered in the callback
  99 structure, specified by
 100 .Fa ch .
 101 The functions are executed in round-robin fashion.
 102 The value of
 103 .Fa arg
 104 will be passed to the callback functions.
 105 .El
 106 .Sh CODE REFERENCES
 107 This section describes places within the
 108 .Nx
 109 source tree where actual code implementing the
 110 .Nm
 111 interface can be found.
 112 All pathnames are relative to
 113 .Pa /usr/src .
 114 .Pp
 115 The
 116 .Nm
 117 interface is implemented within the file
 118 .Pa sys/kern/subr_callback.c .
 119 .Sh SEE ALSO
 120 .Xr intro 9