CPG_INITIALIZE(3)

💖 CPG_INITIALIZE 💖

okay bestie, welcome to CPG_INITIALIZE(3) — yes it's a section 3 page, yes it's from the Corosync Cluster Engine Programmer's Manual, and yes we are going to get you connected to the closed process groups API. let's go 🦋

✨ NAME ✨

cpg_initialize — create a new connection to the CPG service 💅

🌸 SYNOPSIS 🌸

#include <corosync/cpg.h>

int cpg_initialize(cpg_handle_t *handle, cpg_callbacks_t *callbacks);

🎀 DESCRIPTION 🎀

so, the cpg_initialize function is literally the thing that initializes a connection to the closed process groups API. BUT — huge heads up — this function is deprecated, and cpg_model_initialize should be used in newly written code. yes i'm being dramatic, but also i'm being accurate. periodt. 💀

every application can have several connections to the CPG API, no cap. each application uses the handle argument to uniquely identify the connection. and then that handle argument gets used in other function calls to identify which connection is the one being used for communication with the CPG service. it's giving ✨personalized ID badge✨.

every single time a CPG event occurs within the joined group, one of the callbacks specified by the argument callbacks is called. the callback functions are described by these type definitions, right here, verbatim, do not touch:

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

and the callbacks argument? it's of the type:

typedef struct {
        cpg_deliver_fn_t cpg_deliver_fn;
        cpg_confchg_fn_t cpg_confchg_fn;
} cpg_callbacks_t;

when a configuration change occurs, or when a message is to be delivered, one of those callbacks gets called from the cpg_dispatch() function. so: configuration change happens → cpg_confchg_fn gets called. delivery of a message happens → cpg_deliver_fn gets called. iconic division of labor tbh 👑

and the cpg_address structure is defined like this:

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, and reason is an integer code indicating why the node joined/left the group. ⚠️ quick note bestie: this value is not set for the member_list items.

here are all the reason codes, no skipping:

• 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

💫 RETURN VALUE 💫

this call returns the CS_OK value if successful, otherwise an error is returned. simple as that 🫶

🌈 ERRORS 🌈

the errors are undocumented. yeah. i know. we're all just out here vibing 🙈

⭐ SEE ALSO ⭐

• 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 the error codes, served fresh:

• 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

and that's the whole page, bestie!! 💖 this lil beauty comes to you from the corosync Man Page, dated 2019-04-16, and yeah the manual name is still CPG_INITIALIZE(3) because some things never change. go forth and initialize responsibly ✨🎀🦋