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)