1.\" 2.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd July 23, 2021 26.Dt G_EVENT 9 27.Os 28.Sh NAME 29.Nm g_post_event , 30.Nm g_waitfor_event , 31.Nm g_cancel_event 32.Nd "GEOM events management" 33.Sh SYNOPSIS 34.In geom/geom.h 35.Ft int 36.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ... 37.Ft int 38.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ... 39.Ft void 40.Fn g_cancel_event "void *ref" 41.Ft "struct g_event *" 42.Fn g_alloc_event "int flag" 43.Ft void 44.Fn g_post_event_ep "g_event_t *func" "void *arg" "struct g_event *ep" ... 45.Sh DESCRIPTION 46The GEOM framework has its own event queue to inform classes about important 47events. 48The event queue can be also used by GEOM classes themselves, for example 49to work around some restrictions in the I/O path, where sleeping, heavy weight 50tasks, etc.\& are not permitted. 51.Pp 52The 53.Fn g_post_event 54function tells the GEOM framework to call function 55.Fa func 56with argument 57.Fa arg 58from the event queue. 59The 60.Fa flag 61argument is passed to 62.Xr malloc 9 63for memory allocations inside of 64.Fn g_post_event . 65The only allowed flags are 66.Dv M_WAITOK 67and 68.Dv M_NOWAIT . 69The rest of the arguments are used as references to identify the event. 70An event can be canceled by using any of the given references as an 71argument to 72.Fn g_cancel_event . 73The list of references has to end with a 74.Dv NULL 75value. 76.Pp 77The 78.Fn g_waitfor_event 79function is a blocking version of the 80.Fn g_post_event 81function. 82It waits until the event is finished or canceled and then returns. 83.Pp 84The 85.Fn g_post_event_ep 86function posts the event with a pre-allocated 87.Va struct g_event . 88An event may be pre-allocated with 89.Fn g_alloc_event . 90.Pp 91The 92.Fn g_cancel_event 93function cancels all event(s) identified by 94.Fa ref . 95Cancellation is equivalent to calling the requested function 96with requested arguments and argument 97.Fa flag 98set to 99.Dv EV_CANCEL . 100.Sh RESTRICTIONS/CONDITIONS 101.Fn g_post_event : 102.Bl -item -offset indent 103.It 104The argument 105.Fa flag 106has to be 107.Dv M_WAITOK 108or 109.Dv M_NOWAIT . 110.It 111The list of references has to end with a 112.Dv NULL 113value. 114.El 115.Pp 116.Fn g_waitfor_event : 117.Bl -item -offset indent 118.It 119The argument 120.Fa flag 121has to be 122.Dv M_WAITOK 123or 124.Dv M_NOWAIT . 125.It 126The list of references has to end with a 127.Dv NULL 128value. 129.It 130The 131.Fn g_waitfor_event 132function cannot be called from an event, since doing so would result 133in a deadlock. 134.El 135.Pp 136.Fn g_alloc_event : 137.Bl -item -offset indent 138.It 139The argument 140.Fa flag 141has to be 142.Dv M_WAITOK 143or 144.Dv M_NOWAIT . 145.It 146The returned 147.Va struct g_event * 148must be freed with 149.Fn g_free 150if 151.Fn g_post_event_ep 152is not called. 153.El 154.Sh RETURN VALUES 155The 156.Fn g_post_event 157and 158.Fn g_waitfor_event 159functions 160return 0 if successful; otherwise an error code is returned. 161.Sh EXAMPLES 162Example of a function called from the event queue. 163.Bd -literal -offset indent 164void 165example_event(void *arg, int flag) 166{ 167 168 if (flag == EV_CANCEL) { 169 printf("Event with argument %p canceled.\\n", arg); 170 return; 171 } 172 173 printf("Event with argument %p called.\\n", arg); 174} 175.Ed 176.Sh ERRORS 177Possible errors for the 178.Fn g_post_event 179function: 180.Bl -tag -width Er 181.It Bq Er ENOMEM 182The 183.Fa flag 184argument was set to 185.Dv M_NOWAIT 186and there was insufficient memory. 187.El 188.Pp 189Possible errors for the 190.Fn g_waitfor_event 191function: 192.Bl -tag -width Er 193.It Bq Er EAGAIN 194The event was canceled. 195.It Bq Er ENOMEM 196The 197.Fa flag 198argument was set to 199.Dv M_NOWAIT 200and there was insufficient memory. 201.El 202.Sh SEE ALSO 203.Xr geom 4 , 204.Xr DECLARE_GEOM_CLASS 9 , 205.Xr g_access 9 , 206.Xr g_attach 9 , 207.Xr g_bio 9 , 208.Xr g_consumer 9 , 209.Xr g_data 9 , 210.Xr g_geom 9 , 211.Xr g_provider 9 , 212.Xr g_provider_by_name 9 , 213.Xr g_wither_geom 9 214.Sh AUTHORS 215.An -nosplit 216This manual page was written by 217.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . 218