From owner-p4-projects@FreeBSD.ORG Sat Apr 7 12:41:28 2012 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 9860E1065673; Sat, 7 Apr 2012 12:41:28 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 5AFE9106564A for ; Sat, 7 Apr 2012 12:41:28 +0000 (UTC) (envelope-from jhb@freebsd.org) Received: from skunkworks.freebsd.org (skunkworks.freebsd.org [IPv6:2001:4f8:fff6::2d]) by mx1.freebsd.org (Postfix) with ESMTP id 43CFC8FC15 for ; Sat, 7 Apr 2012 12:41:28 +0000 (UTC) Received: from skunkworks.freebsd.org (localhost [127.0.0.1]) by skunkworks.freebsd.org (8.14.4/8.14.4) with ESMTP id q37CfS1C034811 for ; Sat, 7 Apr 2012 12:41:28 GMT (envelope-from jhb@freebsd.org) Received: (from perforce@localhost) by skunkworks.freebsd.org (8.14.4/8.14.4/Submit) id q37CfSZN034808 for perforce@freebsd.org; Sat, 7 Apr 2012 12:41:28 GMT (envelope-from jhb@freebsd.org) Date: Sat, 7 Apr 2012 12:41:28 GMT Message-Id: <201204071241.q37CfSZN034808@skunkworks.freebsd.org> X-Authentication-Warning: skunkworks.freebsd.org: perforce set sender to jhb@freebsd.org using -f From: John Baldwin To: Perforce Change Reviews Precedence: bulk Cc: Subject: PERFORCE change 209196 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 07 Apr 2012 12:41:28 -0000 http://p4web.freebsd.org/@@209196?ac=10 Change 209196 by jhb@jhb_fiver on 2012/04/07 12:40:55 Update. Affected files ... .. //depot/projects/smpng/share/man/man9/EVENTHANDLER.9#3 edit Differences ... ==== //depot/projects/smpng/share/man/man9/EVENTHANDLER.9#3 (text+ko) ==== @@ -36,10 +36,10 @@ .Fn EVENTHANDLER_FAST_DECLARE name type .Fn EVENTHANDLER_FAST_DEFINE name type .Fn EVENTHANDLER_FAST_INVOKE name ... -.Fn EVENTHANDLER_DEFINE name func arg priority .Ft eventhandler_tag .Fn EVENTHANDLER_REGISTER name func arg priority .Fn EVENTHANDLER_DEREGISTER name tag +.Fn EVENTHANDLER_DEFINE name func arg priority .Ft eventhandler_tag .Fo eventhandler_register .Fa "struct eventhandler_list *list" @@ -64,15 +64,63 @@ kernel events and have their callback functions invoked when these events occur. .Pp -The normal way to use this subsystem is via the macro interface. +Each event is associated with a named event handler list which contains +the associated callback functions. +There are two types of event handler lists: +normal lists and fast lists. +.Pp +Normal lists are more flexible at the expense of additional overhead. +These lists are allocated dynamically when the first callback +function is registered. +Invoking a normal event list always requires a linear lookup of the +list by name, +even if there are no callback functions registered for the event. +.Pp +Fast lists use static allocation rather than dynamic allocation. +This allows fast list invocations to avoid the lookup operation +and to minimize overhead if no callback functions are registered for +an event. +However, +the storage for fast lists must always be valid, +so they cannot be used in a kernel module that supports unloading. +In addition, +fast lists must be defined in exactly one place. +.Pp +This subsystem should be used via the macro interface. The macros that can be used for working with event handlers and callback function lists are: .Bl -tag -width indent .It Fn EVENTHANDLER_DECLARE -This macro declares an event handler named by argument +This macro declares a normal event handler named by argument +.Fa name +with callback functions of type +.Fa type . +.It Fn EVENTHANDLER_INVOKE +This macro is used to invoke all the callbacks associated with the +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_FAST_DECLARE +This macro declares a fast event handler named by argument .Fa name with callback functions of type .Fa type . +.It Fn EVENTHANDLER_FAST_DEFINE +This macro defines the storage for a fast event handler list and +registers the list with +.Fa name . +.It Fn EVENTHANDLER_FAST_INVOKE +This macro is used to invoke all the callbacks associated with the +fast event handler +.Fa name . +As with +.Fn EVENTHANDLER_INVOKE , +this macro is a variadic macro that passes additional arguments to +each registered callback function. .It Fn EVENTHANDLER_REGISTER This macro registers a callback function .Fa func @@ -82,10 +130,12 @@ .Fa func will be invoked with argument .Fa arg -as its first parameter along with any additional parameters passed in -via macro +as its first parameter along with any additional parameters passed to +the .Fn EVENTHANDLER_INVOKE -(see below). +or +.Fn EVENTHANDLER_FAST_INVOKE +macro. 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 @@ -108,15 +158,17 @@ .Fa tag from the event handler named by argument .Fa name . -.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_DEFINE +This macro is used to manage a static callback. +It registers a callback function via the +.Fn EVENTHANDLER_REGISTER +macro at system boot or module load. +Its arguments have the same meaning as for the +.Fn EVENTHANDLER_REGISTER +macro. +Additionally, +the callback function will be removed from the named event handler +list on module unload. .El .Pp The macros are implemented using the following functions: