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

Compile and link with -llibrecast.

DESCRIPTION¶

lc_channel_detect_gaps() arranges for a channel to check message sequence numbers of recently received messages and to send NACK messages if it detects gaps. These NACK messages will cause the sender to resend the missing messages, which will then arrive as normal. The application needs to receive messages using lc_msg_recv() or lc_socket_listen() which decode the incoming messages and extract the sequence numbers, and will then automatically detect gaps.

lc_channel_check_seqno() compares the sequence number passed to it with the sequence numbers of recent messages and sends NACKs if any are deemed missing: it is necessary to call this if an application uses its own message format, and receives messages using functions other than lc_msg_recv() or lc_socket_listen() because the library will not have the information necessary to extract sequence numbers from messages; however the library will still take care of gap detection and NACK messages. The second argument must be the sequence number from the message as decoded by the application. It is necessary to call lc_channel_detect_gaps() before using lc_channel_check_seqno() otherwise the function will not do anything. This could be useful for example if gap detection and NACKs are optional, and the application will conditionally call lc_channel_detect_gaps() during initialisation, but then can just unconditionally call lc_channel_check_seqno() after decoding each incoming message.

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 to indicate that there was insufficient memory to set up the required data structures.

lc_channel_detect_gaps() returns 0 if the message is new, 1 if it is 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.

ERRORS¶

lc_channel_detect_gaps() can fail with any of the errors the malloc() library function can produce, as well as any errors produces 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¶

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)