Date: Mon, 4 Mar 2002 17:05:13 +0300 From: "Alexey V. Neyman" <alex.neyman@auriga.ru> To: freebsd-doc@freebsd.org Subject: please review proposed EVENTHANDLER(9) manpage Message-ID: <0203041705130D.22942@vagabond.auriga.ru>
next in thread | raw e-mail | index | archive | help
--------------Boundary-00=_PGCGMP44UKTF1RZ6FEV6
Content-Type: text/plain;
charset="koi8-r"
Content-Transfer-Encoding: 8bit
Hello there,
Thanks to Ruslan Ermilov for redirecting me to the right list.
Attached is a proposed EVENTHANDLER(9) manpage. (Copyright slightly
changed from the version posten on -hackers - as it was pointed to me,
I'd be copyright holder, not UCB :-)
If it looks OK, feel free to commit it.
Regards,
Alexey.
PS. Please Cc: me. I'm not subscribed to this list.
--
<------------------------->
) May the Sun and Water ( Regards, Alexey V. Neyman
) always fall upon you! ( mailto:alex.neyman@auriga.ru
<------------------------->
--------------Boundary-00=_PGCGMP44UKTF1RZ6FEV6
Content-Type: application/x-troff;
charset="koi8-r";
name="EVENTHANDLER.9"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="EVENTHANDLER.9"
.\" Copyright (c) 2002 Alexey Neyman
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
.\"
.\" $FreeBSD$
.\"
.Dd March 4, 2002
.Os
.Dt EVENTHANDLER 9
.Sh NAME
.Nm EVENTHANDLER_DECLARE ,
.Nm EVENTHANDLER_INVOKE ,
.Nm EVENTHANDLER_REGISTER ,
.Nm EVENTHANDLER_DEREGISTER ,
.Nm EVENTHANDLER_FAST_DECLARE ,
.Nm EVENTHANDLER_FAST_DEFINE ,
.Nm EVENTHANDLER_FAST_REGISTER ,
.Nm EVENTHANDLER_FAST_DEREGISTER ,
.Nm EVENTHANDLER_FAST_INVOKE
.Nd manage event callout queues
.Sh SYNOPSIS
.In sys/eventhandler.h
.Fn EVENTHANDLER_DECLARE "name" "type"
.Fn EVENTHANDLER_REGISTER "name" "func" "arg" "priority"
.Fn EVENTHANDLER_DEREGISTER "name" "tag"
.Fn EVENTHANDLER_INVOKE "name" "args..."
.Fn EVENTHANDLER_FAST_DECLARE "name" "type"
.Fn EVENTHANDLER_FAST_DEFINE "name" "type"
.Fn EVENTHANDLER_FAST_REGISTER "name" "func" "arg" "priority"
.Fn EVENTHANDLER_FAST_DEREGISTER "name" "tag"
.Fn EVENTHANDLER_FAST_INVOKE "name" "args..."
.Sh DESCRIPTION
These macros setup and execute callout queues for miscellaneous events in the
kernel.
They all accept the
.Fa name
argument, which serves as a unique identifier of the queue.
.Pp
The
.Fn EVENTHANDLER_DECLARE
macro declares a queue with given name and given type of the callout function.
The queues are allocated dynamically upon the first insertion with the
.Fn EVENTHANDLER_REGISTER
macro.
.Pp
The
.Fn EVENTHANDLER_REGISTER
macro inserts a new item in the specified list.
If the list does not exist, it is created.
This macro evaluates to eventhandler_tag value, which can be later used to
remove the handler from the queue with the
.Fn EVENTHANDLER_DEREGISTER
macro.
.Dv NULL
value is returned upon failure.
The
.Fa arg
parameter will always be passed as a first argument to callout function.
The
.Fa priority
argument defines the order of handler invocations.
.Pp
The
.Fn EVENTHANDLER_DEREGISTER
macro removes a handler from the queue, using the value returned by the
.Fn EVENTHANDLER_REGISTER
macro.
If
.Dv NULL
is passed as a second argument, all handlers will be removed from the
specified queue.
.Pp
The
.Fn EVENTHANDLER_INVOKE
macro calls each handler in the queue.
The first argument to the callout function is the argument specified with the
.Fn EVENTHANDLER_REGISTER
macro, subsequent arguments are passed through
.Fn EVENTHANDLER_INVOKE
invocation.
The handlers will be executed in order of increasing priority.
.Pp
The
.Fn EVENTHANDLER_FAST_XXX
macros are similar to their equivalents, but the queues are allocated
statically.
Thus the queue must be defined somewhere with the
.Fn EVENTHANDLER_FAST_DEFINE
macro.
This macro takes the same arguments as the
.Fn EVENTHANDLER_FAST_DECLARE
macro.
.Pp
Generally,
.Fn EVENTHANDLER_XXX
macros are preferred over
.Fn EVENTHANDLER_FAST_XXX
ones.
.Sh EXAMPLES
.Bd -literal
typedef void (*myhandler_fun)(void *, int);
eventhandler_tag et;
void myfunc(void *a, int b) {}
EVENTHANDLER_DECLARE(myqueue, myhandler_fun);
et = EVENTHANDLER_REGISTER(myqueue, myfunction, NULL, 0);
EVENTHANDLER_INVOKE(myqueue, 14);
EVENTHANDLER_DEREGISTER(myqueue, et);
.Ed
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Alexey Neyman Aq alex.neyman@auriga.ru .
--------------Boundary-00=_PGCGMP44UKTF1RZ6FEV6--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?0203041705130D.22942>