(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 01a41c25e7dc904e27ccf930fc838cb25b614a58..9ffbb2028da642f85afd6e96eec51472e56a8c79 100644 (file)
--- 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 213b527b451f261509eb750c97b3014eb44cbe31..49f719c12863b53a355d78f3f0e93b347c76b6be 100644 (file)
--- 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 00929d25e042c3d46ac6a4e1ac1ea60c6b90647a..ef8c06af24300a65d2f75240fee58864c0189eb1 100644 (file)
--- 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;