xref: /freebsd/share/man/man9/EVENTHANDLER.9 (revision 058ac3e8063366dafa634d9107642e12b038bf09)
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