mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 02:37:15 +00:00
290 lines
8.4 KiB
Groff
290 lines
8.4 KiB
Groff
.\" Copyright (c) 2004 Joseph Koshy
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd October 7, 2022
|
|
.Dt EVENTHANDLER 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm EVENTHANDLER
|
|
.Nd kernel event handling functions
|
|
.Sh SYNOPSIS
|
|
.In sys/eventhandler.h
|
|
.Fn EVENTHANDLER_DECLARE name type
|
|
.Fn EVENTHANDLER_DEFINE name func arg priority
|
|
.Fn EVENTHANDLER_INVOKE name ...
|
|
.Ft eventhandler_tag
|
|
.Fn EVENTHANDLER_REGISTER name func arg priority
|
|
.Fn EVENTHANDLER_DEREGISTER name tag
|
|
.Fn EVENTHANDLER_DEREGISTER_NOWAIT name tag
|
|
.Fn EVENTHANDLER_LIST_DECLARE name
|
|
.Fn EVENTHANDLER_LIST_DEFINE name
|
|
.Fn EVENTHANDLER_DIRECT_INVOKE name
|
|
.Ft eventhandler_tag
|
|
.Fo eventhandler_register
|
|
.Fa "struct eventhandler_list *list"
|
|
.Fa "const char *name"
|
|
.Fa "void *func"
|
|
.Fa "void *arg"
|
|
.Fa "int priority"
|
|
.Fc
|
|
.Ft void
|
|
.Fo eventhandler_deregister
|
|
.Fa "struct eventhandler_list *list"
|
|
.Fa "eventhandler_tag tag"
|
|
.Fc
|
|
.Ft void
|
|
.Fo eventhandler_deregister_nowait
|
|
.Fa "struct eventhandler_list *list"
|
|
.Fa "eventhandler_tag tag"
|
|
.Fc
|
|
.Ft "struct eventhandler_list *"
|
|
.Fn eventhandler_find_list "const char *name"
|
|
.Ft void
|
|
.Fn eventhandler_prune_list "struct eventhandler_list *list"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
mechanism provides a way for kernel subsystems to register interest in
|
|
kernel events and have their callback functions invoked when these
|
|
events occur.
|
|
.Pp
|
|
Callback functions are invoked in order of priority.
|
|
The relative priority of each callback among other callbacks
|
|
associated with an event is given by argument
|
|
.Fa priority ,
|
|
which is an integer ranging from
|
|
.Dv EVENTHANDLER_PRI_FIRST
|
|
(highest priority), to
|
|
.Dv EVENTHANDLER_PRI_LAST
|
|
(lowest priority).
|
|
The symbol
|
|
.Dv EVENTHANDLER_PRI_ANY
|
|
may be used if the handler does not have a specific priority
|
|
associated with it.
|
|
.Pp
|
|
The normal way to use this subsystem is via the macro interface.
|
|
For events that are high frequency it is suggested that you additionally use
|
|
.Fn EVENTHANDLER_LIST_DEFINE
|
|
so that the event handlers can be invoked directly using
|
|
.Fn EVENTHANDLER_DIRECT_INVOKE
|
|
(see below).
|
|
This saves the invoker from having to do a locked traversal of a global
|
|
list of event handler lists.
|
|
.Bl -tag -width indent
|
|
.It Fn EVENTHANDLER_DECLARE
|
|
This macro declares an event handler named by argument
|
|
.Fa name
|
|
with callback functions of type
|
|
.Fa type .
|
|
.It Fn EVENTHANDLER_DEFINE
|
|
This macro uses
|
|
.Xr SYSINIT 9
|
|
to register a callback function
|
|
.Fa func
|
|
with event handler
|
|
.Fa name .
|
|
When invoked, function
|
|
.Fa func
|
|
will be invoked with argument
|
|
.Fa arg
|
|
as its first parameter along with any additional parameters passed in
|
|
via macro
|
|
.Fn EVENTHANDLER_INVOKE
|
|
(see below).
|
|
.It Fn EVENTHANDLER_REGISTER
|
|
This macro registers a callback function
|
|
.Fa func
|
|
with event handler
|
|
.Fa name .
|
|
When invoked, function
|
|
.Fa func
|
|
will be invoked with argument
|
|
.Fa arg
|
|
as its first parameter along with any additional parameters passed in
|
|
via macro
|
|
.Fn EVENTHANDLER_INVOKE
|
|
(see below).
|
|
If registration is successful,
|
|
.Fn EVENTHANDLER_REGISTER
|
|
returns a cookie of type
|
|
.Vt eventhandler_tag .
|
|
.It Fn EVENTHANDLER_DEREGISTER
|
|
This macro removes a previously registered callback associated with tag
|
|
.Fa tag
|
|
from the event handler named by argument
|
|
.Fa name .
|
|
It waits until no threads are running handlers for this event before
|
|
returning, making it safe to unload a module immediately upon return
|
|
from this function.
|
|
.It Fn EVENTHANDLER_DEREGISTER_NOWAIT
|
|
This macro removes a previously registered callback associated with tag
|
|
.Fa tag
|
|
from the event handler named by argument
|
|
.Fa name .
|
|
Upon return, one or more threads could still be running the removed
|
|
function(s), but no new calls will be made.
|
|
To remove a handler function from within that function, use this
|
|
version of deregister, to avoid a deadlock.
|
|
.It Fn EVENTHANDLER_INVOKE
|
|
This macro is used to invoke all the callbacks associated with event
|
|
handler
|
|
.Fa name .
|
|
This macro is a variadic one.
|
|
Additional arguments to the macro after the
|
|
.Fa name
|
|
parameter are passed as the second and subsequent arguments to each
|
|
registered callback function.
|
|
.It Fn EVENTHANDLER_LIST_DEFINE
|
|
This macro defines a reference to an event handler list named by
|
|
argument
|
|
.Fa name .
|
|
It uses
|
|
.Xr SYSINIT 9
|
|
to initialize the reference and the eventhandler list.
|
|
.It Fn EVENTHANDLER_LIST_DECLARE
|
|
This macro declares an event handler list named by argument
|
|
.Fa name .
|
|
This is only needed for users of
|
|
.Fn EVENTHANDLER_DIRECT_INVOKE
|
|
which are not in the same compilation unit of that list's definition.
|
|
.It Fn EVENTHANDLER_DIRECT_INVOKE
|
|
This macro invokes the event handlers registered for the list named by
|
|
argument
|
|
.Fa name .
|
|
This macro can only be used if the list was defined with
|
|
.Fn EVENTHANDLER_LIST_DEFINE .
|
|
The macro is variadic with the same semantics as
|
|
.Fn EVENTHANDLER_INVOKE .
|
|
.El
|
|
.Pp
|
|
The macros are implemented using the following functions:
|
|
.Bl -tag -width indent
|
|
.It Fn eventhandler_register
|
|
The
|
|
.Fn eventhandler_register
|
|
function is used to register a callback with a given event.
|
|
The arguments expected by this function are:
|
|
.Bl -tag -width ".Fa priority"
|
|
.It Fa list
|
|
A pointer to an existing event handler list, or
|
|
.Dv NULL .
|
|
If
|
|
.Fa list
|
|
is
|
|
.Dv NULL ,
|
|
the event handler list corresponding to argument
|
|
.Fa name
|
|
is used.
|
|
.It Fa name
|
|
The name of the event handler list.
|
|
.It Fa func
|
|
A pointer to a callback function.
|
|
Argument
|
|
.Fa arg
|
|
is passed to the callback function
|
|
.Fa func
|
|
as its first argument when it is invoked.
|
|
.It Fa priority
|
|
The relative priority of this callback among all the callbacks
|
|
registered for this event.
|
|
Valid values are those in the range
|
|
.Dv EVENTHANDLER_PRI_FIRST
|
|
to
|
|
.Dv EVENTHANDLER_PRI_LAST .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn eventhandler_register
|
|
function returns a
|
|
.Fa tag
|
|
that can later be used with
|
|
.Fn eventhandler_deregister
|
|
to remove the particular callback function.
|
|
.It Fn eventhandler_deregister
|
|
The
|
|
.Fn eventhandler_deregister
|
|
function removes the callback associated with tag
|
|
.Fa tag
|
|
from the event handler list pointed to by
|
|
.Fa list .
|
|
If
|
|
.Fa tag
|
|
is
|
|
.Va NULL ,
|
|
all callback functions for the event are removed.
|
|
This function will not return until all threads have exited from the
|
|
removed handler callback function(s).
|
|
This function is not safe to call from inside an event handler callback.
|
|
.It Fn eventhandler_deregister_nowait
|
|
The
|
|
.Fn eventhandler_deregister
|
|
function removes the callback associated with tag
|
|
.Fa tag
|
|
from the event handler list pointed to by
|
|
.Fa list .
|
|
This function is safe to call from inside an event handler
|
|
callback.
|
|
.It Fn eventhandler_find_list
|
|
The
|
|
.Fn eventhandler_find_list
|
|
function returns a pointer to event handler list structure corresponding
|
|
to event
|
|
.Fa name .
|
|
.It Fn eventhandler_prune_list
|
|
The
|
|
.Fn eventhandler_prune_list
|
|
function removes all deregistered callbacks from the event list
|
|
.Fa list .
|
|
.El
|
|
.Sh RETURN VALUES
|
|
The macro
|
|
.Fn EVENTHANDLER_REGISTER
|
|
and function
|
|
.Fn eventhandler_register
|
|
return a cookie of type
|
|
.Vt eventhandler_tag ,
|
|
which may be used in a subsequent call to
|
|
.Fn EVENTHANDLER_DEREGISTER
|
|
or
|
|
.Fn eventhandler_deregister .
|
|
.Pp
|
|
The
|
|
.Fn eventhandler_find_list
|
|
function
|
|
returns a pointer to an event handler list corresponding to parameter
|
|
.Fa name ,
|
|
or
|
|
.Dv NULL
|
|
if no such list was found.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
facility first appeared in
|
|
.Fx 4.0 .
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
|
|
and
|
|
.An Matt Joras Aq Mt mjoras@FreeBSD.org .
|