g_event(9)

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 argu

ment 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 fin

ished or canceled and then returns.

The g_cancel_event() function cancels all event(s) identi

fied 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 can

celed.0, arg);
return;

}

printf("Event with argument %p called.0, 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>.

BSD January 16, 2004

BSD