NAME

       lc_channel_nack_handler,  lc_channel_nack_handler_thr, lc_channel_nack_add_log - outgoing message logging
       to handle NACK and replay requests

LIBRARY

       Librecast library (liblibrecast, -llibrecast)

SYNOPSIS

       #include <librecast/net.h>

       int lc_channel_nack_handler(lc_channel_t *chan, int n_seconds);
       int lc_channel_nack_handler_thr(lc_channel_t *chan, int n_seconds, void *(*nack_thread)(void *));
       int lc_channel_nack_add_log(lc_channel_t *chan, const void *buf, size_t len, lc_seq_t seq);

       Compile and link with -llibrecast.

DESCRIPTION

       lc_channel_nack_handler() sets up a per-channel buffer to keep a  copy  of  outgoing  messages  sent  via
       lc_msg_send()  and also starts a new thread (called "nack thread") to handle any retransmission requests;
       the outgoing messages are kept for at least n_seconds seconds if there is sufficient free  memory  to  do
       so.  The  nack  thread  listens  for messages on a related channel, interprets them as NACK messages, and
       arranges for retransmission of the corresponding messages. The normal case is that  these  NACK  messages
       are  generated  as  a  result  of  calling  lc_channel_detect_gaps()  on  the  receiver  side.  A call to
       lc_channel_free(3) will stop the nack thread if it's running.

       lc_channel_nack_handler_thr()  is  similar  to  lc_channel_nack_handler()  except  that  it  specifies  a
       different  function  to use for the nack thread; it will be called in a new thread with an opened channel
       and socket where it can receive NACK messages,  and  another  channel  it  can  use  to  resend  packets;
       currently,  there is no alternative thread to use, and this function is only used by the library's tests;
       however a different nack thread could be provided in future for example to deal with the special case  of
       messages sent from static data, which can be resent without storing recent messages in a memory buffer.

       lc_channel_nack_add_log()  adds  a  message  to  the  internal  memory  buffer,  making  it available for
       retransmission as a result of a NACK; it is not normally necessary to call this function if all  messages
       are  sent  using  lc_msg_send()  however an application which defines its own message format will need to
       call lc_channel_nack_add_log() with a copy of each message as it  goes  on  the  wire,  as  well  as  the
       sequence number it contains, as the library will have no way to find this information in the applicatin's
       own   message   format.   The   application   needs   to   call  lc_channel_nack_handler()  before  using
       lc_channel_nack_add_log() otherwise the call will not log anything:  this  could  be  useful  if  message
       logging   and   NACK   request   handling   is  optional,  so  the  application  can  conditionally  call
       lc_channel_nack_handler() during initialisation, but then unconditionally call  lc_channel_nack_add_log()
       for each message it sends.

RETURN VALUE

       lc_channel_nack_handler()  and  lc_channel_nack_handler_thr()  return 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.

       The  lc_channel_nack_add_log()  function returns 0 on success and -1 to indicate that there was no memory
       to store the message in its internal buffers, setting errno to the value ENOMEM

ERRORS

       lc_channel_nack_handler() and lc_channel_nack_handler_thr() 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_nack_add_log() can fail with any of the errors the malloc() library 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_nack_handler(chan, 10) == -1) {
            /* handle this error */
       }

       /* your program goes here, likely calling lc_msg_send(chan, ...) */

       lc_channel_free(chan);
       lc_ctx_free(lctx);

SEE ALSO

       lc_channel_detect_gaps(3), lc_channel_free(3), lc_msg_send(3)

LIBRECAST                                          2022-10-29                         LC_CHANNEL_NACK_HANDLER(3)