react-native-windows 0.81.35 → 0.81.37

package/external/folly/folly/docs/Format.md

@@ -0,0 +1,177 @@
+`folly/Format.h`
+----------------
+
+`folly/Format.h` provides a fast, powerful, type-safe, flexible facility
+for formatting text, using a specification language similar to Python's
+[str.format](http://docs.python.org/library/string.html#formatstrings).
+By default, it can format strings, numbers (integral and floating point),
+and dynamically-typed `folly::dynamic` objects, and can extract values from
+random-access containers and string-keyed maps.  In many cases, `format` is
+faster than `sprintf` as well as being fully type-safe.
+
+### Overview
+***
+
+Here are some code samples to get started:
+
+``` Cpp
+using folly::format;
+using folly::sformat;
+
+// Objects produced by format() can be streamed without creating
+// an intermediary string; {} yields the next argument using default
+// formatting.
+std::cout << format("The answers are {} and {}", 23, 42);
+// => "The answers are 23 and 42"
+
+// If you just want the string, though, you're covered.
+std::string result = sformat("The answers are {} and {}", 23, 42);
+// => "The answers are 23 and 42"
+
+// To insert a literal '{' or '}', just double it.
+std::cout << format("{} {{}} {{{}}}", 23, 42);
+// => "23 {} {42}"
+
+// Arguments can be referenced out of order, even multiple times
+std::cout << format("The answers are {1}, {0}, and {1} again", 23, 42);
+// => "The answers are 42, 23, and 42 again"
+
+// It's perfectly fine to not reference all arguments
+std::cout << format("The only answer is {1}", 23, 42);
+// => "The only answer is 42"
+
+// Values can be extracted from indexable containers
+// (random-access sequences and integral-keyed maps), and also from
+// string-keyed maps
+std::vector<int> v {23, 42};
+std::map<std::string, std::string> m { {"what", "answer"} };
+std::cout << format("The only {1[what]} is {0[1]}", v, m);
+// => "The only answer is 42"
+
+// format works with pairs and tuples
+std::tuple<int, std::string, int> t {42, "hello", 23};
+std::cout << format("{0} {2} {1}", t);
+// => "42 23 hello"
+
+// Format supports width, alignment, arbitrary fill, and various
+// format specifiers, with meanings similar to printf
+// "X<10": fill with 'X', left-align ('<'), width 10
+std::cout << format("{:X<10} {}", "hello", "world");
+// => "helloXXXXX world"
+
+// Field width may be a runtime value rather than part of the format string
+int x = 6;
+std::cout << format("{:-^*}", x, "hi");
+// => "--hi--"
+
+// Explicit arguments work with dynamic field width, as long as indexes are
+// given for both the value and the field width.
+std::cout << format("{2:+^*0}",
+9, "unused", 456); // => "+++456+++"
+
+// Format supports printf-style format specifiers
+std::cout << format("{0:05d} decimal = {0:04x} hex", 42);
+// => "00042 decimal = 002a hex"
+
+// Formatter objects may be written to a string using folly::to or
+// folly::toAppend (see folly/Conv.h), or by calling their appendTo(),
+// and str() methods
+std::string s = format("The only answer is {}", 42).str();
+std::cout << s;
+// => "The only answer is 42"
+
+// Decimal precision usage
+std::cout << format("Only 2 decimals is {:.2f}", 23.34134534535);
+// => "Only 2 decimals is 23.34"
+```
+
+
+### Format string syntax
+***
+
+Format string (`format`):
+`"{" [arg_index] ["[" key "]"] [":" format_spec] "}"`
+
+- `arg_index`: index of argument to format; default = next argument.  Note
+  that a format string may have either default argument indexes or
+  non-default argument indexes, but not both (to avoid confusion).
+- `key`: if the argument is a container (C-style array or pointer,
+  `std::array`, vector, deque, map), you may use this
+  to select the element to format; works with random-access sequences and
+  integer- and string-keyed maps.  Multiple level keys work as well, with
+  components separated with "."; for example, given
+  `map<string, map<string, string>> m`, `{[foo.bar]}` selects
+  `m["foo"]["bar"]`.
+- `format_spec`: format specification, see below
+
+Format specification:
+`[[fill] align] [sign] ["#"] ["0"] [width] [","] ["." precision] ["."] [type]`
+
+- `fill` (may only be specified if `align` is also specified): pad with this
+  character ('` `' (space) or '`0`' (zero) might be useful; space is default)
+- `align`: one of '`<`', '`>`', '`=`', '`^`':
+    - '`<`': left-align (default for most objects)
+    - '`>`': right-align (default for numbers)
+    - '`=`': pad after sign, but before significant digits; used to print
+            `-0000120`; only valid for numbers
+    - '`^`': center
+- `sign`: one of '`+`', '`-`', ' ' (space) (only valid for numbers)
+    - '`+`': output '`+`' if positive or zero, '`-`' if negative
+    - '`-`': output '`-`' if negative, nothing otherwise (default)
+    - '` `' (space): output '` `' (space) if positive or zero, '`-`' if negative
+- '`#`': output base prefix (`0` for octal, `0b` or `0B` for binary, `0x` or
+  `0X` for hexadecimal; only valid for integers)
+- '`0`': 0-pad after sign, same as specifying "`0=`" as the `fill` and
+  `align` parameters (only valid for numbers)
+- `width`: minimum field width. May be '`*`' to indicate that the field width
+  is given by an argument. Defaults to the next argument (preceding the value
+  to be formatted) but an explicit argument index may be given following the
+  '`*`'.
+- '`,`' (comma): output comma as thousands' separator (only valid for integers,
+  and only for decimal output)
+- `precision` (not allowed for integers):
+    - for floating point values, number of digits after decimal point ('`f`' or
+      '`F`' presentation) or number of significant digits ('`g`' or '`G`')
+    - for others, maximum field size (truncate subsequent characters)
+- '`.`' (when used after precision or in lieu of precison): Forces a trailing
+  decimal point to make it clear this is a floating point value.
+- `type`: presentation format, see below
+
+Presentation formats:
+
+- Strings (`folly::StringPiece`, `std::string`, `folly::fbstring`,
+  `const char*`):
+    - '`s`' (default)
+- Integers:
+    - '`b`': output in binary (base 2) ("`0b`" prefix if '`#`' specified)
+    - '`B`': output in binary (base 2) ("`0B`" prefix if '`#`' specified)
+    - '`c`': output as a character (cast to `char`)
+    - '`d`': output in decimal (base 10) (default)
+    - '`o`': output in octal (base 8)
+    - '`O`': output in octal (base 8) (same as '`o`')
+    - '`x`': output in hexadecimal (base 16) (lower-case digits above 9)
+    - '`X`': output in hexadecimal (base 16) (upper-case digits above 9)
+    - '`n`': locale-aware output (currently same as '`d`')
+- `bool`:
+    - default: output "`true`" or "`false`" as strings
+    - integer presentations allowed as well
+- `char`:
+    - same as other integers, but default is '`c`' instead of '`d`'
+- Floating point (`float`, `double`; `long double` is not implemented):
+    - '`e`': scientific notation using '`e`' as exponent character
+    - '`E`': scientific notation using '`E`' as exponent character
+    - '`f`': fixed point
+    - '`F`': fixed point (same as '`f`')
+    - '`g`': general; use either '`f`' or '`e`' depending on magnitude (default)
+    - '`G`': general; use either '`f`' or '`E`' depending on magnitude
+    - '`n`': locale-aware version of '`g`' (currently same as '`g`')
+    - '`%`': percentage: multiply by 100 then display as '`f`'
+
+
+### Extension
+***
+
+You can extend `format` for your own class by providing a specialization for
+`folly::FormatValue`.  See `folly/Format.h` and `folly/FormatArg.h` for
+details, and the existing specialization for `folly::dynamic` in
+`folly/dynamic-inl.h` for an implementation example.

package/external/folly/folly/docs/Function.md

@@ -0,0 +1,92 @@
+`folly/Function.h`
+------------------
+
+`folly::Function` is a polymorphic function wrapper that is not copyable and does not require the wrapped function to be copy constructible. It is similar to `std::function`, but different with respect to some interesting features.
+
+There are some limitations in `std::function` that `folly::Function` tries to avoid. `std::function` is copy-constructible and requires that the callable that it wraps is copy-constructible as well, which is a constraint that is often inconvenient. In most cases when using a `std::function` you don't make use of its copy-constructibility, so you might sometimes feel like you get back very little in return for a noticeable restriction.
+
+This restriction becomes apparent when trying to use a lambda capturing a `unique_ptr` (or any non-copyable type) as a callback for a folly::Future.
+``` Cpp
+std::unique_ptr<Foo> foo_ptr = new Foo;
+
+some_future.then(
+    [foo_ptr = std::move(foo_ptr)] mutable
+    (int x)
+    { foo_ptr->setX(x); }
+);
+```
+This piece of code did not compile before `folly::Future` started using `folly::Function` instead of `std::function` to store the callback. Because the lambda captures something non-copyable (the `unique_ptr`), it is not copyable itself. And `std::function` can only store copyable callables.
+
+The implementation of folly::Future did not make use of the copy-constructibility of `std::function` at any point. There was no benefit from the fact that the `std::function` is copy-constructible, but the fact that it can only wrap copy-constructible callables posed a restriction.
+
+A workaround was available: `folly::MoveWrapper`, which wraps an object that may be non-copyable and implements copy operations by moving the embedded object. Using a `folly::MoveWrapper`, you can capture non-copyable objects in a lambda, and the lambda itself is still copyable and may be wrapped in a `std::function`. It is a pragmatic solution for the above problem, but you have to be a little careful. The problem is that you can’t use a `MoveWrapper` anywhere where copy operations are assumed to behave like actual copy operations. Also, a `folly::MoveWrapper<std::unique_ptr<T>>` essentially behaves like `auto_ptr<T>`. Ask yourself whether you’d want to use lots of `auto_ptr`s in your codebase. And the original question still persists: we very often don’t benefit from copy-constructibility of `std::function`, so why do we have to live with this restriction? I.e. why do we have to use `MoveWrapper`?
+
+`folly::Function` is an actual solution to this problem, as it can wrap non-copyable callables, at the cost of not being copy-constructible, which more often than not is not a relevant restriction. `folly::Future` now uses `folly::Function` to store callbacks, so the good news is: the code example from the top of this note is becoming a perfectly valid way to use future callbacks. The code compiles and behaves as you would expect.
+
+Here are more details about `folly::Function`: much like `std::function`, it wraps an arbitrary object that can be invoked like a given function type. E.g. a `folly::Function<int(std::string, double)>` can wrap any callable object that returns an `int` (or something that is convertible to an `int`) when invoked with a `std::string` and a `double` argument. The function type is a template parameter of `folly::Function`, but the specific type of the callable is not.
+
+Other than copyability, there is one more significant difference between `std::function` and `folly::Function`, and it concerns const-correctness. `std::function` does not enforce const-correctness: it allows you to store mutable callables (i.e. callables that may change their inner state when executed, such as a mutable lambda) and call them in a const context (i.e. when you only have access to a const reference to the `std::function` object). For example:
+``` Cpp
+class FooBar {
+ public:
+  void call_func() const {
+    func_();
+  }
+ private:
+  std::function<void()> func_;
+};
+```
+The `call_func` member function is declared const. However, when it calls `func_()`, it may change the inner state of `func_`, and thereby the inner state of the `FooBar` object. Inside the `FooBar` class, `func_` is like a non-const method that is callable from const methods.
+
+Some people consider `std::function` in the standard broken with respect to this. (Paper N4348 explains this problem in more detail.) It also lists possible ways to fix the problem. `folly::Function`, however, goes a different way: you have to declare whether you want to store a const function, in which case you can invoke any reference (const or non-const) of the `folly::Function`, or a non-const (mutable) function, in which case you need a non-const reference to the `folly::Function` to be able to invoke it. In the above example, let’s say that `func_` stores a const function, which makes it okay that it gets invoked from `call_func` (a const method). Instead of `std::function`, you could use `folly::Function<void() const>` for the `func_` member.
+
+Const-ness is part of a function type. To illustrate:
+``` Cpp
+class Foo {
+ public:
+  int operator()() { return 1; }
+  int operator()(char const*) { return 2; }
+  int operator()(int) { return 3; }
+  int operator()(int) const { return 4; }
+  int operator()(int, int) const { return 5; }
+};
+```
+You can overload methods multiple times using different argument signatures. Const-ness is part of that signature, so even for the same set of argument types you can overload a const and a non-const version. It’s not even particularly unusual to do that. Take for instance the `begin()` method of STL container types: `begin()` returns an `iterator`, `begin() const` returns a `const_iterator`. `folly::Function` allows you to select a specific overload easily:
+``` Cpp
+folly::Function<int()> uf1 = Foo();
+// uf1() returns 1
+folly::Function<int(char const*)> uf2 = Foo();
+// uf2() returns 2
+folly::Function<int(int)> uf3 = Foo();
+// uf3() returns 3
+folly::Function<int(int) const> uf4 = Foo();
+// uf4() returns 4
+folly::Function<int(int, int) const> uf5 = Foo();
+// uf5() returns 5
+```
+If `cfoo` is a const-reference to a `Foo` object, `cfoo(int)` returns 4. If `foo` is a non-const reference to a `Foo` object, `foo(int)` returns 3. Normal const-to-non-const conversion behavior applies: if you call `foo(int, int)` it will return 5: a non-const reference will invoke the const method if no non-const method is defined. Which leads to the following behavior:
+``` Cpp
+folly::Function<int(int, int)> uf5nc = Foo();
+// uf5nc() returns 5
+```
+If you are wondering if the introduction of const function types means that you have to change lots of normal function types to const function types if you want to use `folly::Function`: not really, or at least not as much as you might think. There are only two reasons to use a `folly::Function` with a const function type:
+* a callable object defines both const and non-const `operator()` and you explicitly want to select the const one
+* you need to invoke a `folly::Function` from a const context (i.e. you only have a const reference to the `folly::Function`)
+
+In practice, you will not need the const variant very often. Adding const to a function type adds a restriction for the callable: it must not change its inner state when invoked. If you don’t care whether it does or not, don’t worry about const!
+
+A `folly::Function<R(Args...) const>` can be converted into a `folly::Function<R(Args...)>`: either way the stored callable will not change its inner state when invoked. The former type expresses and guarantees that, the latter does not. When you get rid of the const, the selected function stays the same:
+``` Cpp
+folly::Function<int(int)> uf4nc = std::move(uf4);
+// uf4nc() returns 4, not 3!
+```
+If you want to go the other way, you are talking about a (potentially dangerous) const cast: a callable that may or may not change its inner state is declared as one that guarantees not to do that. Proceed at your own risk! This conversion does not happen implicitly, though:
+``` Cpp
+folly::Function<int() const> uf1c = folly::constCastFunction(std::move(uf1));
+// uf1c() returns 1
+```
+Admittedly, seeing const function types as template parameters is unfamiliar. As far as I am aware it happens nowhere in the standard library. But it is the most consistent way to deal with the issue of const-correctness here. Const qualifiers are part of a function type, as a matter of fact. If you require a const-qualified function to be wrapped in a `folly::Function`, just declare it as that! More often than not you will find that you do not need the const qualifier. While writing the `folly::Function` implementation, a good set of unit tests had existed before the const function types got introduced. Not a single one of those unit tests had to be changed: they all compiled and passed after the introduction of const function types. Obviously new ones were added to test the const-correctness. But in your day-to-day use of `folly::Function` you won’t have to worry about const very often.
+
+Memory usage
+============
+Like most implementations of `std::function`, `folly::Function` stores small callable objects in-line and larger callable objects will be stored on the heap. `folly::Function` returns the size of the allocation it has made from its `heapAllocatedMemory()` member function; naturally it will return `0` when the callable is stored in-line.

package/external/folly/folly/docs/Futures.md

@@ -0,0 +1,263 @@
+# Futures
+
+### Futures is a framework for expressing asynchronous code in C++ using the Promise/Future pattern.
+
+# Overview
+
+Folly Futures is an async C++ framework inspired by [Twitter's Futures](https://twitter.github.io/finagle/guide/Futures.html) implementation in Scala (see also [Future.scala](https://github.com/twitter/util/blob/master/util-core/src/main/scala/com/twitter/util/Future.scala), [Promise.scala](https://github.com/twitter/util/blob/master/util-core/src/main/scala/com/twitter/util/Promise.scala), and friends), and loosely builds upon the existing but anemic Futures code found in the C++11 standard ([std::future](https://en.cppreference.com/w/cpp/thread/future)) and [boost::future](https://www.boost.org/doc/libs/1_53_0/doc/html/thread/synchronization.html#thread.synchronization.futures) (especially >= 1.53.0). Although inspired by the C++11 std::future interface, it is not a drop-in replacement because some ideas don't translate well enough to maintain API compatibility.
+
+The primary difference from std::future is that you can attach callbacks to Futures (with `thenValue` or `thenTry`), under the control of an executor to manage where work runs, which enables sequential and parallel composition of Futures for cleaner asynchronous code.
+
+# Brief Synopsis
+
+```cpp
+#include <folly/futures/Future.h>
+#include <folly/executors/ThreadedExecutor.h>
+using namespace folly;
+using namespace std;
+
+void foo(int x) {
+  // do something with x
+  cout << "foo(" << x << ")" << endl;
+}
+
+// ...
+  folly::ThreadedExecutor executor;
+  cout << "making Promise" << endl;
+  Promise<int> p;
+  Future<int> f = p.getSemiFuture().via(&executor);
+  auto f2 = move(f).thenValue(foo);
+  cout << "Future chain made" << endl;
+
+// ... now perhaps in another event callback
+
+  cout << "fulfilling Promise" << endl;
+  p.setValue(42);
+  move(f2).get();
+  cout << "Promise fulfilled" << endl;
+```
+
+This would print:
+
+```
+making Promise
+Future chain made
+fulfilling Promise
+foo(42)
+Promise fulfilled
+```
+
+## Blog Post
+
+In addition to this document, there is [a blog post on code.facebook.com (June
+2015)](https://code.facebook.com/posts/1661982097368498/futures-for-c-11-at-facebook/).
+
+# Brief guide
+This brief guide covers the basics. For a more in-depth coverage skip to the appropriate section.
+
+Let's begin with an example using an imaginary simplified Memcache client interface:
+
+```cpp
+using std::string;
+class MemcacheClient {
+ public:
+  struct GetReply {
+    enum class Result {
+      FOUND,
+      NOT_FOUND,
+      SERVER_ERROR,
+    };
+
+    Result result;
+    // The value when result is FOUND,
+    // The error message when result is SERVER_ERROR or CLIENT_ERROR
+    // undefined otherwise
+    string value;
+  };
+
+  GetReply get(string key);
+};
+```
+
+This API is synchronous, i.e. when you call `get()` you have to wait for the result. This is very simple, but unfortunately it is also very easy to write very slow code using synchronous APIs.
+
+Now, consider this traditional asynchronous signature for the same operation:
+
+```cpp
+int async_get(string key, std::function<void(GetReply)> callback);
+```
+
+When you call `async_get()`, your asynchronous operation begins and when it finishes your callback will be called with the result. Very performant code can be written with an API like this, but for nontrivial applications the code devolves into a special kind of spaghetti code affectionately referred to as "callback hell".
+
+The Future-based API looks like this:
+
+```cpp
+SemiFuture<GetReply> future_get(string key);
+```
+
+A `SemiFuture<GetReply>` or `Future<GetReply>` is a placeholder for the `GetReply` that we will eventually get. For most of the descriptive text below, Future can refer to either `folly::SemiFuture` or `folly::Future` as the former is a safe subset of the latter. A Future usually starts life out "unfulfilled", or incomplete, i.e.:
+
+```cpp
+fut.isReady() == false
+fut.value()  // will throw an exception because the Future is not ready
+```
+
+At some point in the future, the `Future` will have been fulfilled, and we can access its value.
+
+```cpp
+fut.isReady() == true
+GetReply& reply = fut.value();
+```
+
+Futures support exceptions. If the asynchronous producer fails with an exception, your Future may represent an exception instead of a value. In that case:
+
+```cpp
+fut.isReady() == true
+fut.value() // will rethrow the exception
+```
+
+Just what is exceptional depends on the API. In our example we have chosen not to raise exceptions for `SERVER_ERROR`, but represent this explicitly in the `GetReply` object. On the other hand, an astute Memcache veteran would notice that we left `CLIENT_ERROR` out of `GetReply::Result`, and perhaps a `CLIENT_ERROR` would have been raised as an exception, because `CLIENT_ERROR` means there's a bug in the library and this would be truly exceptional. These decisions are judgement calls by the API designer. The important thing is that exceptional conditions (including and especially spurious exceptions that nobody expects) get captured and can be handled higher up the "stack".
+
+So far we have described a way to initiate an asynchronous operation via an API that returns a Future, and then sometime later after it is fulfilled, we get its value. This is slightly more useful than a synchronous API, but it's not yet ideal. There are two more very important pieces to the puzzle.
+
+First, we can aggregate Futures, to define a new Future that completes after some or all of the aggregated Futures complete. Consider two examples: fetching a batch of requests and waiting for all of them, and fetching a group of requests and waiting for only one of them.
+
+```cpp
+MemcacheClient mc;
+
+vector<SemiFuture<GetReply>> futs;
+for (auto& key : keys) {
+  futs.push_back(mc.future_get(key));
+}
+auto all = collectAll(futs.begin(), futs.end());
+
+vector<SemiFuture<GetReply>> futs;
+for (auto& key : keys) {
+  futs.push_back(mc.future_get(key));
+}
+auto any = collectAny(futs.begin(), futs.end());
+
+vector<SemiFuture<GetReply>> futs;
+for (auto& key : keys) {
+  futs.push_back(mc.future_get(key));
+}
+auto anyv = collectAnyWithoutException(futs.begin(), futs.end());
+```
+
+`all` and `any` are Futures (for the exact type and usage see the header files). They will be complete when all/one of futs are complete, respectively. (There is also `collectN()` for when you need some, and `collectAnyWithoutException` when you need one value if some value would be available.)
+
+Second, we can associate a Future with an executor. An executor specifies where work will run, and we detail this more later. In summary, given an executor we can convert a `SemiFuture` to a `Future` with an executor, or a `Future` on one executor to a `Future` on another executor.
+
+For example:
+
+```cpp
+folly::ThreadedExecutor executor;
+SemiFuture<GetReply> semiFut = mc.future_get("foo");
+Future<GetReply> fut1 = std::move(semiFut).via(&executor);
+```
+
+Once an executor is attached, a `Future` allows continuations to be attached and chained together monadically. An example will clarify:
+
+```cpp
+SemiFuture<GetReply> semiFut = mc.future_get("foo");
+Future<GetReply> fut1 = std::move(semiFut).via(&executor);
+
+Future<string> fut2 = std::move(fut1).thenValue(
+  [](GetReply reply) {
+    if (reply.result == MemcacheClient::GetReply::Result::FOUND)
+      return reply.value;
+    throw SomeException("No value");
+  });
+
+Future<Unit> fut3 = std::move(fut2)
+  .thenValue([](string str) {
+    cout << str << endl;
+  })
+  .thenTry([](folly::Try<string> strTry) {
+    cout << strTry.value() << endl;
+  })
+  .thenError(folly::tag_t<std::exception>{}, [](std::exception const& e) {
+    cerr << e.what() << endl;
+  });
+```
+
+That example is a little contrived but the idea is that you can transform a result from one type to another, potentially in a chain, and unhandled errors propagate. Of course, the intermediate variables are optional.
+
+Using `.thenValue` or `.thenTry` to add callbacks is idiomatic. It brings all the code into one place, which avoids callback hell. `.thenValue` appends a continuation that takes `T&&` for some `Future<T>` and an error bypasses the callback and is passed to the next, `thenTry` takes a callback taking `folly::Try<T>` which encapsulates both value and exception. `thenError(tag_t<ExceptionType>{},...` will bypass a value and only run if there is an exception, the `ExceptionType` template parameter to the tag type allows filtering by exception type; `tag_t<ExceptionType>{}` is optional and if no tag is passed passed the function will be parameterized with a `folly::exception_wrapper`. For C++17 there is a global inline variable and `folly::tag<ExceptionType>` may be passed directly without explicit construction.
+
+
+
+Up to this point we have skirted around the matter of waiting for Futures. You may never need to wait for a Future, because your code is event-driven and all follow-up action happens in a then-block. But if want to have a batch workflow, where you initiate a batch of asynchronous operations and then wait for them all to finish at a synchronization point, then you will want to wait for a Future. Futures have a blocking method called `wait()` that does exactly that and optionally takes a timeout.
+
+Futures are partially threadsafe. A Promise or Future can migrate between threads as long as there's a full memory barrier of some sort. `Future::thenValue` and `Promise::setValue` (and all variants that boil down to those two calls) can be called from different threads. **But**, be warned that you might be surprised about which thread your callback executes on. Let's consider an example, where we take a future straight from a promise, without going via the safer SemiFuture, and where we therefore have a `Future` that does not carry an executor. This is in general something to avoid.
+
+```cpp
+// Thread A
+Promise<Unit> p;
+auto f = p.getFuture();
+
+// Thread B
+std::move(f).thenValue(x).thenValue(y).thenTry(z);
+
+// Thread A
+p.setValue();
+```
+
+This is legal and technically threadsafe. However, it is important to realize that you do not know in which thread `x`, `y`, and/or `z` will execute. Maybe they will execute in Thread A when `p.setValue()` is called. Or, maybe they will execute in Thread B when `f.thenValue` is called. Or, maybe `x` will execute in Thread A, but `y` and/or `z` will execute in Thread B. There's a race between `setValue` and `then`—whichever runs last will execute the callback. The only guarantee is that one of them will run the callback.
+
+For safety, `.via` should be preferred. We can chain `.via` operations to give very strong control over where callbacks run:
+
+```cpp
+std::move(aFuture)
+  .thenValue(x)
+  .via(e1).thenValue(y1).thenValue(y2)
+  .via(e2).thenValue(z);
+```
+
+`x` will execute in the context of the executor associated with `aFuture`. `y1` and `y2` will execute in the context of `e1`, and `z` will execute in the context of `e2`. If after `z` you want to get back to the original context, you need to get there with a call to `via` passing the original executor.
+
+# You make me Promises, Promises
+
+If you are wrapping an asynchronous operation, or providing an asynchronous API to users, then you will want to make `Promise`s. Every Future has a corresponding Promise (except Futures that spring into existence already completed, with `makeFuture()`). Promises are simple: you make one, you extract the Future, and you fulfill it with a value or an exception. Example:
+
+```cpp
+Promise<int> p;
+SemiFuture<int> f = p.getSemiFuture();
+
+f.isReady() == false
+
+p.setValue(42);
+
+f.isReady() == true
+f.value() == 42
+```
+
+and an exception example:
+
+```cpp
+Promise<int> p;
+SemiFuture<int> f = p.getSemiFuture();
+
+f.isReady() == false
+
+p.setException(std::runtime_error("Fail"));
+
+f.isReady() == true
+f.value() // throws the exception
+```
+
+It's good practice to use setWith which takes a function and automatically captures exceptions, e.g.
+
+```cpp
+Promise<int> p;
+p.setWith([]{
+  try {
+    // do stuff that may throw
+    return 42;
+  } catch (MySpecialException const& e) {
+    // handle it
+    return 7;
+  }
+  // Any exceptions that we didn't catch, will be caught for us
+});
+```

package/external/folly/folly/docs/GroupVarint.md

@@ -0,0 +1,46 @@
+`folly/GroupVarint.h`
+---------------------
+
+`folly/GroupVarint.h` is an implementation of variable-length encoding for 32-
+and 64-bit integers using the Group Varint encoding scheme as described in
+Jeff Dean's [WSDM 2009 talk][wsdm] and in [Information Retrieval: Implementing
+and Evaluating Search Engines][irbook].
+
+[wsdm]: http://research.google.com/people/jeff/WSDM09-keynote.pdf
+[irbook]: http://www.ir.uwaterloo.ca/book/addenda-06-index-compression.html
+
+Briefly, a group of four 32-bit integers is encoded as a sequence of variable
+length, between 5 and 17 bytes; the first byte encodes the length (in bytes)
+of each integer in the group.  A group of five 64-bit integers is encoded as a
+sequence of variable length, between 7 and 42 bytes; the first two bytes
+encode the length (in bytes) of each integer in the group.
+
+`GroupVarint.h` defines a few classes:
+
+* `GroupVarint<T>`, where `T` is `uint32_t` or `uint64_t`:
+
+    Basic encoding / decoding interface, mainly aimed at encoding / decoding
+    one group at a time.
+
+* `GroupVarintEncoder<T, Output>`, where `T` is `uint32_t` or `uint64_t`,
+  and `Output` is a functor that accepts `StringPiece` objects as arguments:
+
+    Streaming encoder: add values one at a time, and they will be
+    flushed to the output one group at a time.  Handles the case where
+    the last group is incomplete (the number of integers to encode isn't
+    a multiple of the group size)
+
+* `GroupVarintDecoder<T>`, where `T` is `uint32_t` or `uint64_t`:
+
+    Streaming decoder: extract values one at a time.  Handles the case where
+    the last group is incomplete.
+
+The 32-bit implementation is significantly faster than the 64-bit
+implementation; on platforms supporting the SSSE3 instruction set, we
+use the PSHUFB instruction to speed up lookup, as described in [SIMD-Based
+Decoding of Posting Lists][cikmpaper] (CIKM 2011).
+
+[cikmpaper]: http://www.stepanovpapers.com/CIKM_2011.pdf
+
+For more details, see the header file `folly/GroupVarint.h` and the
+associated test file `folly/test/GroupVarintTest.cpp`.