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