1.\" Copyright (c) 2004 Joseph Koshy 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" $FreeBSD$ 25.\" 26.Dd October 7, 2022 27.Dt EVENTHANDLER 9 28.Os 29.Sh NAME 30.Nm EVENTHANDLER 31.Nd kernel event handling functions 32.Sh SYNOPSIS 33.In sys/eventhandler.h 34.Fn EVENTHANDLER_DECLARE name type 35.Fn EVENTHANDLER_DEFINE name func arg priority 36.Fn EVENTHANDLER_INVOKE name ... 37.Ft eventhandler_tag 38.Fn EVENTHANDLER_REGISTER name func arg priority 39.Fn EVENTHANDLER_DEREGISTER name tag 40.Fn EVENTHANDLER_DEREGISTER_NOWAIT name tag 41.Fn EVENTHANDLER_LIST_DECLARE name 42.Fn EVENTHANDLER_LIST_DEFINE name 43.Fn EVENTHANDLER_DIRECT_INVOKE name 44.Ft eventhandler_tag 45.Fo eventhandler_register 46.Fa "struct eventhandler_list *list" 47.Fa "const char *name" 48.Fa "void *func" 49.Fa "void *arg" 50.Fa "int priority" 51.Fc 52.Ft void 53.Fo eventhandler_deregister 54.Fa "struct eventhandler_list *list" 55.Fa "eventhandler_tag tag" 56.Fc 57.Ft void 58.Fo eventhandler_deregister_nowait 59.Fa "struct eventhandler_list *list" 60.Fa "eventhandler_tag tag" 61.Fc 62.Ft "struct eventhandler_list *" 63.Fn eventhandler_find_list "const char *name" 64.Ft void 65.Fn eventhandler_prune_list "struct eventhandler_list *list" 66.Sh DESCRIPTION 67The 68.Nm 69mechanism provides a way for kernel subsystems to register interest in 70kernel events and have their callback functions invoked when these 71events occur. 72.Pp 73Callback functions are invoked in order of priority. 74The relative priority of each callback among other callbacks 75associated with an event is given by argument 76.Fa priority , 77which is an integer ranging from 78.Dv EVENTHANDLER_PRI_FIRST 79(highest priority), to 80.Dv EVENTHANDLER_PRI_LAST 81(lowest priority). 82The symbol 83.Dv EVENTHANDLER_PRI_ANY 84may be used if the handler does not have a specific priority 85associated with it. 86.Pp 87The normal way to use this subsystem is via the macro interface. 88For events that are high frequency it is suggested that you additionally use 89.Fn EVENTHANDLER_LIST_DEFINE 90so that the event handlers can be invoked directly using 91.Fn EVENTHANDLER_DIRECT_INVOKE 92(see below). 93This saves the invoker from having to do a locked traversal of a global 94list of event handler lists. 95.Bl -tag -width indent 96.It Fn EVENTHANDLER_DECLARE 97This macro declares an event handler named by argument 98.Fa name 99with callback functions of type 100.Fa type . 101.It Fn EVENTHANDLER_DEFINE 102This macro uses 103.Xr SYSINIT 9 104to register a callback function 105.Fa func 106with event handler 107.Fa name . 108When invoked, function 109.Fa func 110will be invoked with argument 111.Fa arg 112as its first parameter along with any additional parameters passed in 113via macro 114.Fn EVENTHANDLER_INVOKE 115(see below). 116.It Fn EVENTHANDLER_REGISTER 117This macro registers a callback function 118.Fa func 119with event handler 120.Fa name . 121When invoked, function 122.Fa func 123will be invoked with argument 124.Fa arg 125as its first parameter along with any additional parameters passed in 126via macro 127.Fn EVENTHANDLER_INVOKE 128(see below). 129If registration is successful, 130.Fn EVENTHANDLER_REGISTER 131returns a cookie of type 132.Vt eventhandler_tag . 133.It Fn EVENTHANDLER_DEREGISTER 134This macro removes a previously registered callback associated with tag 135.Fa tag 136from the event handler named by argument 137.Fa name . 138It waits until no threads are running handlers for this event before 139returning, making it safe to unload a module immediately upon return 140from this function. 141.It Fn EVENTHANDLER_DEREGISTER_NOWAIT 142This macro removes a previously registered callback associated with tag 143.Fa tag 144from the event handler named by argument 145.Fa name . 146Upon return, one or more threads could still be running the removed 147function(s), but no new calls will be made. 148To remove a handler function from within that function, use this 149version of deregister, to avoid a deadlock. 150.It Fn EVENTHANDLER_INVOKE 151This macro is used to invoke all the callbacks associated with event 152handler 153.Fa name . 154This macro is a variadic one. 155Additional arguments to the macro after the 156.Fa name 157parameter are passed as the second and subsequent arguments to each 158registered callback function. 159.It Fn EVENTHANDLER_LIST_DEFINE 160This macro defines a reference to an event handler list named by 161argument 162.Fa name . 163It uses 164.Xr SYSINIT 9 165to initialize the reference and the eventhandler list. 166.It Fn EVENTHANDLER_LIST_DECLARE 167This macro declares an event handler list named by argument 168.Fa name . 169This is only needed for users of 170.Fn EVENTHANDLER_DIRECT_INVOKE 171which are not in the same compilation unit of that list's definition. 172.It Fn EVENTHANDLER_DIRECT_INVOKE 173This macro invokes the event handlers registered for the list named by 174argument 175.Fa name . 176This macro can only be used if the list was defined with 177.Fn EVENTHANDLER_LIST_DEFINE . 178The macro is variadic with the same semantics as 179.Fn EVENTHANDLER_INVOKE . 180.El 181.Pp 182The macros are implemented using the following functions: 183.Bl -tag -width indent 184.It Fn eventhandler_register 185The 186.Fn eventhandler_register 187function is used to register a callback with a given event. 188The arguments expected by this function are: 189.Bl -tag -width ".Fa priority" 190.It Fa list 191A pointer to an existing event handler list, or 192.Dv NULL . 193If 194.Fa list 195is 196.Dv NULL , 197the event handler list corresponding to argument 198.Fa name 199is used. 200.It Fa name 201The name of the event handler list. 202.It Fa func 203A pointer to a callback function. 204Argument 205.Fa arg 206is passed to the callback function 207.Fa func 208as its first argument when it is invoked. 209.It Fa priority 210The relative priority of this callback among all the callbacks 211registered for this event. 212Valid values are those in the range 213.Dv EVENTHANDLER_PRI_FIRST 214to 215.Dv EVENTHANDLER_PRI_LAST . 216.El 217.Pp 218The 219.Fn eventhandler_register 220function returns a 221.Fa tag 222that can later be used with 223.Fn eventhandler_deregister 224to remove the particular callback function. 225.It Fn eventhandler_deregister 226The 227.Fn eventhandler_deregister 228function removes the callback associated with tag 229.Fa tag 230from the event handler list pointed to by 231.Fa list . 232If 233.Fa tag 234is 235.Va NULL , 236all callback functions for the event are removed. 237This function will not return until all threads have exited from the 238removed handler callback function(s). 239This function is not safe to call from inside an event handler callback. 240.It Fn eventhandler_deregister_nowait 241The 242.Fn eventhandler_deregister 243function removes the callback associated with tag 244.Fa tag 245from the event handler list pointed to by 246.Fa list . 247This function is safe to call from inside an event handler 248callback. 249.It Fn eventhandler_find_list 250The 251.Fn eventhandler_find_list 252function returns a pointer to event handler list structure corresponding 253to event 254.Fa name . 255.It Fn eventhandler_prune_list 256The 257.Fn eventhandler_prune_list 258function removes all deregistered callbacks from the event list 259.Fa list . 260.El 261.Sh RETURN VALUES 262The macro 263.Fn EVENTHANDLER_REGISTER 264and function 265.Fn eventhandler_register 266return a cookie of type 267.Vt eventhandler_tag , 268which may be used in a subsequent call to 269.Fn EVENTHANDLER_DEREGISTER 270or 271.Fn eventhandler_deregister . 272.Pp 273The 274.Fn eventhandler_find_list 275function 276returns a pointer to an event handler list corresponding to parameter 277.Fa name , 278or 279.Dv NULL 280if no such list was found. 281.Sh HISTORY 282The 283.Nm 284facility first appeared in 285.Fx 4.0 . 286.Sh AUTHORS 287This manual page was written by 288.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org 289and 290.An Matt Joras Aq Mt mjoras@FreeBSD.org . 291