From owner-freebsd-doc Mon Mar 4 6: 5:24 2002 Delivered-To: freebsd-doc@freebsd.org Received: from vagabond.auriga.ru (vagabond.auriga.ru [80.240.102.246]) by hub.freebsd.org (Postfix) with ESMTP id 7CAD037B416 for ; Mon, 4 Mar 2002 06:05:15 -0800 (PST) Received: from localhost (localhost [[UNIX: localhost]]) by vagabond.auriga.ru (8.11.2/8.11.2) id g24E5Dq12418 for freebsd-doc@freebsd.org; Mon, 4 Mar 2002 17:05:13 +0300 Content-Type: Multipart/Mixed; charset="koi8-r"; boundary="------------Boundary-00=_PGCGMP44UKTF1RZ6FEV6" From: "Alexey V. Neyman" To: freebsd-doc@freebsd.org Subject: please review proposed EVENTHANDLER(9) manpage Date: Mon, 4 Mar 2002 17:05:13 +0300 X-Mailer: KMail [version 1.2] MIME-Version: 1.0 Message-Id: <0203041705130D.22942@vagabond.auriga.ru> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org --------------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