CPG_M...ALIZE(3)

💖 CPG_MODEL_INITIALIZE ✨

okay bestie, this is the cpg_model_initialize(3) page from the Corosync Cluster Engine Programmer's Manual — yes it's a whole manual, and yes you're gonna read it, because I love you and I want you to slay 🫶

---

🌸 NAME 🌸

cpg_model_initialize — Create a new connection to the CPG service

---

🎀 SYNOPSIS 🎀

#include <corosync/cpg.h>

cs_error_t cpg_model_initialize(cpg_handle_t *handle, cpg_model_t model,
cpg_model_data_t *model_data, void *context);

---

🦋 DESCRIPTION 🦋

So like, cpg_model_initialize is the function you call to set up a connection to the closed process groups API. It's giving "hello CPG service, it's me" energy. ✨

Your app can have several connections to the CPG API at once — not just one, bestie, we're multitasking. And the way you tell them apart is the handle argument. That's your lil ID badge. You pass handle into all the other function calls later so everyone knows which connection you're talking about when you're chatting with the CPG service. 💅

Then there's the model argument, which is how you explicitly pick your set of callbacks and internal parameters. Right now only model CPG_MODEL_V1 is defined, so that's your only option, no cap.

The callbacks and internal parameters get passed through the model_data argument. It's a casted pointer (same idea as the sockaddr situation, iykyk) pointing at one of the structures that matches whichever model you chose. And again — currently only cpg_model_v1_data_t is needed.

---

🌈 MODEL_V1 🌈

MODEL_V1 is backwards compatible with the original callbacks you'd set up with cpg_initialize, but it also defines a brand new callback: cpg_totem_confchg_fn. Glow up moment. ✨

Every single time a CPG event happens inside the joined group, one of the callbacks you specified in the callbacks argument gets called. Here are those callback functions as type definitions, verbatim, don't touch them:

typedef void (*cpg_deliver_fn_t) (
        cpg_handle_t handle,
        const struct cpg_name *group_name,
        uint32_t nodeid,
        uint32_t pid,
        const void *msg,
        size_t msg_len);

typedef void (*cpg_confchg_fn_t) (
        cpg_handle_t handle,
        const struct cpg_name *group_name,
        const struct cpg_address *member_list, size_t member_list_entries,
        const struct cpg_address *left_list, size_t left_list_entries,
        const struct cpg_address *joined_list, size_t joined_list_entries);

typedef void (*cpg_totem_confchg_fn_t) (
        cpg_handle_t handle,
        struct cpg_ring_id ring_id,
        uint32_t member_list_entries,
        const uint32_t *member_list);

And the cpg_model_v1_data_t structure is defined like this:

typedef struct {
        cpg_model_t model;
        cpg_deliver_fn_t cpg_deliver_fn;
        cpg_confchg_fn_t cpg_confchg_fn;
        cpg_totem_confchg_fn_t cpg_totem_confchg_fn;
        unsigned int flags;
} cpg_model_v1_data_t;

Okay so here's the tea on when each one fires ☕ — when a configuration change happens or a message needs delivering, one of these callbacks gets called from the cpg_dispatch() function:

• config change goes down? → cpg_confchg_fn gets called
• message delivery goes down? → cpg_deliver_fn gets called
• totem membership change goes down? → cpg_totem_confchg_fn gets called

And here's a lil trick, bestie: you can OR the CPG_MODEL_V1_DELIVER_INITIAL_TOTEM_CONF constant into flags and you'll get the callback after the first confchg event. 🎀

Now the cpg_address structure, defined as:

struct cpg_address {
        unsigned int nodeid;
        unsigned int pid;
        unsigned int reason;
};

where:

• nodeid is a 32 bit unique node identifier
• pid is the process ID of the process that has joined/left the group or sent the message
• reason is an integer code indicating why the node joined/left the group (⚠️ heads up: this value is not set for the member_list items)

The possible reason values, and what they mean:

• CPG_REASON_JOIN — the process joined a group using cpg_join().
• CPG_REASON_LEAVE — the process left a group using cpg_leave()
• CPG_REASON_NODEDOWN — the process left a group because the node left the cluster.
• CPG_REASON_NODEUP — the process joined a group because it was already a member of a group on a node that has just joined the cluster
• CPG_REASON_PROCDOWN — the process left a group without calling cpg_leave()
• CPG_REASON_UNDEFINED — a special value used for the member_list items

And finally the cpg_ring_id structure, defined as:

struct cpg_ring_id {
        uint32_t nodeid;
        uint64_t seq;
};

where nodeid is the current Totem leader and seq is an increasing number. 📈

---

💜 RETURN VALUE 💜

If it works, this call returns the CS_OK value. If it doesn't... it returns an error instead. That's it, that's the deal. 😭

---

💀 ERRORS 💀

ngl bestie, the errors are undocumented. That's literally what it says. We don't know. Nobody wrote it down. 🙈

---

🌟 SEE ALSO 🌟

Go read these next, queen 👑

cpg_overview(3), cpg_initialize(3), cpg_finalize(3), cpg_fd_get(3), cpg_dispatch(3), cpg_join(3), cpg_leave(3), cpg_mcast_joined(3), cpg_membership_get(3) cpg_zcb_alloc(3) cpg_zcb_free(3) cpg_zcb_mcast_joined(3) cpg_context_get(3) cpg_context_set(3) cpg_local_get(3) cpg_model_initialize(3)

And here are the error codes that show up around these parts:

• CS_ERR_TRY_AGAIN — Resource temporarily unavailable
• CS_ERR_INVALID_PARAM — Invalid argument
• CS_ERR_ACCESS — Permission denied
• CS_ERR_LIBRARY — The connection failed
• CS_ERR_INTERRUPT — System call interrupted by a signal
• CS_ERR_NOT_SUPPORTED — The requested protocol/functionality not supported
• CS_ERR_MESSAGE_ERROR — Incorrect auth message received
• CS_ERR_NO_MEMORY — Not enough memory to complete the requested task

---

okay that's the whole page, you ate that 🍓 this was the corosync Man Page, dated 2024-07-15 — mwah, go forth and initialize your connections, bestie 💅👑🌈