SAM_H...ISTER(3)

💖 SAM_HC_CALLBACK_REGISTER — the Corosync Cluster Engine Programmer's Manual's own little icon 💖

okay bestie so we're doing a page from the Corosync Cluster Engine Programmer's Manual and it's sam_hc_callback_register(3) — section 3, library call, very demure, very mindful, very health-check. let's get into it 🫶

✨ NAME ✨

sam_hc_callback_register — register a health check callback 🩺💅

✨ SYNOPSIS ✨

#include <corosync/sam.h>

cs_error_t sam_hc_callback_register (sam_hc_callback_t cb);

like, that's the whole vibe. one function, one argument, so clean ✨

✨ DESCRIPTION ✨

so sam_hc_callback_register is literally just here to let you hand over a healthcheck callback that you wrote yourself. you register it, and boom — after you call this function, SAM switches from application driven healthchecking over to event driven healthchecking. new era unlocked 💫

and here's the slay part: once you're in that mode, you do not need to run sam_hc_send(3) anymore. not once. it's giving self-sufficient. 👑

the parameter cb is a callback function of type sam_hc_callback_t, and it's defined like this:

typedef int (*sam_hc_callback_t)(void);

this function gets called regularly (she's consistent, we love that 🎀) and it has to return 0 if the process is functioning normally, or -1 if the process is executing abnormally. and when -1 comes back? the SAM server executes the registered recovery policy. so like, don't return -1 unless you mean it fr fr 😭

you can also pass a value of NULL into this function to switch back into application driven healthchecking. cb to NULL. just like that. 🦋

✨ RETURN VALUE ✨

this call returns the CS_OK value if it's successful — otherwise an error is returned. (the original says "and error is returned", which is honestly so real of it, we're keeping it as-is 💀)

✨ ERRORS ✨

• CS_ERR_BAD_HANDLE — SAM was not initialized and registered, or health checking is in running state. so like... she's not ready, or she's already mid-glow-up. either way, no 💅
• CS_ERR_LIBRARY — an internal library call failed. this can happen during fork() or pipe() system calls, and you can read the errno variable to retrieve more information. bestie go check your errno, she's holding the tea 🫖

✨ SEE ALSO ✨

• sam_start(3)
• sam_stop(3)
• sam_hc_send(3)
• sam_register(3)

and then there's this whole other list of error codes hanging out down here, which is iconic of the original and we're keeping every single one 🌈

• 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

lowkey important: if you're getting CS_ERR_BAD_HANDLE, check that SAM is actually initialized and registered and that health checking isn't already in a running state. that's the whole checklist, no cap 🧚

and that's the page!! 🎀 this one's from the corosync Man Page, dated 12/01/2009 — yes she's an elder icon and she still ate. go register your callback, bestie, you got this 💜🌸