CMAP_TRACK_ADD(3)

💖 CMAP_TRACK_ADD — bestie edition 💖

okay so this is cmap_track_add from the Corosync Cluster Engine Programmer's Manual, section 3 (that's the library-functions girlies, iykyk). no cap, this one's lowkey important. let's get into it 🦋

✨ NAME ✨

cmap_track_add — the function that sets a tracking function for values in CMAP. yes queen, you're literally spying on your own config keys (affectionately). 👑

🌸 SYNOPSIS 🌸

#include <corosync/cmap.h>

cs_error_t cmap_track_add (cmap_handle_t handle, const char *key_name,
int32_t track_type, cmap_notify_fn_t notify_fn, void *user_data,
cmap_track_handle_t *cmap_track_handle);

💅 DESCRIPTION 💅

so cmap_track_add sets up a function that tracks changes in CMAP. and bestie, she's generous — one single CMAP connection can track multiple keys, and you can even track the same key multiple times. iconic behaviour honestly. 💖

• handle — your connection to the CMAP database, obtained by calling cmap_initialize(3). this is your portal, your main character entrance. ✨
• key_name — either the exact key name or a prefix of a key name you want to track changes on.
• track_type — a bitfield, which may consist of the following values:

🎀 the track_type bitfield 🎀

• CMAP_TRACK_ADD — tracks the addition of a new key (or a key added in a callback). new key just dropped 🍓
• CMAP_TRACK_DELETE — tracks the deletion of a key (or a key deleted in a callback). rip bestie 😭
• CMAP_TRACK_MODIFY — tracks the modification of a key (or a key modified in a callback). glow-up detected 💅
• CMAP_TRACK_PREFIX — the whole prefix is tracked instead of just the key alone, so tracking "totem." means it applies to "totem.nodeid", "totem.version", and so on. (heads up: this value is never returned in the callback — it's a setup-only vibe 🫶)

🌈 the other args 🌈

• notify_fn — pointer to the function that gets called when a value changes. her definition and the meaning of her parameters are discussed below, keep reading bestie.
• user_data — passed directly to notify_fn with zero changes. no notes, no edits, straight through. ✨
• cmap_track_handle — used for removing the tracking when you no longer need it, by calling cmap_track_delete(3). it's giving "we're done here" energy.

🧚 the callback function 🧚

the callback function is defined as:

typedef void (*cmap_notify_fn_t) (
    cmap_handle_t cmap_handle,
    cmap_track_handle_t cmap_track_handle,
    int32_t event,
    const char *key_name,
    struct cmap_notify_value new_value,
    struct cmap_notify_value old_value,
    void *user_data);

breaking it down, one param at a time, because she deserves it:

• cmap_handle — the handle used when registering the track function.
• cmap_track_handle — the handle returned by the cmap_track_add function.
• event — one of CMAP_TRACK_ADD, CMAP_TRACK_DELETE or CMAP_TRACK_MODIFY.
• key_name — the name of the changed key.
• new_value — the new value of the key, or unset if the event is CMAP_TRACK_DELETE.
• old_value — the previous value of the key, or unset if the event is CMAP_TRACK_ADD, or for some special keys set directly by Corosync due to speed optimizations. (yes, speed. she's fast. 🏃‍♀️)
• user_data — your little gift, delivered untouched.

both new_value and old_value are structures defined as:

struct cmap_notify_value {
    cmap_value_types_t type;
    size_t len;
    const void *data;
};

so: if the value is unset, all fields are set to 0. otherwise type is one of the cmap types (as described in the cmap_get(3) function), len is the length of the value in cmap, and data is a pointer to the value of the item. 🫶

⚠️ data storage is dynamically allocated by the caller, and the notify function must not try to free it. do not free her. she is not yours to free. 💀

⭐ RETURN VALUE ⭐

this call returns the CS_OK value if successful. slay. ✨

it can also return CS_ERR_INVALID_PARAM if notify_fn is NULL or if track_type is an invalid value. (so like, don't do that 💅)

🦋 NOTES 🦋

• modification tracking of individual keys is supported in the stats map, but not prefixes. so keys? yes. prefixes? no bestie. 🙈
• add/delete operations are supported on prefixes though, so you can track for new ipc connections or knet interfaces. that's the loophole and it's valid. 🔥
• in the icmap map, prefix tracking is fully supported. she's the overachiever of the family 👑

💜 SEE ALSO 💜

• cmap_track_delete(3)
• cmap_initialize(3)
• cmap_get(3)
• cmap_dispatch(3)
• cmap_overview(3)

and the error codes, in all their glory:

• 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, no skips, no crumbs left behind 🍓💖 this one's from the corosync Man Page, dated 06/02/2012 — vintage but still serving, fr fr. go track some keys, bestie, you've got this. periodt. 👑✨🌈