From 96ffe1c3ad22a80619d1c1f9740bcce5e86256cc Mon Sep 17 00:00:00 2001
From: Xavier Arteaga <xavier@softwareradiosystems.com>
Date: Tue, 3 Mar 2020 17:12:57 +0100
Subject: [PATCH] Commented class tti_semaphore

---
 lib/include/srslte/common/tti_sempahore.h | 44 ++++++++++++++++++++---
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/lib/include/srslte/common/tti_sempahore.h b/lib/include/srslte/common/tti_sempahore.h
index 3c2e782fd..c1ade13fb 100644
--- a/lib/include/srslte/common/tti_sempahore.h
+++ b/lib/include/srslte/common/tti_sempahore.h
@@ -29,39 +29,73 @@
 #define SRSLTE_TTI_SEMPAHORE_H_
 
 namespace srslte {
+
+/**
+ * Implements priority semaphore based on a FIFO queue wait . This class enqueues T type element identifiers (method
+ * push) and waits until the enqueued object is the first (method wait). The first element is released by method
+ * release. The method release_all waits for all the elements to be released.
+ *
+ * @tparam T Object identifier type
+ */
 template <class T>
 class tti_semaphore
 {
 private:
-  std::mutex              mutex;
-  std::condition_variable cvar;
-  std::deque<T>           fifo;
+  std::mutex              mutex; ///< Used for scope mutexes
+  std::condition_variable cvar;  ///< Used for notifying element identifier releases
+  std::deque<T>           fifo;  ///< Queue to keep order
 
 public:
+  /**
+   * Waits for the first element of the queue match the element identifier provided.
+   *
+   * @param id the element identifier
+   */
   void wait(T id)
   {
     std::unique_lock<std::mutex> lock(mutex);
-    while (!fifo.empty() && fifo.front() != id) {
+
+    // While the FIFO is not empty and the front ID does not match the provided element identifier, keep waiting
+    while (not fifo.empty() and fifo.front() != id) {
+      // Wait for a release
       cvar.wait(lock);
     }
   }
 
+  /**
+   * Enqueue (push) an element identifier to the queue
+   *
+   * @param id the element identifier
+   */
   void push(T id)
   {
     std::unique_lock<std::mutex> lock(mutex);
+
+    // Append the element identifier
     fifo.push_back(id);
   }
 
+  /**
+   * Releases (pops) the first element
+   */
   void release()
   {
     std::unique_lock<std::mutex> lock(mutex);
+
+    // Pop first element
     fifo.pop_front();
+
+    // Notify release
     cvar.notify_all();
   }
 
+  /**
+   * Waits for all the elements to be released
+   */
   void wait_all()
   {
-    while (!fifo.empty()) {
+    // Wait until the FIFO is empty
+    while (not fifo.empty()) {
       wait(fifo.front());
     }
   }