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