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.\" $FreeBSD$ 26.\" 27.Dd July 23, 2021 28.Dt G_EVENT 9 29.Os 30.Sh NAME 31.Nm g_post_event , 32.Nm g_waitfor_event , 33.Nm g_cancel_event 34.Nd "GEOM events management" 35.Sh SYNOPSIS 36.In geom/geom.h 37.Ft int 38.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ... 39.Ft int 40.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ... 41.Ft void 42.Fn g_cancel_event "void *ref" 43.Ft "struct g_event *" 44.Fn g_alloc_event "int flag" 45.Ft void 46.Fn g_post_event_ep "g_event_t *func" "void *arg" "struct g_event *ep" ... 47.Sh DESCRIPTION 48The GEOM framework has its own event queue to inform classes about important 49events. 50The event queue can be also used by GEOM classes themselves, for example 51to work around some restrictions in the I/O path, where sleeping, heavy weight 52tasks, etc.\& are not permitted. 53.Pp 54The 55.Fn g_post_event 56function tells the GEOM framework to call function 57.Fa func 58with argument 59.Fa arg 60from the event queue. 61The 62.Fa flag 63argument is passed to 64.Xr malloc 9 65for memory allocations inside of 66.Fn g_post_event . 67The only allowed flags are 68.Dv M_WAITOK 69and 70.Dv M_NOWAIT . 71The rest of the arguments are used as references to identify the event. 72An event can be canceled by using any of the given references as an 73argument to 74.Fn g_cancel_event . 75The list of references has to end with a 76.Dv NULL 77value. 78.Pp 79The 80.Fn g_waitfor_event 81function is a blocking version of the 82.Fn g_post_event 83function. 84It waits until the event is finished or canceled and then returns. 85.Pp 86The 87.Fn g_post_event_ep 88function posts the event with a pre-allocated 89.Va struct g_event . 90An event may be pre-allocated with 91.Fn g_alloc_event . 92.Pp 93The 94.Fn g_cancel_event 95function cancels all event(s) identified by 96.Fa ref . 97Cancellation is equivalent to calling the requested function 98with requested arguments and argument 99.Fa flag 100set to 101.Dv EV_CANCEL . 102.Sh RESTRICTIONS/CONDITIONS 103.Fn g_post_event : 104.Bl -item -offset indent 105.It 106The argument 107.Fa flag 108has to be 109.Dv M_WAITOK 110or 111.Dv M_NOWAIT . 112.It 113The list of references has to end with a 114.Dv NULL 115value. 116.El 117.Pp 118.Fn g_waitfor_event : 119.Bl -item -offset indent 120.It 121The argument 122.Fa flag 123has to be 124.Dv M_WAITOK 125or 126.Dv M_NOWAIT . 127.It 128The list of references has to end with a 129.Dv NULL 130value. 131.It 132The 133.Fn g_waitfor_event 134function cannot be called from an event, since doing so would result 135in a deadlock. 136.El 137.Pp 138.Fn g_alloc_event : 139.Bl -item -offset indent 140.It 141The argument 142.Fa flag 143has to be 144.Dv M_WAITOK 145or 146.Dv M_NOWAIT . 147.It 148The returned 149.Va struct g_event * 150must be freed with 151.Fn g_free 152if 153.Fn g_post_event_ep 154is not called. 155.El 156.Sh RETURN VALUES 157The 158.Fn g_post_event 159and 160.Fn g_waitfor_event 161functions 162return 0 if successful; otherwise an error code is returned. 163.Sh EXAMPLES 164Example of a function called from the event queue. 165.Bd -literal -offset indent 166void 167example_event(void *arg, int flag) 168{ 169 170 if (flag == EV_CANCEL) { 171 printf("Event with argument %p canceled.\\n", arg); 172 return; 173 } 174 175 printf("Event with argument %p called.\\n", arg); 176} 177.Ed 178.Sh ERRORS 179Possible errors for the 180.Fn g_post_event 181function: 182.Bl -tag -width Er 183.It Bq Er ENOMEM 184The 185.Fa flag 186argument was set to 187.Dv M_NOWAIT 188and there was insufficient memory. 189.El 190.Pp 191Possible errors for the 192.Fn g_waitfor_event 193function: 194.Bl -tag -width Er 195.It Bq Er EAGAIN 196The event was canceled. 197.It Bq Er ENOMEM 198The 199.Fa flag 200argument was set to 201.Dv M_NOWAIT 202and there was insufficient memory. 203.El 204.Sh SEE ALSO 205.Xr geom 4 , 206.Xr DECLARE_GEOM_CLASS 9 , 207.Xr g_access 9 , 208.Xr g_attach 9 , 209.Xr g_bio 9 , 210.Xr g_consumer 9 , 211.Xr g_data 9 , 212.Xr g_geom 9 , 213.Xr g_provider 9 , 214.Xr g_provider_by_name 9 , 215.Xr g_wither_geom 9 216.Sh AUTHORS 217.An -nosplit 218This manual page was written by 219.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . 220