react-native-windows 0.85.0-preview.1 → 0.85.0

package/external/folly/folly/docs/Conv.md

@@ -0,0 +1,291 @@
+`folly/Conv.h`
+-------------
+
+`folly/Conv.h` is a one-stop-shop for converting values across
+types. Its main features are simplicity of the API (only the
+names `to` and `toAppend` must be memorized), speed
+(folly is significantly faster, sometimes by an order of magnitude,
+than comparable APIs), and correctness.
+
+### Synopsis
+***
+
+All examples below are assume to have included `folly/Conv.h`
+and issued `using namespace folly;` You will need:
+
+``` Cpp
+    // To format as text and append to a string, use toAppend.
+    fbstring str;
+    toAppend(2.5, &str);
+    CHECK_EQ(str, "2.5");
+
+    // Multiple arguments are okay, too. Just put the pointer to string at the end.
+    toAppend(" is ", 2, " point ", 5, &str);
+    CHECK_EQ(str, "2.5 is 2 point 5");
+
+    // You don't need to use fbstring (although it's much faster for conversions and in general).
+    std::string stdStr;
+    toAppend("Pi is about ", 22.0 / 7, &stdStr);
+    // In general, just use to<TargetType>(sourceValue). It returns its result by value.
+    stdStr = to<std::string>("Variadic ", "arguments also accepted.");
+
+    // to<fbstring> is 2.5x faster than to<std::string> for typical workloads.
+    str = to<fbstring>("Variadic ", "arguments also accepted.");
+```
+
+### Integral-to-integral conversion
+***
+
+Using `to<Target>(value)` to convert one integral type to another
+will behave as follows:
+
+* If the target type can accommodate all possible values of the
+  source value, the value is implicitly converted. No further
+  action is taken. Example:
+
+``` Cpp
+        short x;
+        unsigned short y;
+        ...
+        auto a = to<int>(x); // zero overhead conversion
+        auto b = to<int>(y); // zero overhead conversion
+```
+
+* Otherwise, `to` inserts bounds checks and throws
+  `std::range_error` if the target type cannot accommodate the
+  source value. Example:
+
+``` Cpp
+    short x;
+    unsigned short y;
+    long z;
+    ...
+    x = 123;
+    auto a = to<unsigned short>(x); // fine
+    x = -1;
+    a = to<unsigned short>(x); // THROWS
+    z = 2000000000;
+    auto b = to<int>(z); // fine
+    z += 1000000000;
+    b = to<int>(z); // THROWS
+    auto b = to<unsigned int>(z); // fine
+```
+
+### Anything-to-string conversion
+***
+
+As mentioned, there are two primitives for converting anything to
+string: `to` and `toAppend`. They support the same set of source
+types, literally by definition (`to` is implemented in terms of
+`toAppend` for all types). The call `toAppend(value, &str)`
+formats and appends `value` to `str` whereas
+`to<StringType>(value)` formats `value` as a `StringType` and
+returns the result by value. Currently, the supported
+`StringType`s are `std::string` and `fbstring`
+
+Both `toAppend` and `to` with a string type as a target support
+variadic arguments. Each argument is converted in turn. For
+`toAppend` the last argument in a variadic list must be the
+address of a supported string type (no need to specify the string
+type as a template argument).
+
+#### Integral-to-string conversion
+
+Nothing special here - integrals are converted to strings in
+decimal format, with a '-' prefix for negative values. Example:
+
+``` Cpp
+    auto a = to<fbstring>(123);
+    assert(a == "123");
+    a = to<fbstring>(-456);
+    assert(a == "-456");
+```
+
+The conversion implementation is aggressively optimized. It
+converts two digits at a time assisted by fixed-size tables.
+Converting a `long` to an `fbstring` is 3.6x faster than using
+`boost::lexical_cast` and 2.5x faster than using `sprintf` even
+though the latter is used in conjunction with a stack-allocated
+constant-size buffer.
+
+Note that converting integral types to `fbstring` has a
+particular advantage compared to converting to `std::string`
+No integral type (<= 64 bits) has more than 20 decimal digits
+including sign. Since `fbstring` employs the small string
+optimization for up to 23 characters, converting an integral
+to `fbstring` is guaranteed to not allocate memory, resulting
+in significant speed and memory locality gains. Benchmarks
+reveal a 2x gain on a typical workload.
+
+#### `char` to string conversion
+
+Although `char` is technically an integral type, most of the time
+you want the string representation of `'a'` to be `"a"`, not `96`
+That's why `folly/Conv.h` handles `char` as a special case that
+does the expected thing. Note that `signed char` and `unsigned
+char` are still considered integral types.
+
+
+#### Floating point to string conversion
+
+`folly/Conv.h` uses [V8's double conversion](http://code.google.com/p/double-conversion/)
+routines. They are accurate and fast; on typical workloads,
+`to<fbstring>(doubleValue)` is 1.9x faster than `sprintf` and
+5.5x faster than `boost::lexical_cast` (It is also 1.3x faster
+than `to<std::string>(doubleValue)`
+
+#### `const char*` to string conversion
+
+For completeness, `folly/Conv.h` supports `const char*` including
+i.e. string literals. The "conversion" consists, of course, of
+the string itself. Example:
+
+``` Cpp
+    auto s = to<fbstring>("Hello, world");
+    assert(s == "Hello, world");
+```
+
+#### Anything from string conversion (i.e. parsing)
+***
+
+`folly/Conv.h` includes three kinds of parsing routines:
+
+* `to<Type>(const char* begin, const char* end)` rigidly
+  converts the range [begin, end) to `Type` These routines have
+  drastic restrictions (e.g. allow no leading or trailing
+  whitespace) and are intended as an efficient back-end for more
+  tolerant routines.
+* `to<Type>(stringy)` converts `stringy` to `Type` Value
+  `stringy` may be of type `const char*`, `StringPiece`,
+  `std::string`, or `fbstring` (Technically, the requirement is
+  that `stringy` implicitly converts to a `StringPiece`
+* `to<Type>(&stringPiece)` parses with progress information:
+  given `stringPiece` of type `StringPiece` it parses as much
+  as possible from it as type `Type` and alters `stringPiece`
+  to remove the munched characters. This is easiest clarified
+  by an example:
+
+``` Cpp
+    fbstring s = " 1234 angels on a pin";
+    StringPiece pc(s);
+    auto x = to<int>(&pc);
+    assert(x == 1234);
+    assert(pc == " angels on a pin";
+```
+
+Note how the routine ate the leading space but not the trailing one.
+
+#### Parsing integral types
+
+Parsing integral types is unremarkable - decimal format is
+expected, optional `'+'` or `'-'` sign for signed types, but no
+optional `'+'` is allowed for unsigned types. The one remarkable
+element is speed - parsing typical `long` values is 6x faster than
+`sscanf`. `folly/Conv.h` uses aggressive loop unrolling and
+table-assisted SIMD-style code arrangement that avoids integral
+division (slow) and data dependencies across operations
+(ILP-unfriendly). Example:
+
+``` Cpp
+    fbstring str = "  12345  ";
+    assert(to<int>(str) == 12345);
+    str = "  12345six seven eight";
+    StringPiece pc(str);
+    assert(to<int>(&pc) == 12345);
+    assert(str == "six seven eight");
+```
+
+#### Parsing floating-point types
+
+`folly/Conv.h` uses, again, [V8's double-conversion](http://code.google.com/p/double-conversion/)
+routines as back-end. The speed is 3x faster than `sscanf` and
+1.7x faster than in-home routines such as `parse<double>` But
+the more important detail is accuracy - even if you do code a
+routine that works faster than `to<double>` chances are it is
+incorrect and will fail in a variety of corner cases. Using
+`to<double>` is strongly recommended.
+
+Note that if the string "NaN" (with any capitalization) is passed to
+`to<double>` then `NaN` is returned, which can be tested for as follows:
+
+``` Cpp
+    fbstring str = "nan"; // "NaN", "NAN", etc.
+    double d = to<double>(str);
+    if (std::isnan(d)) {
+      // string was a valid representation of the double value NaN
+    }
+```
+
+Note that passing "-NaN" (with any capitalization) to `to<double>` also returns
+`NaN`.
+
+Note that if the strings "inf" or "infinity" (with any capitalization) are
+passed to `to<double>` then `infinity` is returned, which can be tested for
+as follows:
+
+``` Cpp
+    fbstring str = "inf"; // "Inf", "INF", "infinity", "Infinity", etc.
+    double d = to<double>(str);
+    if (std::isinf(d)) {
+      // string was a valid representation of one of the double values +Infinity
+      // or -Infinity
+    }
+```
+
+Note that passing "-inf" or "-infinity" (with any capitalization) to
+`to<double>` returns `-infinity` rather than `+infinity`. The sign of the
+`infinity` can be tested for as follows:
+
+``` Cpp
+    fbstring str = "-inf"; // or "inf", "-Infinity", "+Infinity", etc.
+    double d = to<double>(str);
+    if (d == std::numeric_limits<double>::infinity()) {
+      // string was a valid representation of the double value +Infinity
+    } else if (d == -std::numeric_limits<double>::infinity()) {
+      // string was a valid representation of the double value -Infinity
+    }
+```
+
+Note that if an unparseable string is passed to `to<double>` then an exception
+is thrown, rather than `NaN` being returned.  This can be tested for as follows:
+
+``` Cpp
+    fbstring str = "not-a-double"; // Or "1.1.1", "", "$500.00", etc.
+    double d;
+    try {
+      d = to<double>(str);
+    } catch (const std::range_error &) {
+      // string could not be parsed
+    }
+```
+
+Note that the empty string (`""`) is an unparseable value, and will cause
+`to<double>` to throw an exception.
+
+#### Non-throwing interfaces
+
+`tryTo<T>` is the non-throwing variant of `to<T>`. It returns
+an `Expected<T, ConversionCode>`. You can think of `Expected`
+as like an `Optional<T>`, but if the conversion failed, `Expected`
+stores an error code instead of a `T`.
+
+`tryTo<T>` has similar performance as `to<T>` when the
+conversion is successful. On the error path, you can expect
+`tryTo<T>` to be roughly three orders of magnitude faster than
+the throwing `to<T>` and to completely avoid any lock contention
+arising from stack unwinding.
+
+Here is how to use non-throwing conversions:
+
+``` Cpp
+    auto t1 = tryTo<int>(str);
+    if (t1.hasValue()) {
+      use(t1.value());
+    }
+```
+
+`Expected` has a composability feature to make the above pattern simpler.
+
+``` Cpp
+    tryTo<int>(str).then([](int i) { use(i); });
+```

package/external/folly/folly/docs/Dynamic.md

@@ -0,0 +1,220 @@
+`folly/dynamic.h`
+-----------------
+
+`folly/dynamic.h` provides a runtime dynamically typed value for
+C++, similar to the way languages with runtime type systems work
+(e.g. Python). It can hold types from a predetermined set of types
+(ints, bools, arrays of other dynamics, etc), similar to something like
+`std::variant`, but the syntax is intended to be a little more like
+using the native type directly.
+
+### Overview
+***
+
+Here are some code samples to get started (assumes a `using
+folly::dynamic;` was used):
+
+``` Cpp
+    dynamic twelve = 12; // creates a dynamic that holds an integer
+    dynamic str = "string"; // yep, this one is an fbstring
+
+    // A few other types.
+    dynamic nul = nullptr;
+    dynamic boolean = false;
+
+    // Arrays can be initialized with dynamic::array.
+    dynamic array = dynamic::array("array ", "of ", 4, " elements");
+    assert(array.size() == 4);
+    dynamic emptyArray = dynamic::array;
+    assert(emptyArray.empty());
+
+    // Maps from dynamics to dynamics are called objects.  The
+    // dynamic::object constant is how you make an empty map from dynamics
+    // to dynamics.
+    dynamic map = dynamic::object;
+    map["something"] = 12;
+    map["another_something"] = map["something"] * 2;
+
+    // Dynamic objects may be initialized this way
+    dynamic map2 = dynamic::object("something", 12)("another_something", 24);
+```
+
+### Runtime Type Checking and Conversions
+***
+
+Any operation on a dynamic requires checking at runtime that the
+type is compatible with the operation. If it isn't, you'll get a
+`folly::TypeError`. Other exceptions can also be thrown if
+you try to do something impossible (e.g. if you put a very large
+64-bit integer in and try to read it out as a double).
+
+More examples should hopefully clarify this:
+
+``` Cpp
+    dynamic dint = 42;
+
+    dynamic str = "foo";
+    dynamic anotherStr = str + "something"; // fine
+    dynamic thisThrows = str + dint; // TypeError is raised
+```
+
+Explicit type conversions can be requested for some of the basic types:
+
+``` Cpp
+    dynamic dint = 12345678;
+    dynamic doub = dint.asDouble(); // doub will hold 12345678.0
+    dynamic str = dint.asString(); // str == "12345678"
+
+    dynamic hugeInt = std::numeric_limits<int64_t>::max();
+    dynamic hugeDoub = hugeInt.asDouble();  // throws a folly/Conv.h error,
+                                            // since it can't fit in a double
+```
+
+For more complicated conversions, see [DynamicConverter](DynamicConverter.md).
+
+### Comparison Operators and Hashing
+#### Equality Operators
+Equality operators (`==`, `!=`) are supported for all types.
+
+For dynamics of the same type, the underlying equality operator shall apply.
+
+For comparisons between different numeric types (double and int64), numeric
+equality will apply - thus `2.0 == 2`.
+
+Values of any other different types will be deemed to not be equal.
+
+#### Ordering operators
+Ordering operators (`<`, `<=`, `>`, `>=`) are supported for all types, except
+`dynamic::object` which will throw if it is involved in an ordering operator.
+
+For dynamics of the same type, the underlying ordering operator shall apply.
+
+For comparisons between different numeric types (double and int64), numeric
+ordering will apply - thus `1.5 < 2`.
+
+Ordering of values between other different types will maintain total ordering
+properties and be consistent within a given binary run, and thus safe for use in
+e.g. `std::set`. The actual ordering is undefined and could change across
+versions, thus a dependency should not be taken outside of the total ordering
+property within a given binary.
+
+#### Hashing
+Hashing is supported by all types, and the hashes of two values will match if
+they are equal per `dynamic::operator==`.
+
+As a result, numerical types have the same numerical hashing regardless of int64
+vs double - so e.g. `std::hash<dynamic>()(2)` will give the same value as
+`std::hash<dynamic>()(2.0)`.
+
+### Iteration and Lookup
+***
+
+You can iterate over dynamic arrays as you would over any C++ sequence container.
+
+``` Cpp
+    dynamic array = dynamic::array(2, 3, "foo");
+
+    for (auto& val : array) {
+      doSomethingWith(val);
+    }
+```
+
+You can iterate over dynamic maps by calling `items()`, `keys()`,
+`values()`, which behave similarly to the homonymous methods of Python
+dictionaries.
+
+``` Cpp
+    dynamic obj = dynamic::object(2, 3)("hello", "world")("x", 4);
+
+    for (auto& pair : obj.items()) {
+      // Key is pair.first, value is pair.second
+      processKey(pair.first);
+      processValue(pair.second);
+    }
+
+    for (auto& key : obj.keys()) {
+      processKey(key);
+    }
+
+    for (auto& value : obj.values()) {
+      processValue(value);
+    }
+```
+
+You can find an element by key in a dynamic map using the `find()` method,
+which returns an iterator compatible with `items()`:
+
+``` Cpp
+    dynamic obj = dynamic::object(2, 3)("hello", "world")("x", 4);
+
+    auto pos = obj.find("hello");
+    // pos->first is "hello"
+    // pos->second is "world"
+
+    auto pos = obj.find("no_such_key");
+    // pos == obj.items().end()
+```
+
+
+### Use for JSON
+***
+
+The original motivation for implementing this type was to try to
+make dealing with json documents in C++ almost as easy as it is
+in languages with dynamic type systems (php or javascript, etc).
+The reader can judge whether we're anywhere near that goal, but
+here's what it looks like:
+
+``` Cpp
+    // Parsing JSON strings and using them.
+    std::string jsonDocument = R"({"key":12,"key2":[false, null, true, "yay"]})";
+    dynamic parsed = folly::parseJson(jsonDocument);
+    assert(parsed["key"] == 12);
+    assert(parsed["key2"][0] == false);
+    assert(parsed["key2"][1] == nullptr);
+
+    // Building the same document programmatically.
+    dynamic sonOfAJ = dynamic::object
+      ("key", 12)
+      ("key2", dynamic::array(false, nullptr, true, "yay"));
+
+    // Printing.  (See also folly::toPrettyJson)
+    auto str = folly::toJson(sonOfAJ);
+    assert(jsonDocument.compare(str) == 0);
+```
+
+### Performance
+***
+
+Dynamic typing is more expensive than static typing, even when
+you do it in C++. ;)
+
+However, some effort has been made to keep `folly::dynamic` and
+the json (de)serialization at least reasonably performant for
+common cases. The heap is only used for arrays and objects, and
+move construction is fully supported. String formatting
+internally also uses the highly performant `folly::to<>` (see
+`folly/Conv.h`).
+
+A trade off to keep in mind though, is that
+`sizeof(folly::dynamic)` is 64 bytes. You probably don't want to
+use it if you need to allocate large numbers of them (prefer
+static types, etc).
+
+### Some Design Rationale
+***
+
+**Q. Why doesn't a dynamic string support begin(), end(), and operator[]?**
+
+The value_type of a dynamic iterator is `dynamic`, and `operator[]`
+(or the `at()` function) has to return a reference to a dynamic.  If
+we wanted this to work for strings, this would mean we'd have to
+support dynamics with a character type, and moreover that the internal
+representation of strings would be such that we can hand out
+references to dynamic as accessors on individual characters.  There
+are a lot of potential efficiency drawbacks with this, and it seems
+like a feature that is not needed too often in practice.
+
+**Q. Isn't this just a poor imitation of the C# language feature?**
+
+Pretty much.

package/external/folly/folly/docs/DynamicConverter.md

@@ -0,0 +1,71 @@
+`folly/DynamicConverter.h`
+--------------------------
+
+When dynamic objects contain data of a known type, it is sometimes
+useful to have its well-typed representation. A broad set of
+type-conversions are contained in `DynamicConverter.h`, and
+facilitate the transformation of dynamic objects into their well-typed
+format.
+
+### Usage
+***
+
+Simply pass a dynamic into a templated convertTo:
+
+```cpp
+    dynamic d = { { 1, 2, 3 }, { 4, 5 } }; // a vector of vector of int
+    auto vvi = convertTo<fbvector<fbvector<int>>>(d);
+```
+
+### Supported Types
+***
+
+convertTo naturally supports conversions to
+
+1. arithmetic types (such as int64_t, unsigned short, bool, and double)
+2. fbstring, std::string
+3. containers and map-containers
+
+NOTE:
+
+convertTo<Type> will assume that Type is a container if
+* it has a Type::value_type, and
+* it has a Type::iterator, and
+* it has a constructor that accepts two InputIterators
+
+Additionally, convertTo<Type> will assume that Type is a map if
+* it has a Type::key_type, and
+* it has a Type::mapped_type, and
+* value_type is a pair of const key_type and mapped_type
+
+If Type meets the container criteria, then it will be constructed
+by calling its InputIterator constructor.
+
+### Customization
+***
+
+If you want to use convertTo to convert dynamics into your own custom
+class, then all you have to do is provide a template specialization
+of DynamicConverter with the static method convert. Make sure you put it
+in namespace folly.
+
+Example:
+
+``` Cpp
+    struct Token {
+      int kind_;
+      fbstring lexeme_;
+      
+      explicit Token(int kind, const fbstring& lexeme)
+        : kind_(kind), lexeme_(lexeme) {}
+    };
+    namespace folly {
+    template <> struct DynamicConverter<Token> {
+      static Token convert(const dynamic& d) {
+        int k = convertTo<int>(d["KIND"]);
+        fbstring lex = convertTo<fbstring>(d["LEXEME"]);
+        return Token(k, lex);
+      }
+    };
+    }
+```

package/external/folly/folly/docs/Executors.md

@@ -0,0 +1,63 @@
+<section class="dex_document"><h1>Thread pools &amp; Executors</h1><p class="dex_introduction">Run your concurrent code in a performant way</p><h2 id="all-about-thread-pools">All about thread pools <a href="#all-about-thread-pools" class="headerLink">#</a></h2>
+
+<h3 id="how-do-i-use-the-thread">How do I use the thread pools? <a href="#how-do-i-use-the-thread" class="headerLink">#</a></h3>
+
+<p>Wangle provides two concrete thread pools (IOThreadPoolExecutor, CPUThreadPoolExecutor) as well as building them in as part of a complete async framework.  Generally you might want to grab the global executor, and use it with a future, like this:</p>
+
+<div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code"><span class="no">auto</span> <span class="no">f</span> <span class="o">=</span> <span class="nf" data-symbol-name="someFutureFunction">someFutureFunction</span><span class="o">().</span><span class="nf" data-symbol-name="via">via</span><span class="o">(</span><span class="nf" data-symbol-name="getCPUExecutor">getCPUExecutor</span><span class="o">()).</span><span class="nf" data-symbol-name="then">then</span><span class="o">(...)</span></pre></div>
+
+<p>Or maybe you need to construct a thrift/memcache client, and need an event base:</p>
+
+<div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code"><span class="no">auto</span> <span class="no">f</span> <span class="o">=</span> <span class="nf" data-symbol-name="getClient">getClient</span><span class="o">(</span><span class="nf" data-symbol-name="getIOExecutor">getIOExecutor</span><span class="o">()-&gt;</span><span class="na" data-symbol-name="getEventBase">getEventBase</span><span class="o">())-&gt;</span><span class="na" data-symbol-name="callSomeFunction">callSomeFunction</span><span class="o">(</span><span class="no">args</span><span class="o">...)</span>
+         <span class="o">.</span><span class="nf" data-symbol-name="via">via</span><span class="o">(</span><span class="nf" data-symbol-name="getCPUExecutor">getCPUExecutor</span><span class="o">())</span>
+         <span class="o">.</span><span class="nf" data-symbol-name="then">then</span><span class="o">([](</span><span class="no">Result</span> <span class="no">r</span><span class="o">)&#123;</span> <span class="o">....</span> <span class="k">do</span> <span class="no">something</span> <span class="no">with</span> <span class="no">result</span><span class="o">&#125;);</span></pre></div>
+
+<h3 id="vs-c-11-s-std-launch">vs. C++11&#039;s std::launch <a href="#vs-c-11-s-std-launch" class="headerLink">#</a></h3>
+
+<p>The current C++11 std::launch only has two modes: async or deferred.  In a production system, neither is what you want:  async will launch a new thread for every launch without limit, while deferred will defer the work until it is needed lazily, but then do the work <strong>in the current thread synchronously</strong> when it is needed.</p>
+
+<p>Wangle&#039;s thread pools always launch work as soon as possible, have limits to the maximum number of tasks / threads allowed, so we will never use more threads than absolutely needed.  See implementation details below about each type of executor.</p>
+
+<h3 id="why-do-we-need-yet-anoth">Why do we need yet another set of thread pools? <a href="#why-do-we-need-yet-anoth" class="headerLink">#</a></h3>
+
+<p>Unfortunately none of the existing thread pools had every feature needed - things based on pipes are too slow.   Several older ones didn&#039;t support std::function.</p>
+
+<h3 id="why-do-we-need-several-d">Why do we need several different types of thread pools? <a href="#why-do-we-need-several-d" class="headerLink">#</a></h3>
+
+<p>If you want epoll support, you need an fd - event_fd is the latest notification hotness.   Unfortunately, an active fd triggers all the epoll loops it is in, leading to thundering herd - so if you want a fair queue (one queue total vs. one queue per worker thread), you need to use some kind of semaphore.  Unfortunately semaphores can&#039;t be put in epoll loops, so they are incompatible with IO.   Fortunately, you usually want to separate the IO and CPU bound work anyway to give stronger tail latency guarantees on IO.</p>
+
+<h3 id="iothreadpoolexecutor">IOThreadPoolExecutor <a href="#iothreadpoolexecutor" class="headerLink">#</a></h3>
+
+<ul>
+<li>Uses event_fd for notification, and waking an epoll loop.</li>
+<li>There is one queue (NotificationQueue specifically) per thread/epoll.</li>
+<li>If the thread is already running and not waiting on epoll, we don&#039;t make any additional syscalls to wake up the loop, just put the new task in the queue.</li>
+<li>If any thread has been waiting for more than a few seconds, its stack is madvised away.   Currently however tasks are scheduled round robin on the queues, so unless there is <strong>no</strong> work going on, this isn&#039;t very effective.</li>
+<li>::getEventBase() will return an EventBase you can schedule IO work on directly, chosen round-robin.</li>
+<li>Since there is one queue per thread, there is hardly any contention on the queues - so a simple spinlock around an std::deque is used for the tasks.  There is no max queue size.</li>
+<li>By default, there is one thread per core - it usually doesn&#039;t make sense to have more IO threads than this, assuming they don&#039;t block.</li>
+</ul>
+
+<h3 id="cputhreadpoolexecutor">CPUThreadPoolExecutor <a href="#cputhreadpoolexecutor" class="headerLink">#</a></h3>
+
+<ul>
+<li>A single queue backed by folly/LifoSem and folly/MPMC queue.  Since there is only a single queue, contention can be quite high, since all the worker threads and all the producer threads hit the same queue.  MPMC queue excels in this situation.  MPMC queue dictates a max queue size.</li>
+<li>LifoSem wakes up threads in Lifo order - i.e. there are only few threads as necessary running, and we always try to reuse the same few threads for better cache locality.</li>
+<li>Inactive threads have their stack madvised away.  This works quite well in combination with Lifosem - it almost doesn&#039;t matter if more threads than are necessary are specified at startup.</li>
+<li>stop() will finish all outstanding tasks at exit</li>
+<li>Supports priorities - priorities are implemented as multiple queues - each worker thread checks the highest priority queue first.  Threads themselves don&#039;t have priorities set, so a series of long running low priority tasks could still hog all the threads.  (at last check pthreads thread priorities didn&#039;t work very well)</li>
+</ul>
+
+<h3 id="threadpoolexecutor">ThreadPoolExecutor <a href="#threadpoolexecutor" class="headerLink">#</a></h3>
+
+<p>Base class that contains the thread startup/shutdown/stats logic, since this is pretty disjoint from how tasks are actually run</p>
+
+<h3 id="observers">Observers <a href="#observers" class="headerLink">#</a></h3>
+
+<p>An observer interface is provided to listen for thread start/stop events.  This is useful to create objects that should be one-per-thread, but also have them work correctly if threads are added/removed from the thread pool.</p>
+
+<h3 id="stats">Stats <a href="#stats" class="headerLink">#</a></h3>
+
+<p>PoolStats are provided to get task count, running time, waiting time, etc.</p>
+</section>
+