| EVENTHANDLER.9 (9df1bed3ca42c12e52a7cd7434315a76535982d8) | EVENTHANDLER.9 (48ef243364ab83df388e72b73b253a73ae55131e) |
|---|---|
| 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 unchanged lines hidden (view full) --- 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.\" | 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 unchanged lines hidden (view full) --- 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 November 23, 2004 | 26.Dd January 7, 2005 |
| 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 --- 21 unchanged lines hidden (view full) --- 56.Sh DESCRIPTION 57The 58.Nm 59mechanism provides a way for kernel subsystems to register interest in 60kernel events and have their callback functions invoked when these 61events occur. 62.Pp 63The normal way to use this subsystem is via the macro interface. | 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 --- 21 unchanged lines hidden (view full) --- 56.Sh DESCRIPTION 57The 58.Nm 59mechanism provides a way for kernel subsystems to register interest in 60kernel events and have their callback functions invoked when these 61events occur. 62.Pp 63The normal way to use this subsystem is via the macro interface. |
| 64.Pp 65The macro 66.Fn EVENTHANDLER_DECLARE 67declares an event handler named by argument | 64The macros that can be used for working with event handlers and callback 65function lists are: 66.Bl -tag -width indent 67.It Fn EVENTHANDLER_DECLARE 68This macro declares an event handler named by argument |
| 68.Fa name 69with callback functions of type 70.Fa type . | 69.Fa name 70with callback functions of type 71.Fa type . |
| 71.Pp 72The macro 73.Fn EVENTHANDLER_REGISTER 74registers a callback function | 72.It Fn EVENTHANDLER_REGISTER 73This macro registers a callback function |
| 75.Fa func 76with event handler 77.Fa name . 78When invoked, function 79.Fa func 80will be invoked with argument 81.Fa arg 82as its first parameter along with any additional parameters passed in 83via macro 84.Fn EVENTHANDLER_INVOKE 85(see below). 86Callback functions are invoked in order of priority. | 74.Fa func 75with event handler 76.Fa name . 77When invoked, function 78.Fa func 79will be invoked with argument 80.Fa arg 81as its first parameter along with any additional parameters passed in 82via macro 83.Fn EVENTHANDLER_INVOKE 84(see below). 85Callback functions are invoked in order of priority. |
| 87The relative priority of this callback among other callbacks 88associated with this event is given by argument | 86The relative priority of each callback among other callbacks 87associated with an event is given by argument |
| 89.Fa priority , 90which is an integer ranging from 91.Dv EVENTHANDLER_PRI_FIRST 92(highest priority), to 93.Dv EVENTHANDLER_PRI_LAST 94(lowest priority). 95The symbol 96.Dv EVENTHANDLER_PRI_ANY 97may be used if the handler does not have a specific priority 98associated with it. 99If registration is successful, 100.Fn EVENTHANDLER_REGISTER 101returns a cookie of type 102.Vt eventhandler_tag . | 88.Fa priority , 89which is an integer ranging from 90.Dv EVENTHANDLER_PRI_FIRST 91(highest priority), to 92.Dv EVENTHANDLER_PRI_LAST 93(lowest priority). 94The symbol 95.Dv EVENTHANDLER_PRI_ANY 96may be used if the handler does not have a specific priority 97associated with it. 98If registration is successful, 99.Fn EVENTHANDLER_REGISTER 100returns a cookie of type 101.Vt eventhandler_tag . |
| 103.Pp 104The macro 105.Fn EVENTHANDLER_DEREGISTER 106removes a previously registered callback associated with 107tag | 102.It Fn EVENTHANDLER_DEREGISTER 103This macro removes a previously registered callback associated with tag |
| 108.Fa tag 109from the event handler named by argument 110.Fa name . | 104.Fa tag 105from the event handler named by argument 106.Fa name . |
| 111.Pp 112The macro 113.Fn EVENTHANDLER_INVOKE 114is used to invoke all the callbacks associated with event handler | 107.It Fn EVENTHANDLER_INVOKE 108This macro is used to invoke all the callbacks associated with event 109handler |
| 115.Fa name . 116This macro is a variadic one. 117Additional arguments to the macro after the 118.Fa name 119parameter are passed as the second and subsequent arguments to each 120registered callback function. | 110.Fa name . 111This macro is a variadic one. 112Additional arguments to the macro after the 113.Fa name 114parameter are passed as the second and subsequent arguments to each 115registered callback function. |
| 116.El |
|
| 121.Pp 122The macros are implemented using the following functions: | 117.Pp 118The macros are implemented using the following functions: |
| 123.Pp 124The function | 119.Bl -tag -width indent 120.It Fn eventhandler_register 121The |
| 125.Fn eventhandler_register | 122.Fn eventhandler_register |
| 126is used to register a callback with a given event. 127The argument 128.Fa list 129is pointer to an existing event handler list, or | 123function is used to register a callback with a given event. 124The arguments expected by this function are: 125.Bl -tag -width ".Fa priority" 126.It Fa list 127A pointer to an existing event handler list, or |
| 130.Dv NULL . | 128.Dv NULL . |
| 131If argument | 129If |
| 132.Fa list 133is 134.Dv NULL , 135the event handler list corresponding to argument 136.Fa name 137is used. | 130.Fa list 131is 132.Dv NULL , 133the event handler list corresponding to argument 134.Fa name 135is used. |
| 136.It Fa name 137The name of the event handler list. 138.It Fa func 139A pointer to a callback function. |
|
| 138Argument | 140Argument |
| 139.Fa func 140is a pointer to a callback function. 141Argument | |
| 142.Fa arg | 141.Fa arg |
| 143is a passed in to callback function | 142is a passed to the callback function |
| 144.Fa func 145as its first argument when it is invoked. | 143.Fa func 144as its first argument when it is invoked. |
| 146Argument 147.Fa priority 148ranges from | 145.It Fa priority 146The relative priority of this callback among all the callbacks 147registered for this event. 148Valid values are those in the range |
| 149.Dv EVENTHANDLER_PRI_FIRST 150to | 149.Dv EVENTHANDLER_PRI_FIRST 150to |
| 151.Dv EVENTHANDLER_PRI_LAST , 152and determines the relative priority of this callback among all the 153callbacks registered for this event. | 151.Dv EVENTHANDLER_PRI_LAST . 152.El |
| 154.Pp | 153.Pp |
| 155Function | 154The 155.Fn eventhandler_register 156function returns a 157.Fa tag 158that can later be used with |
| 156.Fn eventhandler_deregister | 159.Fn eventhandler_deregister |
| 157removes the callback associated with tag | 160to remove the particular callback function. 161.It Fn eventhandler_deregister 162The 163.Fn eventhandler_deregister 164function removes the callback associated with tag |
| 158.Fa tag 159from the event handler list pointed to by 160.Fa list . 161This function is safe to call from inside an event handler 162callback. | 165.Fa tag 166from the event handler list pointed to by 167.Fa list . 168This function is safe to call from inside an event handler 169callback. |
| 163.Pp 164Function | 170.It Fn eventhandler_find_list 171The |
| 165.Fn eventhandler_find_list | 172.Fn eventhandler_find_list |
| 166returns a pointer to event handler list structure corresponding to 167event | 173function returns a pointer to event handler list structure corresponding 174to event |
| 168.Fa name . | 175.Fa name . |
| 169.Pp 170Function | 176.It Fn eventhandler_prune_list 177The |
| 171.Fn eventhandler_prune_list | 178.Fn eventhandler_prune_list |
| 172removes all deregistered callbacks from the event list | 179function removes all deregistered callbacks from the event list |
| 173.Fa list . | 180.Fa list . |
| 181.El |
|
| 174.Ss Kernel Event Handlers 175The following event handlers are present in the kernel: 176.Bl -tag -width indent 177.It Vt acpi_sleep_event 178Callbacks invoked when the system is being sent to sleep. 179.It Vt acpi_wakeup_event 180Callbacks invoked when the system is being woken up. 181.It Vt dev_clone --- 35 unchanged lines hidden (view full) --- 217.Fn eventhandler_register 218return a cookie of type 219.Vt eventhandler_tag , 220which may be used in a subsequent call to 221.Fn EVENTHANDLER_DEREGISTER 222or 223.Fn eventhandler_deregister . 224.Pp | 182.Ss Kernel Event Handlers 183The following event handlers are present in the kernel: 184.Bl -tag -width indent 185.It Vt acpi_sleep_event 186Callbacks invoked when the system is being sent to sleep. 187.It Vt acpi_wakeup_event 188Callbacks invoked when the system is being woken up. 189.It Vt dev_clone --- 35 unchanged lines hidden (view full) --- 225.Fn eventhandler_register 226return a cookie of type 227.Vt eventhandler_tag , 228which may be used in a subsequent call to 229.Fn EVENTHANDLER_DEREGISTER 230or 231.Fn eventhandler_deregister . 232.Pp |
| 225Function | 233The |
| 226.Fn eventhandler_find_list | 234.Fn eventhandler_find_list |
| 235function |
|
| 227returns a pointer to an event handler list corresponding to parameter 228.Fa name , 229or 230.Dv NULL 231if no such list was found. 232.Sh HISTORY 233The 234.Nm 235facility first appeared in 236.Fx 4.0 . 237.Sh AUTHORS 238This manual page was written by 239.An Joseph Koshy Aq jkoshy@FreeBSD.org . | 236returns a pointer to an event handler list corresponding to parameter 237.Fa name , 238or 239.Dv NULL 240if no such list was found. 241.Sh HISTORY 242The 243.Nm 244facility first appeared in 245.Fx 4.0 . 246.Sh AUTHORS 247This manual page was written by 248.An Joseph Koshy Aq jkoshy@FreeBSD.org . |