Docs: relayd: document the lifetime of viewer session trace chunks

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I167ae4e651099c824bb24d5497199d1414b6ca1a

diff --git a/src/bin/lttng-relayd/viewer-session.h b/src/bin/lttng-relayd/viewer-session.h
index 2895db0ef43230ed4d40b5dad4a24da434abf22f..cbf4aa157dcfff4c8071ca3792191a8988a8e199 100644 (file)
--- a/src/bin/lttng-relayd/viewer-session.h
+++ b/src/bin/lttng-relayd/viewer-session.h
@@ -30,6 +30,29 @@ struct relay_viewer_session {
         */
        struct cds_list_head session_list;      /* RCU list. */
        pthread_mutex_t session_list_lock;      /* Protects list updates. */
+       /*
+        * The viewer session's current trace chunk is initially set, when
+        * a viewer attaches to the viewer session, to a copy the corresponding
+        * relay_session's current trace chunk.
+        *
+        * A live session always attempts to "catch-up" to the newest available
+        * trace chunk. This means that when a viewer reaches the end of a
+        * trace chunk, the viewer session may not transition to the "next" one:
+        * it jumps to the most recent trace chunk available (the one being
+        * produced by the relay_session). Hence, if the producer performs
+        * multiple rotations before a viewer completes the consumption of a
+        * trace chunk, it will skip over those "intermediary" trace chunks.
+        *
+        * A viewer session updates its current trace chunk when:
+        *   1) new viewer streams are created,
+        *   2) a new index is requested,
+        *   3) metadata is requested.
+        *
+        * Hence, as a general principle, the viewer session will reference the
+        * most recent trace chunk available _even if its streams do not point to
+        * it_. It indicates which trace chunk viewer streams should transition
+        * to when the end of their current trace chunk is reached.
+        */
        struct lttng_trace_chunk *current_trace_chunk;
 };