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 EXAMPLES 134Example of a function called from the event queue. 135.Bd -literal -offset indent 136void 137example_event(void *arg, int flag) 138{ 139 140 if (flag == EV_CANCEL) { 141 printf("Event with argument %p canceled.\\n", arg); 142 return; 143 } 144 145 printf("Event with argument %p called.\\n", arg); 146} 147.Ed 148.Sh ERRORS 149Possible errors for the 150.Fn g_post_event 151function: 152.Bl -tag -width Er 153.It Bq Er ENOMEM 154The 155.Fa flag 156argument was set to 157.Dv M_NOWAIT 158and there was insufficient memory. 159.El 160.Pp 161Possible errors for the 162.Fn g_waitfor_event 163function: 164.Bl -tag -width Er 165.It Bq Er EAGAIN 166The event was canceled. 167.It Bq Er ENOMEM 168The 169.Fa flag 170argument was set to 171.Dv M_NOWAIT 172and there was insufficient memory. 173.El 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