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

   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)

LIBRECAST                                          2022-10-29                          LC_CHANNEL_DETECT_GAPS(3)