LC_CHANNE...TECT_GAPS(3)

💖 lc_channel_detect_gaps, lc_channel_check_seqno — Librecast Programmer's Manual, section 3 🎀

okay bestie, sit down, hydrate, and let me tell you about lc_channel_detect_gaps and lc_channel_check_seqno — two little functions whose whole job is catching the messages that ghosted you and asking for them back. this is page 3 of the Librecast Programmer's Manual, so you know it's giving "reference material but make it cute". ✨

---

🌸 NAME 🌸

lc_channel_detect_gaps, lc_channel_check_seqno — check for missing incoming messages and send NACK messages if required 🫶

---

📚 LIBRARY 📚

Librecast library (liblibrecast, -llibrecast)

---

✨ SYNOPSIS ✨

#include <librecast/net.h>

int lc_channel_detect_gaps(lc_channel_t *chan);
int lc_channel_check_seqno(lc_channel_t *chan, lc_seq_t seq);

and like, compile and link it with -llibrecast, obviously 💅

---

💅 DESCRIPTION 💅

so lc_channel_detect_gaps() sets things up so that a channel starts checking the message sequence numbers of the messages it just received, and fires off NACK messages the second it spots a gap. those NACKs make the sender resend the missing messages, and then they just show up like nothing happened. 🌈 for this to work, your app needs to be receiving messages with lc_msg_recv() or lc_socket_listen() — those decode the incoming messages and pull the sequence numbers out, and then gap detection just... happens. automatic. main character behaviour, no cap. 👑

then there's lc_channel_check_seqno(), which takes the sequence number you hand it, compares it against the sequence numbers of recent messages, and sends NACKs for anything it decides is missing. you have to call this one if your application rolls its own message format and receives messages with functions other than lc_msg_recv() or lc_socket_listen() — because in that case the library has no way to get the sequence numbers out of your messages. but don't worry bestie, the library is still handling gap detection and the NACK messages for you. 💖 the second argument must be the sequence number from the message, as decoded by your application.

⚠️ and listen — you must call lc_channel_detect_gaps() before using lc_channel_check_seqno(), otherwise the function literally won't do anything. like, nothing. 💀

this is lowkey useful if gap detection and NACKs are optional for you: your app can conditionally call lc_channel_detect_gaps() during initialisation, and then just unconditionally call lc_channel_check_seqno() after decoding every incoming message. no branching, no stress, we love a clean call site. 🎀

---

🫶 RETURN VALUE 🫶

lc_channel_detect_gaps() returns 0 on success, and -1 to indicate an error, setting the global variable errno to an appropriate code — most likely ENOMEM, which means there wasn't enough memory to set up the required data structures. 😭

lc_channel_detect_gaps() returns 0 if the message is new, 1 if it's a duplicate (the sequence number has already been seen), and -1 to indicate an error transmitting a NACK message, setting errno to an appropriate code. (yes, that's exactly how the page says it — I'm just the messenger 🫡)

---

💀 ERRORS 💀

lc_channel_detect_gaps() can fail with any of the errors the malloc() library function can produce, plus any errors produced by the lc_channel_sidehash() or lc_socket_new() functions.

lc_channel_check_seqno() can fail with any of the errors the lc_socket_send() function can produce.

---

🌟 EXAMPLE 🌟

🍓 Program source 🍓

lc_ctx_t *lctx;
lc_channel_t *chan;
lctx = lc_ctx_new();
chan = lc_channel_new(lctx, "channel name");
if (lc_channel_detect_gaps(chan) == -1) {
     /* handle this error */
}

/* your program goes here, likely calling lc_msg_recv(chan, ...) or lc_socket_listen(...)  */

lc_channel_free(chan);
lc_ctx_free(lctx);

---

👀 SEE ALSO 👀

lc_channel_nack_handler(3), lc_channel_free(3), lc_msg_recv(3), lc_socket_listen(3), lc_socket_send(3)

---

and that's the whole page, bestie!! this one comes to you from LIBRECAST, dated 2022-10-29, and it lives in the section 3 pages of the Librecast Programmer's Manual. go forth and catch those gaps. 💖✨🦋🧚💜