From: Kefu Chai <kchai@redhat.com>
Date: Thu, 23 Apr 2015 07:46:12 +0000 (+0800)
Subject: Throttle: improve doxygen comments in Throttle
X-Git-Tag: v9.0.1~60^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=127c931ca63b99a950f319b7bffa87865aee90a7;p=ceph.git

Throttle: improve doxygen comments in Throttle

* reindent a line

Signed-off-by: Kefu Chai <kchai@redhat.com>
---

diff --git a/src/common/Throttle.h b/src/common/Throttle.h
index 6d039888c63..2423c92b43b 100644
--- a/src/common/Throttle.h
+++ b/src/common/Throttle.h
@@ -12,11 +12,19 @@
 class CephContext;
 class PerfCounters;
 
+/**
+ * @class Throttle
+ * Throttles the maximum number of active requests.
+ *
+ * This class defines the maximum number of slots currently taken away. The
+ * excessive requests for more of them are delayed, until some slots are put
+ * back, so @p get_current() drops below the limit after fulfills the requests.
+ */
 class Throttle {
   CephContext *cct;
   std::string name;
   PerfCounters *logger;
-	ceph::atomic_t count, max;
+  ceph::atomic_t count, max;
   Mutex lock;
   list<Cond*> cond;
   bool use_perf;
@@ -39,22 +47,58 @@ private:
   bool _wait(int64_t c);
 
 public:
+  /**
+   * gets the number of currently taken slots
+   * @returns the number of taken slots
+   */
   int64_t get_current() {
     return count.read();
   }
 
+  /**
+   * get the max number of slots
+   * @returns the max number of slots
+   */
   int64_t get_max() { return max.read(); }
 
+  /**
+   * set the new max number, and wait until the number of taken slots drains
+   * and drops below this limit.
+   *
+   * @param m the new max number
+   * @returns true if this method is blocked, false it it returns immediately
+   */
   bool wait(int64_t m = 0);
 
+  /**
+   * take the specified number of slots from the stock regardless the throttling
+   * @param c number of slots to take
+   * @returns the total number of taken slots
+   */
   int64_t take(int64_t c = 1);
+
+  /**
+   * get the specified amount of slots from the stock, but will wait if the
+   * total number taken by consumer would exceed the maximum number.
+   * @param c number of slots to get
+   * @param m new maximum number to set, ignored if it is 0
+   * @returns true if this request is blocked due to the throttling, false 
+   * otherwise
+   */
   bool get(int64_t c = 1, int64_t m = 0);
 
   /**
-   * Returns true if it successfully got the requested amount,
+   * the unblocked version of @p get()
+   * @returns true if it successfully got the requested amount,
    * or false if it would block.
    */
   bool get_or_fail(int64_t c = 1);
+
+  /**
+   * put slots back to the stock
+   * @param c number of slots to return
+   * @returns number of requests being hold after this
+   */
   int64_t put(int64_t c = 1);
 };