From: Hans Fugal <fugalh@fb.com>
Date: Sat, 22 Feb 2014 00:22:15 +0000 (-0800)
Subject: (wangle) more comment tweaks
X-Git-Tag: v0.22.0~670
X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=3fb62b36b1548dbf7a103fcb9bb972fb6c715967;p=folly.git

(wangle) more comment tweaks

Test Plan: eyeballs

Reviewed By: hannesr@fb.com

FB internal diff: D1185813
---

diff --git a/folly/wangle/GenericThreadGate.h b/folly/wangle/GenericThreadGate.h
index 01a41c25..9ffbb202 100644
--- a/folly/wangle/GenericThreadGate.h
+++ b/folly/wangle/GenericThreadGate.h
@@ -21,6 +21,11 @@
 
 namespace folly { namespace wangle {
 
+/// This generic threadgate takes two executors and an optional waiter (if you
+/// need to support waiting). Hint: use executors that inherit from Executor
+/// (in Executor.h), then you just do
+///
+///   GenericThreadGate tg(westExecutor, eastExecutor, waiter);
 template <
   class WestExecutorPtr = Executor*,
   class EastExecutorPtr = Executor*,
@@ -52,6 +57,7 @@ public:
   WestExecutorPtr westExecutor;
   EastExecutorPtr eastExecutor;
   WaiterPtr waiter;
+
 private:
   void makeProgress_(std::true_type const&) {
     throw std::logic_error("No waiter.");
diff --git a/folly/wangle/Later.h b/folly/wangle/Later.h
index 213b527b..49f719c1 100644
--- a/folly/wangle/Later.h
+++ b/folly/wangle/Later.h
@@ -110,18 +110,18 @@ class Later {
 
   /*
    * Resets the executor - all then() calls made after the call to via() will be
-   * made in the new executor.
+   * made in the new executor. The Executor must outlive.
    */
   Later<T> via(Executor* executor);
 
   /*
    * Starts the workflow. The function provided in the constructor will be
-   * called in the executor provided in the constructor. All proximate then()
+   * called in the executor provided in the constructor. Subsequent then()
    * calls will be made, potentially changing threads if a via() call is made.
    * The future returned will be fulfilled in the last executor.
    *
    * Thread safety issues of Futures still apply. If you want to wait on the
-   * Future, it must be done in the thread that will fulfill it. If you do not
+   * Future, it must be done in the thread that will fulfil it. If you do not
    * plan to use the result of the Future, use fireAndForget()
    */
   Future<T> launch();
diff --git a/folly/wangle/ThreadGate.h b/folly/wangle/ThreadGate.h
index 00929d25..ef8c06af 100644
--- a/folly/wangle/ThreadGate.h
+++ b/folly/wangle/ThreadGate.h
@@ -49,9 +49,7 @@ namespace folly { namespace wangle {
   In order to make and use a ThreadGate, you need to provide a strategy for
   executing code in the east and west threads. These strategies may be
   different. The only requirement is a threadsafe method
-  `void add(function<void()>&&)`. You may find the executors in
-  Executor.h handy, but ensure that you are using them
-  threadsafely.
+  `void add(function<void()>&&)`.
 
   In order for your ThreadGate to do anything, you need to drive those
   executors somehow. An event loop is a natural fit. A thread pool might be
@@ -69,6 +67,9 @@ namespace folly { namespace wangle {
   Future change toward a multithreaded architecture easier, as you need only
   change the components of the ThreadGate which your client code is already
   using.
+
+  Later (in Later.h) is an alternative mechanism for thread-traversing
+  asynchronous workflows.
   */
 class ThreadGate {
 public:
@@ -105,7 +106,7 @@ public:
 
     In summary, both east and west need to have plans to drive their
     executors, or nothing will actually happen. When the executors are driven,
-    then everything flows.    */
+    then everything flows. */
   template <class T>
   Future<T> gate(std::function<Future<T>()>&& fn) {
     Promise<T> pWest;