NAME

       g_post_event, g_waitfor_event, g_cancel_event — GEOM events management

SYNOPSIS

       #include <geom/geom.h>

       int
       g_post_event(g_event_t *func, void *arg, int flag, ...);

       int
       g_waitfor_event(g_event_t *func, void *arg, int flag, ...);

       void
       g_cancel_event(void *ref);

DESCRIPTION

       The GEOM framework has its own event queue to inform classes about important events.  The event queue can
       be  also  used  by GEOM classes themselves, for example to work around some restrictions in the I/O path,
       where sleeping, heavy weight tasks, etc. are not permitted.

       The g_post_event() function tells the GEOM framework to call function func with  argument  arg  from  the
       event  queue.   The flag argument is passed to malloc(9) for memory allocations inside of g_post_event().
       The only allowed flags are M_WAITOK and M_NOWAIT.  The rest of the arguments are used  as  references  to
       identify  the  event.   An  event  can be canceled by using any of the given references as an argument to
       g_cancel_event().  The list of references has to end with a NULL value.

       The g_waitfor_event() function is a blocking version of the g_post_event() function.  It waits until  the
       event is finished or canceled and then returns.

       The  g_cancel_event()  function  cancels  all  event(s) identified by ref.  Cancellation is equivalent to
       calling the requested function with requested arguments and argument flag set to EV_CANCEL.

RESTRICTIONS/CONDITIONS

       g_post_event():

             The argument flag has to be M_WAITOK or M_NOWAIT.

             The list of references has to end with a NULL value.

       g_waitfor_event():

             The argument flag has to be M_WAITOK or M_NOWAIT.

             The list of references has to end with a NULL value.

             The g_waitfor_event() function cannot be called from an event, since doing so  would  result  in  a
             deadlock.

RETURN VALUES

       The  g_post_event()  and  g_waitfor_event()  functions return 0 if successful; otherwise an error code is
       returned.

EXAMPLES

       Example of a function called from the event queue.

             void
             example_event(void *arg, int flag)
             {

                     if (flag == EV_CANCEL) {
                             printf("Event with argument %p canceled.\n", arg);
                             return;
                     }

                     printf("Event with argument %p called.\n", arg);
             }

ERRORS

       Possible errors for the g_post_event() function:

       [ENOMEM]           The flag argument was set to M_NOWAIT and there was insufficient memory.

       Possible errors for the g_waitfor_event() function:

       [EAGAIN]           The event was canceled.

       [ENOMEM]           The flag argument was set to M_NOWAIT and there was insufficient memory.

SEE ALSO

       geom(4), DECLARE_GEOM_CLASS(9), g_access(9), g_attach(9), g_bio(9), g_consumer(9), g_data(9),  g_geom(9),
       g_provider(9), g_provider_by_name(9), g_wither_geom(9)

AUTHORS

       This manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>.

Debian                                          January 16, 2004                                      G_EVENT(9)