From ce056b9e676aa7e498a7984b63009f10fa1caecb Mon Sep 17 00:00:00 2001
From: Martin Pulec <pulec@cesnet.cz>
Date: Wed, 23 Mar 2016 11:17:14 +0100
Subject: [PATCH] RTP UDP: some documentation + minor changes

---
 src/rtp/net_udp.cpp | 34 +++++++++++++++++++++++++++++-----
 src/rtp/rtp.c       |  4 +++-
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/src/rtp/net_udp.cpp b/src/rtp/net_udp.cpp
index 56c8208e2..86c53a0ff 100644
--- a/src/rtp/net_udp.cpp
+++ b/src/rtp/net_udp.cpp
@@ -945,6 +945,13 @@ int udp_sendv(socket_udp * s, struct iovec *vector, int count, void *d)
 }
 #endif // WIN32
 
+/**
+ * When receiving data in separate thread, this function fetches data
+ * from socket and puts it in queue.
+ *
+ * @todo
+ * Remove ugly thread cancellation stuff.
+ */
 static void *udp_reader(void *arg)
 {
         socket_udp *s = (socket_udp *) arg;
@@ -1024,16 +1031,21 @@ int udp_peek(socket_udp * s, char *buffer, int buflen)
         return udp_do_recv(s, buffer, buflen, MSG_PEEK, 0, 0);
 }
 
+/**
+ * @brief
+ * Checks whether there are data ready to read in socket
+ *
+ * @note
+ * Designed only for multithreaded socket!
+ */
 bool udp_not_empty(socket_udp * s, struct timeval *timeout)
 {
-        std::chrono::microseconds tmout_us;
-
-        if (timeout) {
-                tmout_us = std::chrono::microseconds(timeout->tv_sec * 1000000ll + timeout->tv_usec);
-        }
+        assert(s->multithreaded);
 
         unique_lock<mutex> lk(s->lock);
         if (timeout) {
+                std::chrono::microseconds tmout_us =
+                        std::chrono::microseconds(timeout->tv_sec * 1000000ll + timeout->tv_usec);
                 s->boss_cv.wait_for(lk, tmout_us, [s]{return s->queue_head != s->queue_tail;});
         } else {
                 s->boss_cv.wait(lk, [s]{return s->queue_head != s->queue_tail;});
@@ -1065,8 +1077,16 @@ int udp_recvfrom(socket_udp *s, char *buffer, int buflen, struct sockaddr *src_a
         return udp_do_recv(s, buffer, buflen, 0, src_addr, addrlen);
 }
 
+/**
+ * Receives data from multithreaded socket.
+ *
+ * @param[in] s       UDP socket state
+ * @param[out] buffer data received from socket. Must be freeed by caller!
+ * @returns           length of the received datagram
+ */
 int udp_recv_data(socket_udp * s, char **buffer)
 {
+        assert(s->multithreaded);
         int ret;
         unique_lock<mutex> lk(s->lock);
 
@@ -1464,6 +1484,10 @@ int udp_send_wsa_async(socket_udp *s, char *buffer, int buflen, LPWSAOVERLAPPED_
 }
 #endif
 
+/**
+ * Tries to receive data from socket and if empty, waits at most specified
+ * amount of time.
+ */
 int udp_recv_timeout(socket_udp *s, char *buffer, int buflen, struct timeval *timeout)
 {
         struct udp_fd_r fd;
diff --git a/src/rtp/rtp.c b/src/rtp/rtp.c
index daa4e3f94..5377e46e6 100644
--- a/src/rtp/rtp.c
+++ b/src/rtp/rtp.c
@@ -1048,6 +1048,8 @@ struct rtp *rtp_init(const char *addr,
  * @callback: See section on #rtp_callback.
  * @userdata: Opaque data associated with the session.  See
  * rtp_get_userdata().
+ * @use_ipv6 whether or not use IP version 6
+ * @multithreaded if set to true uses separate thread to receive data (performance optimization)
  *
  * Creates and initializes an RTP session.
  *
@@ -2227,7 +2229,7 @@ int rtp_recv(struct rtp *session, struct timeval *timeout, uint32_t curr_rtp_ts)
  * 
  * Reentrant variant of rtp_recv()
  *
- * Currently, this function is the only one of rtp_recv family egliable for multithreaded
+ * Currently, this function is the only one of rtp_recv family eligible for multithreaded
  * receiving.
  *
  * @param session     the session pointer (returned by rtp_init())