G_CONSUMER(9)

💖 G_CONSUMER(9) 💖

okay bestie, welcome to the Kernel Developer's Manual — yes this is a 9 section page, we're in kernel-land now, put your seatbelt on 🎀

---

✨ NAME ✨

g_new_consumer, g_destroy_consumer — the GEOM consumers management situation, and yes it's exactly as iconic as it sounds 💅

---

🌸 SYNOPSIS 🌸

#include <geom/geom.h>

struct g_consumer *
g_new_consumer(struct g_geom *gp);

void
g_destroy_consumer(struct g_consumer *cp);

like, that's it. that's the whole vibe. two functions. one header. slay ✨

---

🦋 DESCRIPTION 🦋

okay so picture this: a GEOM consumer is the backdoor through which a geom connects to another GEOM provider, and also the lil tunnel through which I/O requests get sent. it's giving secret passageway, it's giving "we go through here" 🚪✨

The g_new_consumer() function creates a brand new consumer on geom gp. but bestie, listen — before you can actually use that shiny new consumer, it has to be attached to a provider with g_attach(9) and opened with g_access(9). no skipping steps, we do not freestyle the topology 🔥

The g_destroy_consumer() function destroys the given consumer and cancels all related pending events. this one is literally the last stage of killing an unwanted consumer. it's the series finale, the final boss, the closing credits 💀✨

---

🔒 RESTRICTIONS/CONDITIONS 🔒

for g_new_consumer():

• The geom gp has to have an orphan method defined. no orphan method, no consumer, that's the rule 🙈
• The topology lock has to be held. HAS TO. do not come in here unlocked, i will know 😭

for g_destroy_consumer():

• The consumer must not be attached to a provider.
• The access count has to be 0.
• The topology lock has to be held.

okay so all three of those are non-negotiable, fr fr. break them and the kernel will simply not be having a good time 💀

---

🎀 RETURN VALUES 🎀

The g_new_consumer() function returns a pointer to the newly created consumer. congrats, you're a parent now 🫶✨

---

⭐ EXAMPLES ⭐

so like, the whole arc: create consumer, attach it to a given provider, gain read access, and clean up after yourself like a responsible main character. here's the code, verbatim, don't touch anything 👑

void
some_function(struct g_geom *mygeom, struct g_provider *pp)
{
    struct g_consumer *cp;

    g_topology_assert();

    /* Create new consumer on 'mygeom' geom. */
    cp = g_new_consumer(mygeom);
    /* Attach newly created consumer to given provider. */
    if (g_attach(cp, pp) != 0) {
        g_destroy_consumer(cp);
        return;
    }
    /* Open provider for reading through our consumer. */
    if (g_access(cp, 1, 0, 0) != 0) {
        g_detach(cp);
        g_destroy_consumer(cp);
        return;
    }

    g_topology_unlock();
    /*
     * Read data from provider.
     */
    g_topology_lock();

    /* Disconnect from provider (release access count). */
    g_access(cp, -1, 0, 0);
    /* Detach from provider. */
    g_detach(cp);
    /* Destroy consumer. */
    g_destroy_consumer(cp);
}

notice the g_topology_assert() at the top? that's the vibe check. and notice how every failure path cleans up after itself? that's main character energy, we do not leak 🧚💜

---

👀 SEE ALSO 👀

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

like, the whole friend group. go read them, iykyk 🌈

---

💜 AUTHORS 💜

This manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>. thank you for your service king 🫡✨

---

and that's the page bestie!! this one came from the Debian crew and it's dated January 16, 2004, filed under G_CONSUMER(9). go forth and manage your consumers responsibly 💖🎀🦋