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

package/external/folly/folly/docs/ThreadCachedInt.md

@@ -0,0 +1,98 @@
+`folly/ThreadCachedInt.h`
+----------------------
+
+High-performance atomic increment using thread caching.
+
+`folly/ThreadCachedInt.h` introduces a integer class designed for high
+performance increments from multiple threads simultaneously without
+loss of precision.  It has two read modes, `readFast` gives a potentially stale
+value with one load, and `readFull` gives the exact value, but is much slower,
+as discussed below.
+
+
+### Performance
+***
+
+Increment performance is up to 10x greater than `std::atomic_fetch_add` in high
+contention environments.  See `folly/test/ThreadCachedIntTest.h` for more
+comprehensive benchmarks.
+
+`readFast` is as fast as a single load.
+
+`readFull`, on the other hand, requires acquiring a mutex and iterating through
+a list to accumulate the values of all the thread local counters, so is
+significantly slower than `readFast`.
+
+
+### Usage
+***
+
+Create an instance and increment it with `increment` or the operator overloads.
+Read the value with `readFast` for quick, potentially stale data, or `readFull`
+for a more expensive but precise result. There are additional convenience
+functions as well, such as `set`.
+
+``` Cpp
+    ThreadCachedInt<int64_t> val;
+    EXPECT_EQ(0, val.readFast());
+    ++val;                        // increment in thread local counter only
+    EXPECT_EQ(0, val.readFast()); // increment has not been flushed
+    EXPECT_EQ(1, val.readFull()); // accumulates all thread local counters
+    val.set(2);
+    EXPECT_EQ(2, val.readFast());
+    EXPECT_EQ(2, val.readFull());
+```
+
+### Implementation
+***
+
+`folly::ThreadCachedInt` uses `folly::ThreadLocal` to store thread specific
+objects that each have a local counter.  When incrementing, the thread local
+instance is incremented.  If the local counter passes the cache size, the value
+is flushed to the global counter with an atomic increment.  It is this global
+counter that is read with `readFast` via a simple load, but will not count any
+of the updates that haven't been flushed.
+
+In order to read the exact value, `ThreadCachedInt` uses the extended
+`readAllThreads()` API of `folly::ThreadLocal` to iterate through all the
+references to all the associated thread local object instances.  This currently
+requires acquiring a global mutex and iterating through the references,
+accumulating the counters along with the global counter.  This also means that
+the first use of the object from a new thread will acquire the mutex in order to
+insert the thread local reference into the list.  By default, there is one
+global mutex per integer type used in `ThreadCachedInt`.  If you plan on using a
+lot of `ThreadCachedInt`s in your application, considering breaking up the
+global mutex by introducing additional `Tag` template parameters.
+
+`set` simply sets the global counter value, and marks all the thread local
+instances as needing to be reset.  When iterating with `readFull`, thread local
+counters that have been marked as reset are skipped.  When incrementing, thread
+local counters marked for reset are set to zero and unmarked for reset.
+
+Upon destruction, thread local counters are flushed to the parent so that counts
+are not lost after increments in temporary threads.  This requires grabbing the
+global mutex to make sure the parent itself wasn't destroyed in another thread
+already.
+
+### Alternate Implementations
+***
+
+There are of course many ways to skin a cat, and you may notice there is a
+partial alternate implementation in `folly/test/ThreadCachedIntTest.cpp` that
+provides similar performance.  `ShardedAtomicInt` simply uses an array of
+`std::atomic<int64_t>`'s and hashes threads across them to do low-contention
+atomic increments, and `readFull` just sums up all the ints.
+
+This sounds great, but in order to get the contention low enough to get similar
+performance as ThreadCachedInt with 24 threads, `ShardedAtomicInt` needs about
+2000 ints to hash across.  This uses about 20x more memory, and the lock-free
+`readFull` has to sum up all 2048 ints, which ends up being a about 50x slower
+than `ThreadCachedInt` in low contention situations, which is hopefully the
+common case since it's designed for high-write, low read access patterns.
+Performance of `readFull` is about the same speed as `ThreadCachedInt` in high
+contention environments.
+
+Depending on the operating conditions, it may make more sense to use one
+implementation over the other.  For example, a lower contention environment will
+probably be able to use a `ShardedAtomicInt` with a much smaller array without
+hurting performance, while improving memory consumption and perf of `readFull`.

package/external/folly/folly/docs/ThreadLocal.md

@@ -0,0 +1,105 @@
+`folly/ThreadLocal.h`
+----------------------
+
+Improved thread local storage for non-trivial types.
+
+ * ~4x faster than `boost::thread_specific_ptr`.
+ * Similar speed as using `pthread_getspecific` directly, but only consumes a
+   single `pthread_key_t` per `Tag` template param.
+ * Expands on the `thread_specific_ptr` API with `accessAllThreads` and extended
+   custom deleter support.
+
+
+### Usage
+***
+
+The API of `ThreadLocalPtr` is very close to `boost::thread_specific_ptr` with
+the notable addition of the `accessAllThreads` method.  There is also a
+`ThreadLocal` class which is a thin wrapper around `ThreadLocalPtr` that manages
+allocation automatically (creates a new object the first time it is dereferenced
+from each thread).
+
+`ThreadLocalPtr` simply gives you a place to put and access a pointer local to
+each thread such that it will be destroyed appropriately.
+
+```Cpp
+{
+  folly::ThreadLocalPtr<Widget> w;
+  w.reset(new Widget(0), Widget::customDeleterA);
+  std::thread([&w]() {
+    w.reset(new Widget(1), Widget::customDeleterB);
+    w.get()->mangleWidget();
+  } // Widget(1) is destroyed with customDeleterB
+} // Widget(0) is destroyed with customDeleterA
+```
+
+Note that `customDeleterB` will get called with
+`TLPDestructionMode::THIS_THREAD` and `customerDeleterA` will get called with
+`TLPDestructionMode::ALL_THREADS`.  This is to distinguish between thread exit
+vs. the entire `ThreadLocalPtr` getting destroyed, in which case there is
+cleanup work that may be avoided.
+
+The `accessAllThreads` interface is provided to walk all the thread local child
+objects of a parent.  `accessAllThreads` initializes an accessor
+which holds a global lock that blocks all creation and destruction of
+`ThreadLocal` objects with the same `Tag` and can be used as an iterable
+container. Typical use is for frequent write, infrequent read data access
+patterns such as counters.  Note that you must specify a unique Tag type so you
+don't block other ThreadLocal object usage, and you should try to minimize the
+lifetime of the accessor so the lock is held for as short as possible).
+
+The following example is a simplification of `folly/ThreadCachedInt.h`.  It
+keeps track of a counter value and allows multiple threads to add to the count
+without synchronization.  In order to get the total count, `read()` iterates
+through all the thread local values via `accessAllThreads()` and sums them up.
+`class NewTag` is used to break the global mutex so that this class won't block
+other `ThreadLocal` usage when `read()` is called.
+
+Note that `read()` holds the global mutex which blocks construction,
+destruction, and `read()` for other `SimpleThreadCachedInt`'s, but does not
+block `add()`.  Also, since it uses the unique `NewTag`, `SimpleThreadCachedInt`
+does not affect other `ThreadLocal` usage.
+
+```Cpp
+class SimpleThreadCachedInt {
+
+  class NewTag;  // Segments the global mutex
+  ThreadLocal<int,NewTag> val_;
+
+ public:
+  void add(int val) {
+    *val_ += val;  // operator*() gives a reference to the thread local instance
+  }
+
+  int read() {
+    int ret = 0;
+    // accessAllThreads acquires the global lock
+    for (const auto& i : val_.accessAllThreads()) {
+      ret += i;
+    }  // Global lock is released on scope exit
+    return ret;
+  }
+};
+```
+
+
+### Implementation
+***
+
+We keep a `__thread` array of pointers to objects (`ThreadEntry::elements`)
+where each array has an index for each unique instance of the `ThreadLocalPtr`
+object.  Each `ThreadLocalPtr` object has a unique id that is an index into
+these arrays so we can fetch the correct object from thread local storage
+very efficiently.
+
+In order to prevent unbounded growth of the id space and thus huge
+`ThreadEntry::elements` arrays, for example due to continuous creation and
+destruction of `ThreadLocalPtr` objects, we keep track of all active instances
+by linking them together into a list.  When an instance is destroyed we remove
+it from the chain and insert the id into `freeIds_` for reuse.  These operations
+require a global mutex, but only happen at construction and destruction time.
+`accessAllThreads` also acquires this global mutex.
+
+We use a single global `pthread_key_t` per `Tag` to manage object destruction
+and memory cleanup upon thread exit because there is a finite number of
+`pthread_key_t`'s available per machine.

package/external/folly/folly/docs/Traits.md

@@ -0,0 +1,161 @@
+'folly/Traits.h'
+-----------------
+
+Implements traits complementary to those provided in <type_traits>
+
+  * Implements `IsRelocatable` trait.
+  * Implements `IsOneOf` trait
+  * Macros to state the assumptions easily
+
+### Motivation
+***
+
+`<type_traits>` is the Standard type-traits library defining a variety of traits
+such as `is_integral` or `is_floating_point`. This helps to gain more
+information about a given type.
+
+`folly/Traits.h` implements traits complementing those present in the Standard.
+
+
+### IsRelocatable
+***
+
+In C++, the default way to move an object is by
+calling the copy constructor and destroying the old copy
+instead of directly copying the memory contents by using memcpy().
+The conservative approach of moving an object assumes that the copied
+object is not relocatable.
+The two following code sequences should be semantically equivalent for a
+relocatable type:
+
+```Cpp
+{
+  void conservativeMove(T * from, T * to) {
+    new(to) T(from);
+    (*from).~T();
+  }
+}
+
+{
+  void optimizedMove(T * from, T * to) {
+    memcpy(to, from, sizeof(T));
+  }
+}
+```
+
+Very few C++ types are non-relocatable.
+The type defined below maintains a pointer inside an embedded buffer and
+hence would be non-relocatable. Moving the object by simply copying its
+memory contents would leave the internal pointer pointing to the old buffer.
+
+```Cpp
+class NonRelocatableType {
+private:
+  char buffer[1024];
+  char * pointerToBuffer;
+  ...
+public:
+  NonRelocatableType() : pointerToBuffer(buffer) {}
+  ...
+};
+```
+
+We can optimize the task of moving a relocatable type T using memcpy.
+IsRelocatable<T>::value describes the ability of moving around memory
+a value of type T by using memcpy.
+
+### Usage
+***
+
+  * Declaring types
+
+    ```Cpp
+    template <class T1, class T2>
+    class MyParameterizedType;
+
+    class MySimpleType;
+    ```
+
+  * Declaring a type as relocatable
+
+    Appending the lines below after definition of My*Type
+    (`MyParameterizedType` or `MySimpleType`) will declare it as relocatable
+
+    ```Cpp
+    /* Definition of My*Type goes here */
+    // global namespace (not inside any namespace)
+    namespace folly {
+      // defining specialization of IsRelocatable for MySimpleType
+      template <>
+      struct IsRelocatable<MySimpleType> : std::true_type {};
+      // defining specialization of IsRelocatable for MyParameterizedType
+      template <class T1, class T2>
+      struct IsRelocatable<MyParameterizedType<T1, T2>>
+          : ::std::true_type {};
+    }
+    ```
+
+  * To make it easy to state assumptions for a regular type or a family of
+    parameterized type, various macros can be used as shown below.
+
+  * Stating that a type is Relocatable using a macro
+
+    ```Cpp
+    // global namespace
+    namespace folly {
+      // For a Regular Type
+      FOLLY_ASSUME_RELOCATABLE(MySimpleType);
+      // For a Parameterized Type
+      FOLLY_ASSUME_RELOCATABLE(MyParameterizedType<T1, T2>);
+    }
+    ```
+
+`fbvector` only works with relocatable objects. If assumptions are not stated
+explicitly, `fbvector<MySimpleType>` or `fbvector<MyParameterizedType>`
+will fail to compile due to assertion below:
+
+```Cpp
+static_assert(IsRelocatable<My*Type>::value, "");
+```
+
+FOLLY_ASSUME_FBVECTOR_COMPATIBLE*(type) macros can be used to state that type
+is relocatable and has nothrow constructor.
+
+  * Stating that a type is `fbvector-compatible` using macros
+    i.e. relocatable and has nothrow default constructor
+
+    ```Cpp
+    // at global level, i.e no namespace
+    // macro for regular type
+    FOLLY_ASSUME_FBVECTOR_COMPATIBLE(MySimpleType)
+    // macro for types having 2 template parameters (MyParameterizedType)
+    FOLLY_ASSUME_FBVECTOR_COMPATIBLE_2(MyParameterizedType)
+    ```
+
+Similarly,
+
+  * FOLLY_ASSUME_FBVECTOR_COMPATIBLE_1(MyTypeHavingOneParameter) macro is
+    for family of parameterized types having 1 parameter
+
+  * FOLLY_ASSUME_FBVECTOR_COMPATIBLE_3(MyTypeHavingThreeParameters) macro is
+    for family of parameterized types having 3 parameters
+
+  * FOLLY_ASSUME_FBVECTOR_COMPATIBLE_4(MyTypeHavingFourParameters) macro is
+    for family of parameterized types having 4 parameters
+
+Few common types, namely `std::basic_string`, `std::vector`, `std::list`,
+`std::map`, `std::deque`, `std::set`, `std::unique_ptr`, `std::shared_ptr`,
+`std::function`, which are compatible with `fbvector` are already instantiated
+and declared compatible with `fbvector`. `fbvector` can be directly used with
+any of these C++ types.
+
+`std::pair` can be safely assumed to be compatible with `fbvector` if both of
+its components are.
+
+### IsOneOf
+***
+
+`std::is_same<T1, T2>::value` can be used to test if types of T1 and T2 are
+same. `folly::IsOneOf<T, T1, Ts...>::value` can be used to test if type of T
+matches the type of one of the other template parameter, T1, T2, ...Tn.
+Recursion is used to implement this type trait.

package/external/folly/folly/docs/small_vector.md

@@ -0,0 +1,64 @@
+`folly/small_vector.h`
+----------------------
+
+`folly::small_vector<T,Int=1,...>` is a sequence container that
+implements small buffer optimization. It behaves similarly to
+std::vector, except until a certain number of elements are reserved it
+does not use the heap.
+
+Like standard vector, it is guaranteed to use contiguous memory.  (So,
+after it spills to the heap all the elements live in the heap buffer.)
+
+Simple usage example:
+
+``` Cpp
+    small_vector<int,2> vec;
+    vec.push_back(0); // Stored in-place on stack
+    vec.push_back(1); // Still on the stack
+    vec.push_back(2); // Switches to heap buffer.
+```
+
+### Details
+***
+
+This class is useful in either of following cases:
+
+* Short-lived stack vectors with few elements (or maybe with a
+  usually-known number of elements), if you want to avoid malloc.
+
+* If the vector(s) are usually under a known size and lookups are very
+  common, you'll save an extra cache miss in the common case when the
+  data is kept in-place.
+
+* You have billions of these vectors and don't want to waste space on
+  `std::vector`'s capacity tracking.  This vector lets `malloc` track our
+  allocation capacity.  (Note that this slows down the
+  insertion/reallocation code paths significantly; if you need those
+  to be fast you should use `fbvector`.)
+
+The last two cases were the main motivation for implementing it.
+
+There are also a couple of flags you can pass into this class
+template to customize its behavior.  You can provide them in any
+order after the in-place count.  They are all in the `namespace
+small_vector_policy`.
+
+* `NoHeap` - Avoid the heap entirely.  (Throws `std::length_error` if
+  you would've spilled out of the in-place allocation.)
+
+* `<Any integral type>` - customizes the amount of space we spend on
+  tracking the size of the vector.
+
+A couple more examples:
+
+``` Cpp
+    // With space for 32 in situ unique pointers, and only using a
+    // 4-byte size_type.
+    small_vector<std::unique_ptr<int>, 32, uint32_t> v;
+
+    // A inline vector of up to 256 ints which will not use the heap.
+    small_vector<int, 256, NoHeap> v;
+
+    // Same as the above, but making the size_type smaller too.
+    small_vector<int, 256, NoHeap, uint16_t> v;
+```

package/external/folly/folly/docs/style.css

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+<style type="text/css">
+pre.literal-block, pre.doctest-block, pre.sourceCode {
+    margin-left: 2em;
+    margin-right: 2em;
+    background-color: #eeeeee
+}
+</style>

package/external/folly/folly/dynamic-inl.h

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <folly/json/dynamic-inl.h>

package/external/folly/folly/dynamic.h

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <folly/json/dynamic.h>

package/external/folly/folly/folly_extended_library.bzl

@@ -0,0 +1,28 @@
+load("@fbsource//tools/build_defs:default_platform_defs.bzl", "ANDROID", "APPLE", "CXX", "FBCODE", "WINDOWS")
+load("@fbsource//xplat/folly:defs.bzl", "folly_library")
+
+def folly_extended_library(name, **kwargs):
+    folly_library(
+        name,
+        force_static = False,
+        enable_static_variant = True,
+        compiler_flags = [
+            "-Wno-shadow",
+        ],
+        fbandroid_deps = [
+            "fbsource//xplat/third-party/linker_lib:atomic",
+            "fbsource//third-party/toolchains:log",
+        ],
+        linker_flags = select({
+            "DEFAULT": [],
+            "ovr_config//os:android": [
+                "-Wl,--no-undefined",
+            ],
+        }),
+        platforms = (CXX, ANDROID, APPLE, FBCODE, WINDOWS),
+        deps = [
+            "fbsource//xplat/folly:memory",
+            "fbsource//third-party/glog:glog",
+        ],
+        **kwargs
+    )