| g_event.9 (126861) | g_event.9 (129381) |
|---|---|
| 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 --- 8 unchanged lines hidden (view full) --- 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.\" | 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 --- 8 unchanged lines hidden (view full) --- 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: head/share/man/man9/g_event.9 126861 2004-03-11 19:53:22Z pjd $ | 25.\" $FreeBSD: head/share/man/man9/g_event.9 129381 2004-05-18 11:33:37Z le $ |
| 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 | 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 "events management" | 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 | 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 has its own event queue to inform classes about important things. 45The event queue can be also used by classes, mostly for running away 46from I/O path. 47Sleeping, heavy weight tasks, etc. are not permitted on I/O path and 48events are the cure to avoid such situations. | 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 | 49.Pp 50The 51.Fn g_post_event |
| 52function tells GEOM to call function | 52function tells the GEOM framework to call function |
| 53.Fa func 54with argument 55.Fa arg 56from the event queue. 57The 58.Fa flag | 53.Fa func 54with argument 55.Fa arg 56from the event queue. 57The 58.Fa flag |
| 59argument is a flag for | 59argument is passed to |
| 60.Xr malloc 9 | 60.Xr malloc 9 |
| 61that should be used by GEOM. 62Only the flags | 61for memory allocations inside of 62.Fn g_post_event . 63The only allowed flags are |
| 63.Dv M_WAITOK | 64.Dv M_WAITOK |
| 64or 65.Dv M_NOWAIT 66can be used. 67The rest of the arguments are used as references. 68An event can be canceled by using any of given references as an 69argument to the 70.Fn g_cancel_event 71function. | 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 . |
| 72The list of references has to end with a 73.Dv NULL 74value. 75.Pp 76The 77.Fn g_waitfor_event 78function is a blocking version of the 79.Fn g_post_event 80function. 81It waits until the event is finished or canceled and then returns. 82.Pp 83The 84.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 |
| 85function cancels event(s) identified by | 84function cancels all event(s) identified by |
| 86.Fa ref . 87Cancellation is equivalent to calling the requested function 88with requested arguments and argument 89.Fa flag 90set to 91.Dv EV_CANCEL . 92.Sh RESTRICTIONS/CONDITIONS 93.Fn g_post_event : --- 29 unchanged lines hidden (view full) --- 123.Fn g_waitfor_event 124function can not be called from an event, since doing so would result 125in a deadlock. 126.El 127.Sh RETURN VALUES 128.Fn g_post_event 129and 130.Fn g_waitfor_event | 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 : --- 29 unchanged lines hidden (view full) --- 122.Fn g_waitfor_event 123function can not be called from an event, since doing so would result 124in a deadlock. 125.El 126.Sh RETURN VALUES 127.Fn g_post_event 128and 129.Fn g_waitfor_event |
| 131returns the value 0 if successful; otherwise an error code is returned. | 130return 0 if successful; otherwise an error code is returned. |
| 132.Sh ERRORS | 131.Sh ERRORS |
| 133Possible errors for | 132Possible errors for the |
| 134.Fn g_post_event 135function: 136.Bl -tag -width Er 137.It Bq Er ENOMEM | 133.Fn g_post_event 134function: 135.Bl -tag -width Er 136.It Bq Er ENOMEM |
| 138There was insufficient memory. | 137The 138.Fa flag 139argument was set to M_NOWAIT and there was insufficient memory. |
| 139.El 140.Pp | 140.El 141.Pp |
| 141Possible errors for | 142Possible errors for the |
| 142.Fn g_waitfor_event 143function: 144.Bl -tag -width Er 145.It Bq Er EAGAIN 146The event was canceled. 147.It Bq Er ENOMEM | 143.Fn g_waitfor_event 144function: 145.Bl -tag -width Er 146.It Bq Er EAGAIN 147The event was canceled. 148.It Bq Er ENOMEM |
| 148There was insufficient memory. | 149The 150.Fa flag 151argument was set to M_NOWAIT and there was insufficient memory. |
| 149.El 150.Sh EXAMPLES 151Example of a function called from the event queue. 152.Bd -literal -offset indent 153void 154example_event(void *arg, int flag) 155{ 156 --- 24 unchanged lines hidden --- | 152.El 153.Sh EXAMPLES 154Example of a function called from the event queue. 155.Bd -literal -offset indent 156void 157example_event(void *arg, int flag) 158{ 159 --- 24 unchanged lines hidden --- |