react-native-windows 0.81.35 → 0.81.36

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));
+```
+***

package/external/folly/folly/docs/Overview.md

@@ -0,0 +1,263 @@
+### `folly/`
+
+### Components
+
+Below is a list of (some) Folly components in alphabetical order, along with
+a brief description of each.
+
+#### `Arena.h`, `ThreadCachedArena.h`
+
+Simple arena for memory allocation: multiple allocations get freed all
+at once. With threaded version.
+
+#### [`AtomicHashMap.h`](AtomicHashMap.md), `AtomicHashArray.h`, `AtomicLinkedList.h`, ...
+
+High-performance atomic data-structures. Many of these are built with very specific
+tradeoffs and constraints in mind that make them faster than their more general
+counterparts. Each header should contain information about what these tradeoffs are.
+
+#### `Baton.h`
+
+A Baton allows a thread to block once and be awoken: it captures a single handoff. It is
+essentially a (very small, very fast) semaphore that supports only a single call to `sem_call`
+and `sem_wait`.
+
+#### [`Benchmark.h`](Benchmark.md)
+
+A small framework for benchmarking code. Client code registers
+benchmarks, optionally with an argument that dictates the scale of the
+benchmark (iterations, working set size etc). The framework runs
+benchmarks (subject to a command-line flag) and produces formatted
+output with timing information.
+
+#### `Bits.h`
+
+Various bit manipulation utilities optimized for speed; includes functions
+that wrap the
+[ffsl(l)](http://linux.die.net/man/3/ffsll) primitives in a uniform
+interface.
+
+#### `ConcurrentSkipList.h`
+
+An implementation of the structure described in [A Provably Correct
+Scalable Concurrent Skip
+List](http://people.csail.mit.edu/shanir/publications/OPODIS2006-BA.pdf)
+by Herlihy et al.
+
+#### [`Conv.h`](Conv.md)
+
+A variety of data conversion routines (notably to and from string),
+optimized for speed and safety.
+
+#### `Demangle.h`
+
+Pretty-printing C++ types.
+
+#### `DiscriminatedPtr.h`
+
+Similar to `std::variant`, but restricted to pointers only. Uses the
+highest-order unused 16 bits in a pointer as discriminator. So
+`sizeof(DiscriminatedPtr<int, string, Widget>) == sizeof(void*)`.
+
+#### [`dynamic.h`](Dynamic.md)
+
+Dynamically-typed object, created with JSON objects in mind. `DynamicConverter.h` is
+a utility for efficiently converting from a `dynamic` to a more concrete structure when
+the scheme is known (e.g. json -> `map<int,int>`).
+
+#### `EvictingCacheMap.h`
+
+A simple LRU hash map.
+
+#### [`FBString.h`](FBString.md)
+
+A drop-in implementation of `std::string` with a variety of optimizations.
+
+#### [`FBVector.h`](FBVector.md)
+
+A mostly drop-in implementation of `std::vector` with a variety of
+optimizations.
+
+#### `File.h`
+
+A C++ abstraction around files.
+
+#### `Fingerprint.h`
+
+Rabin fingerprinting.
+
+#### [`Function.h`](Function.md)
+
+A polymorphic wrapper for callables similar to `std::function` but not copyable and therefore able to wrap non-copyable callables, such as lambdas that capture move-only types like `std::unique_ptr` or `folly::Promise`.
+
+#### [`futures/`](Futures.md)
+
+Futures is a framework for expressing asynchronous code in C++ using the Promise/Future pattern.
+
+#### [`Format.h`](Format.md)
+
+Python-style formatting utilities.
+
+#### `gen/`
+
+This library makes it possible to write declarative comprehensions for
+processing sequences of values efficiently in C++ akin to C#'s LINQ.
+
+#### [`GroupVarint.h`](GroupVarint.md)
+
+[Group Varint
+encoding](http://www.ir.uwaterloo.ca/book/addenda-06-index-compression.html)
+for 32-bit values.
+
+#### `IPAddress.h`
+
+A collection of utilities to deal with IPAddresses, including ipv4 and ipv6.
+
+#### `io/`
+
+A collection of useful of abstractions for high-performance io. This is heavily relied upon
+in Facebook's internally networking code.
+
+#### `Hash.h`
+
+Various popular hash function implementations.
+
+#### [`Histogram.h`](Histogram.md)
+
+A simple class for collecting histogram data.
+
+#### `IntrusiveList.h`
+
+Convenience type definitions for using `boost::intrusive_list`.
+
+#### `json.h`
+
+JSON serializer and deserializer. Uses `dynamic.h`.
+
+#### `Likely.h`
+
+Wrappers around [`__builtin_expect`](http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).
+
+#### `Malloc.h`, `Memory.h`
+
+Memory allocation helpers, particularly when using jemalloc.
+
+#### `MicroSpinLock.h`
+
+A really, *really* small spinlock for fine-grained locking of lots of teeny-tiny data.
+
+#### `MPMCQueue.h`
+
+MPMCQueue<typename> is a high-performance bounded concurrent queue that
+supports multiple producers, multiple consumers, and optional blocking.
+The queue has a fixed capacity, for which all memory will be allocated
+ up front.
+
+The additional utility `MPMCPipeline.h` is an extension that lets you
+chain several queues together with processing steps in between.
+
+#### [`PackedSyncPtr.h`](PackedSyncPtr.md)
+
+A highly specialized data structure consisting of a pointer, a 1-bit
+spin lock, and a 15-bit integer, all inside one 64-bit word.
+
+#### [`Poly.h`](Poly.md)
+
+A class template that makes it relatively easy to define a type-erasing
+polymorphic object wrapper.
+
+#### `Preprocessor.h`
+
+Necessarily evil stuff.
+
+#### [`ProducerConsumerQueue.h`](ProducerConsumerQueue.md)
+
+Lock free single-reader, single-writer queue.
+
+#### `Random.h`
+
+Defines only one function---`randomNumberSeed()`.
+
+#### `Range.h`
+
+Boost-style range facility and the `StringPiece` specialization.
+
+#### `RWSpinLock.h`
+
+Fast and compact reader-writer spin lock.
+
+#### `ScopeGuard.h`
+
+C++11 incarnation of the old [ScopeGuard](http://drdobbs.com/184403758) idiom.
+
+#### `Singleton.h`
+
+A singleton to rule the singletons. This is an attempt to insert a layer between
+C++ statics and the fiasco that ensues, so that things can be created, and destroyed,
+correctly upon program creation, program end and sometimes `dlopen` and `fork`.
+
+Singletons are bad for you, but this may help.
+
+#### [`SmallLocks.h`](SmallLocks.md)
+
+Very small spin locks (1 byte and 1 bit).
+
+#### `small_vector.h`
+
+Vector with the small buffer optimization and an optional embedded
+`PicoSpinLock`.
+
+#### `sorted_vector_types.h`
+
+Collections similar to `std::map` but implemented as sorted vectors.
+
+#### `stats/`
+
+A collection of efficient utilities for collecting statistics:
+* time series counters, gauges, histograms, and quantiles;
+* single-pass mean and variance.
+
+#### `StlAllocator.h`
+
+STL allocator wrapping a simple allocate/deallocate interface.
+
+#### `String.h`
+
+String utilities that connect `folly::fbstring` with `std::string`.
+
+#### `Subprocess.h`
+
+Subprocess library, modeled after Python's subprocess module.
+
+#### [`Synchronized.h`](Synchronized.md)
+
+High-level synchronization library.
+
+#### `System.h`
+
+Demangling and errno utilities.
+
+#### [`ThreadCachedInt.h`](ThreadCachedInt.md)
+
+High-performance atomic increment using thread caching.
+
+#### [`ThreadLocal.h`](ThreadLocal.md)
+
+Improved thread local storage for non-trivial types.
+
+#### `TimeoutQueue.h`
+
+Queue with per-item timeout.
+
+#### `Traits.h`
+
+Type traits that complement those defined in the standard C++11 header
+`<traits>`.
+
+#### `Unicode.h`
+
+Defines the `codePointToUtf8` function.
+
+#### `Uri.h`
+
+A collection of utilities to deal with URIs.

package/external/folly/folly/docs/PackedSyncPtr.md

@@ -0,0 +1,77 @@
+`folly/PackedSyncPtr.h`
+----------------------
+
+A highly specialized data structure consisting of a pointer, a 1-bit
+spin lock, and a 15-bit integral packed into `sizeof(void*)`.
+
+Typical application is for microsharding of many elements within containers.
+Because there is no memory overhead, an arbitrarily large number of locks can be
+used to minimize lock contention with no memory penalty.  Additionally,
+excellent cache performance is obtained by storing the lock inline with the
+pointer (no additional cache miss or false sharing).  Finally, because it uses a
+simple spinlock mechanism, the cost of acquiring an uncontended lock is minimal.
+
+### Usage
+***
+
+This is not a "smart" pointer: nothing automagical is going on
+here.  Locking is up to the user.  Resource deallocation is up to
+the user.  Locks are never acquired or released outside explicit
+calls to lock() and unlock().
+
+Change the value of the raw pointer with set(), but you must hold
+the lock when calling this function if multiple threads could be
+using it.
+
+Here is an example of using a PackedSyncPtr to build a synchronized vector with
+no memory overhead - the spinlock and size are stored in the 16 unused bits of
+pointer, the rest of which points to the actual data.  See
+`folly/small_vector.h` for a complete implementation of this concept.
+
+``` Cpp
+    template<typename T>
+    class SyncVec {
+      PackedSyncPtr<T> base;
+
+     public:
+      SyncVec() { base.init(); }
+
+      void push_back(const T& t) {
+        base.set(
+          static_cast<T*>(realloc(base.get(), (base.extra() + 1) * sizeof(T))));
+        base[base.extra()] = t;
+        base.setExtra(base.extra() + 1);
+      }
+
+      size_t size() const {
+        return base.extra();
+      }
+
+      void lock() {
+        base.lock();
+      }
+
+      void unlock() {
+        base.unlock();
+      }
+
+      T* begin() const {
+        return base.get();
+      }
+
+      T* end() const {
+        return base.get() + base.extra();
+      }
+    };
+```
+
+### Implementation
+***
+
+This is using an x64-specific detail about the effective virtual
+address space.  Long story short: the upper two bytes of all our
+pointers will be zero in reality---and if you have a couple billion
+such pointers in core, it makes pretty good sense to try to make
+use of that memory.  The exact details can be perused here:
+
+[http://en.wikipedia.org/wiki/X86-64#Canonical_form_addresses](http://en.wikipedia.org/wiki/X86-64#Canonical_form_addresses)