G_EVENT(9)

💅 G_EVENT(9) — like, the GEOM events manual, bestie

okay so this is a page from the Kernel Developer's Manual and it's literally all about g_post_event, g_waitfor_event, g_cancel_event — the GEOM events management girlies 💖 if you're writing GEOM classes you're gonna want this, iykyk.

---

✨ 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);

struct g_event *
g_alloc_event(int flag);

void
g_post_event_ep(g_event_t *func, void *arg, struct g_event *ep, ...);

---

🌸 DESCRIPTION 🌸

so the GEOM framework has its own event queue, right? it uses it to tell classes about important events — main character energy fr fr 👑 and like, GEOM classes can totally use it too for their own stuff, for example to work around some restrictions in the I/O path where sleeping, heavy weight tasks, etc. are not permitted. no cap, that's the whole point.

💀 quick vibe check: sleeping and heavy lifting in the I/O path = not allowed. that's why the event queue exists.

• g_post_event() — tells the GEOM framework to call function func with argument arg from the event queue. the flag argument gets 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(). and the list of references has to end with a NULL value — don't forget or it's giving chaos 😭
• g_waitfor_event() — the blocking version of g_post_event(). it waits until the event is finished or canceled and then returns. patient queen 🫶
• g_post_event_ep() — posts the event with a pre-allocated struct g_event. an event may be pre-allocated with g_alloc_event(). efficient icon ⭐
• g_cancel_event() — cancels all event(s) identified by ref. and here's the slay: cancellation is equivalent to calling the requested function with requested arguments and argument flag set to EV_CANCEL. 💅

---

🚧 RESTRICTIONS/CONDITIONS 🚧

okay bestie, read this part, it's literally the rules ✨

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. 🩸 like, do not do it, that's not the vibe at all.

g_alloc_event()

• the argument flag has to be M_WAITOK or M_NOWAIT.
• the returned struct g_event * must be freed with g_free() if g_post_event_ep() is not called. 👈 literally don't leak it, that's so not cute

---

🎀 RETURN VALUES 🎀

the g_post_event() and g_waitfor_event() functions return 0 if successful; otherwise an error code is returned. simple as that 🌈

---

🧚 EXAMPLES 🧚

here's an example of a function called from the event queue — periodt:

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);
}

see how it handles the EV_CANCEL case first? that's the self-care check 💅

---

💀 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)

like, the whole friend group honestly 🫶 go read them all

---

👑 AUTHORS 👑

this manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>. iconic behavior, we stan 💖

---

and that's the page, bestie! 🌸 this Debian build dropped on July 23, 2021 and it's filed under G_EVENT(9) — go forth and queue your events responsibly, mwah 💋✨