react-native-windows 0.84.0 → 0.85.0-preview.2

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`.

package/external/folly/folly/docs/Histogram.md

@@ -0,0 +1,104 @@
+`folly/stats/Histogram.h`
+-------------------
+
+### Classes
+***
+
+#### `Histogram`
+
+`Histogram.h` defines a simple histogram class, templated on the type of data
+you want to store.  This class is useful for tracking a large stream of data
+points, where you want to remember the overall distribution of the data, but do
+not need to remember each data point individually.
+
+Each histogram bucket stores the number of data points that fell in the bucket,
+as well as the overall sum of the data points in the bucket.  Note that no
+overflow checking is performed, so if you have a bucket with a large number of
+very large values, it may overflow and cause inaccurate data for this bucket.
+As such, the histogram class is not well suited to storing data points with
+very large values.  However, it works very well for smaller data points such as
+request latencies, request or response sizes, etc.
+
+In addition to providing access to the raw bucket data, the `Histogram` class
+also provides methods for estimating percentile values.  This allows you to
+estimate the median value (the 50th percentile) and other values such as the
+95th or 99th percentiles.
+
+All of the buckets have the same width.  The number of buckets and bucket width
+is fixed for the lifetime of the histogram.  As such, you do need to know your
+expected data range ahead of time in order to have accurate statistics.  The
+histogram does keep one bucket to store all data points that fall below the
+histogram minimum, and one bucket for the data points above the maximum.
+However, because these buckets don't have a good lower/upper bound, percentile
+estimates in these buckets may be inaccurate.
+
+#### `HistogramBuckets`
+
+The `Histogram` class is built on top of `HistogramBuckets`.
+`HistogramBuckets` provides an API very similar to `Histogram`, but allows a
+user-defined bucket class.  This allows users to implement more complex
+histogram types that store more than just the count and sum in each bucket.
+
+When computing percentile estimates `HistogramBuckets` allows user-defined
+functions for computing the average value and data count in each bucket.  This
+allows you to define more complex buckets which may have multiple different
+ways of computing the average value and the count.
+
+For example, one use case could be tracking timeseries data in each bucket.
+Each set of timeseries data can have independent data in the bucket, which can
+show how the data distribution is changing over time.
+
+### Example Usage
+***
+
+Say we have code that sends many requests to remote services, and want to
+generate a histogram showing how long the requests take.  The following code
+will initialize histogram with 50 buckets, tracking values between 0 and 5000.
+(There are 50 buckets since the bucket width is specified as 100.  If the
+bucket width is not an even multiple of the histogram range, the last bucket
+will simply be shorter than the others.)
+
+``` Cpp
+    folly::Histogram<int64_t> latencies(100, 0, 5000);
+```
+
+The addValue() method is used to add values to the histogram.  Each time a
+request finishes we can add its latency to the histogram:
+
+``` Cpp
+    latencies.addValue(now - startTime);
+```
+
+You can access each of the histogram buckets to display the overall
+distribution.  Note that bucket 0 tracks all data points that were below the
+specified histogram minimum, and the last bucket tracks the data points that
+were above the maximum.
+
+``` Cpp
+    auto numBuckets = latencies.getNumBuckets();
+    cout << "Below min: " << latencies.getBucketByIndex(0).count << "\n";
+    for (unsigned int n = 1; n < numBuckets - 1; ++n) {
+      cout << latencies.getBucketMin(n) << "-" << latencies.getBucketMax(n)
+           << ": " << latencies.getBucketByIndex(n).count << "\n";
+    }
+    cout << "Above max: "
+         << latencies.getBucketByIndex(numBuckets - 1).count << "\n";
+```
+
+You can also use the `getPercentileEstimate()` method to estimate the value at
+the Nth percentile in the distribution.  For example, to estimate the median,
+as well as the 95th and 99th percentile values:
+
+``` Cpp
+    int64_t median = latencies.getPercentileEstimate(0.5);
+    int64_t p95 = latencies.getPercentileEstimate(0.95);
+    int64_t p99 = latencies.getPercentileEstimate(0.99);
+```
+
+### Thread Safety
+***
+
+Note that `Histogram` and `HistogramBuckets` objects are not thread-safe.  If
+you wish to access a single `Histogram` from multiple threads, you must perform
+your own locking to ensure that multiple threads do not access it at the same
+time.

package/external/folly/folly/docs/MapUtils.md

@@ -0,0 +1,80 @@
+`folly/container/MapUtil.h`
+---------------------------
+
+MapUtil provides convenience functions to get a value from a map.
+
+### Motivation & Comparisons
+
+Fetching a value in a map can be tedious. For example, `map.at()` will throw an exception if the key is not present:
+```cpp
+try {
+    auto& v = m.at(1);
+} catch (...) {
+    // do something!
+}
+```
+
+We can avoid the exception handling by using `find`:
+```cpp
+auto it = m.find(1);
+if (it != m.end()) {
+    auto& v = it->second;
+}
+```
+
+Both of these cases can be written more succinctly and without exception handling using folly/MapUtil.h
+```cpp
+if (const auto* v = folly::get_ptr(m, 1)) {
+    // do stuff with `v` which is guaranteed to be present in this block
+}
+```
+
+We can also easily lookup values in nested maps:
+```cpp
+std::map<int, std::map<int, int>> m {{1, {{2, 3}}}};
+// using find
+auto it1 = m.find(1);
+if (it1 != m.end()) {
+    auto it2 = it1->second.find(2);
+    if (it2 != it1->second.end()) {
+        auto& v = it2->second;
+    }
+}
+// using folly/MapUtil.h
+if (const auto* v = folly::get_ptr(m, 1, 2)) {
+    // do stuff with `v`!
+}
+```
+
+### Sample
+The corresponding unit test suite has a very thorough collection of examples: `folly/container/test/MapUtilTest.cpp`,
+for brevity, here is a small glimpse:
+
+***
+```cpp
+std::map<int, int> m {{1, 2}};
+
+// Return a pointer (nullptr if the key is not in the map)
+EXPECT_EQ(2, *get_ptr(m, 1));
+EXPECT_TRUE(get_ptr(m, 2) == nullptr);
+
+// Return a value (or default)
+EXPECT_EQ(2, get_default(m, 1, 42));
+EXPECT_EQ(42, get_default(m, 2, 42));
+
+// Return an optional (empty if the key is not in the map)
+EXPECT_TRUE(get_optional(m, 1).has_value());
+EXPECT_EQ(2, get_optional(m, 1).value());
+
+// Return a reference
+const int i = 42;
+EXPECT_EQ(2, get_ref_default(m, 1, i));
+EXPECT_EQ(42, get_ref_default(m, 2, i));
+
+// Even works for nested maps!
+std::map<int, map<int, map<int, map<int, int>>>> nested{{1, {{2, {{3, {{4, 5}}}}}}}};
+EXPECT_EQ(5, *get_ptr(nested, 1, 2, 3, 4));
+EXPECT_TRUE(get_ptr(nested, 1, 2, 3, 4));
+EXPECT_FALSE(get_ptr(nested, 1, 2, 3, 0));
+```
+***