share/man/man9/g_event.9

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