react-native-windows 0.81.34 → 0.81.37

package/external/folly/folly/docs/Poly.md

@@ -0,0 +1,500 @@
+`folly/Poly.h`
+-------------------------------
+
+`Poly` is a class template that makes it relatively easy to define a
+type-erasing polymorphic object wrapper.
+
+### Type-erasure
+***
+
+`std::function` is one example of a type-erasing polymorphic object wrapper;
+`folly::exception_wrapper` is another. Type-erasure is often used as an
+alternative to dynamic polymorphism via inheritance-based virtual dispatch.
+The distinguishing characteristic of type-erasing wrappers are:
+
+* **Duck typing:** Types do not need to inherit from an abstract base
+    class in order to be assignable to a type-erasing wrapper; they merely
+    need to satisfy a particular interface.
+* **Value semantics:** Type-erasing wrappers are objects that can be
+    passed around _by value_. This is in contrast to abstract base classes
+    which must be passed by reference or by pointer or else suffer from
+    _slicing_, which causes them to lose their polymorphic behaviors.
+    Reference semantics make it difficult to reason locally about code.
+* **Automatic memory management:** When dealing with inheritance-based
+    dynamic polymorphism, it is often necessary to allocate and manage
+    objects on the heap. This leads to a proliferation of `shared_ptr`s and
+    `unique_ptr`s in APIs, complicating their point-of-use. APIs that take
+    type-erasing wrappers, on the other hand, can often store small objects
+    in-situ, with no dynamic allocation. The memory management, if any, is
+    handled for you, and leads to cleaner APIs: consumers of your API don't
+    need to pass `shared_ptr<AbstractBase>`; they can simply pass any object
+    that satisfies the interface you require. (`std::function` is a
+    particularly compelling example of this benefit. Far worse would be an
+    inheritance-based callable solution like
+    `shared_ptr<ICallable<void(int)>>`. )
+
+### Examples: Defining a type-erasing function wrapper with `folly::Poly`
+***
+
+Defining a polymorphic wrapper with `Poly` is a matter of defining two
+things:
+
+* An *interface*, consisting of public member functions, and
+* A *mapping* from a concrete type to a set of member function bindings.
+
+Below is a simple example program that defines a `drawable` wrapper for any type
+that provides a `draw` member function. (The details will be explained later.)
+
+``` Cpp
+    // This example is an adaptation of one found in Louis Dionne's dyno library.
+    #include <folly/Poly.h>
+    #include <iostream>
+
+    struct IDrawable {
+      // Define the interface of something that can be drawn:
+      template <class Base> struct Interface : Base {
+        void draw(std::ostream& out) const { folly::poly_call<0>(*this, out);}
+      };
+      // Define how concrete types can fulfill that interface (in C++17):
+      template <class T> using Members = folly::PolyMembers<&T::draw>;
+    };
+
+    // Define an object that can hold anything that can be drawn:
+    using drawable = folly::Poly<IDrawable>;
+
+    struct Square {
+      void draw(std::ostream& out) const { out << "Square\n"; }
+    };
+
+    struct Circle {
+      void draw(std::ostream& out) const { out << "Circle\n"; }
+    };
+
+    void f(drawable const& d) {
+      d.draw(std::cout);
+    }
+
+    int main() {
+      f(Square{}); // prints Square
+      f(Circle{}); // prints Circle
+    }
+```
+
+The above program prints:
+
+```
+    Square
+    Circle
+```
+
+Here is another (heavily commented) example of a simple implementation of a
+`std::function`-like polymorphic wrapper. Its interface has only a single
+member function: `operator()`
+
+``` Cpp
+    // An interface for a callable object of a particular signature, Fun
+    // (most interfaces don't need to be templates, FWIW).
+    template <class Fun>
+    struct IFunction;
+
+    template <class R, class... As>
+    struct IFunction<R(As...)> {
+      // An interface is defined as a nested class template called
+      // Interface that takes a single template parameter, Base, from
+      // which it inherits.
+      template <class Base>
+      struct Interface : Base {
+        // The Interface has public member functions. These become the
+        // public interface of the resulting Poly instantiation.
+        // (Implementation note: Poly<IFunction<Sig>> will publicly
+        // inherit from this struct, which is what gives it the right
+        // member functions.)
+        R operator()(As... as) const {
+          // The definition of each member function in your interface will
+          // always consist of a single line dispatching to folly::poly_call<N>.
+          // The "N" corresponds to the N-th member function in the
+          // list of member function bindings, Members, defined below.
+          // The first argument will always be *this, and the rest of the
+          // arguments should simply forward (if necessary) the member
+          // function's arguments.
+          return static_cast<R>(
+              folly::poly_call<0>(*this, std::forward<As>(as)...));
+        }
+      };
+      // The "Members" alias template is a comma-separated list of bound
+      // member functions for a given concrete type "T". The
+      // "FOLLY_POLY_MEMBERS" macro accepts a comma-separated list, and the
+      // (optional) "FOLLY_POLY_MEMBER" macro lets you disambiguate overloads
+      // by explicitly specifying the function signature the target member
+      // function should have. In this case, we require "T" to have a
+      // function call operator with the signature `R(As...) const`.
+      //
+      // If you are using a C++17-compatible compiler, you can do away with
+      // the macros and write this as:
+      //
+      //   template <class T>
+      //   using Members =
+      //       folly::PolyMembers<folly::sig<R(As...) const>(&T::operator())>;
+      //
+      // And since `folly::sig` is only needed for disambiguation in case of
+      // overloads, if you are not concerned about objects with overloaded
+      // function call operators, it could be further simplified to:
+      //
+      //   template <class T>
+      //   using Members = folly::PolyMembers<&T::operator()>;
+      //
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(
+          FOLLY_POLY_MEMBER(R(As...) const, &T::operator()));
+    };
+
+    // Now that we have defined the interface, we can pass it to Poly to
+    // create our type-erasing wrapper:
+    template <class Fun>
+    using Function = Poly<IFunction<Fun>>;
+```
+
+Given the above definition of `Function`, users can now initialize instances
+of (say) `Function<int(int, int)>` with function objects like
+`std::plus<int>` and `std::multiplies<int>`, as below:
+
+``` Cpp
+    Function<int(int, int)> fun = std::plus<int>{};
+    assert(5 == fun(2, 3));
+    fun = std::multiplies<int>{};
+    assert(6 = fun(2, 3));
+```
+
+### Defining an interface with C++17
+***
+
+With C++17, defining an interface to be used with `Poly` is fairly
+straightforward. As in the `Function` example above, there is a struct with
+a nested `Interface` class template and a nested `Members` alias template.
+No macros are needed with C++17.
+
+Imagine we were defining something like a Java-style iterator. If we are
+using a C++17 compiler, our interface would look something like this:
+
+``` Cpp
+    template <class Value>
+    struct IJavaIterator {
+      template <class Base>
+      struct Interface : Base {
+        bool Done() const { return folly::poly_call<0>(*this); }
+        Value Current() const { return folly::poly_call<1>(*this); }
+        void Next() { folly::poly_call<2>(*this); }
+      };
+      // NOTE: This works in C++17 only:
+      template <class T>
+      using Members = folly::PolyMembers<&T::Done, &T::Current, &T::Next>;
+    };
+
+    template <class Value>
+    using JavaIterator = Poly<IJavaIterator<Value>>;
+```
+
+Given the above definition, `JavaIterator<int>` can be used to hold instances
+of any type that has `Done`, `Current`, and `Next` member functions with the
+correct (or compatible) signatures.
+
+The presence of overloaded member functions complicates this picture. Often,
+property members are faked in C++ with `const` and non-`const` member
+function overloads, like in the interface specified below:
+
+``` Cpp
+    struct IIntProperty {
+      template <class Base>
+      struct Interface : Base {
+        int Value() const { return folly::poly_call<0>(*this); }
+        void Value(int i) { folly::poly_call<1>(*this, i); }
+      };
+      // NOTE: This works in C++17 only:
+      template <class T>
+      using Members = folly::PolyMembers<
+        folly::sig<int() const>(&T::Value),
+        folly::sig<void(int)>(&T::Value)>;
+    };
+
+    using IntProperty = Poly<IIntProperty>;
+```
+
+Now, any object that has `Value` members of compatible signatures can be
+assigned to instances of `IntProperty` object. Note how `folly::sig` is used
+to disambiguate the overloads of `&T::Value`.
+
+### Defining an interface with C++14
+***
+
+In C++14, the nice syntax above doesn't work, so we have to resort to macros.
+The two examples above would look like this:
+
+``` Cpp
+    template <class Value>
+    struct IJavaIterator {
+      template <class Base>
+      struct Interface : Base {
+        bool Done() const { return folly::poly_call<0>(*this); }
+        Value Current() const { return folly::poly_call<1>(*this); }
+        void Next() { folly::poly_call<2>(*this); }
+      };
+      // NOTE: This works in C++14 and C++17:
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(&T::Done, &T::Current, &T::Next);
+    };
+
+    template <class Value>
+    using JavaIterator = Poly<IJavaIterator<Value>>;
+```
+
+and
+
+``` Cpp
+    struct IIntProperty {
+      template <class Base>
+      struct Interface : Base {
+        int Value() const { return folly::poly_call<0>(*this); }
+        void Value(int i) { return folly::poly_call<1>(*this, i); }
+      };
+      // NOTE: This works in C++14 and C++17:
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(
+        FOLLY_POLY_MEMBER(int() const, &T::Value),
+        FOLLY_POLY_MEMBER(void(int), &T::Value));
+    };
+
+    using IntProperty = Poly<IIntProperty>;
+```
+
+### Extending interfaces
+***
+
+One typical advantage of inheritance-based solutions to runtime polymorphism
+is that one polymorphic interface could extend another through inheritance.
+The same can be accomplished with type-erasing polymorphic wrappers. In
+the `Poly` library, you can use `folly::PolyExtends` to say that one interface
+extends another.
+
+``` Cpp
+    struct IFoo {
+      template <class Base>
+      struct Interface : Base {
+        void Foo() const { return folly::poly_call<0>(*this); }
+      };
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(&T::Foo);
+    };
+
+    // The IFooBar interface extends the IFoo interface
+    struct IFooBar : PolyExtends<IFoo> {
+      template <class Base>
+      struct Interface : Base {
+        void Bar() const { return folly::poly_call<0>(*this); }
+      };
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(&T::Bar);
+    };
+
+    using FooBar = Poly<IFooBar>;
+```
+
+Given the above definition, instances of type `FooBar` have both `Foo()` and
+`Bar()` member functions.
+
+The sensible conversions exist between a wrapped derived type and a wrapped
+base type. For instance, assuming `IDerived` extends `IBase` with `PolyExtends`:
+
+``` Cpp
+    Poly<IDerived> derived = ...;
+    Poly<IBase> base = derived; // This conversion is OK.
+```
+
+As you would expect, there is no conversion in the other direction, and at
+present there is no `Poly` equivalent to `dynamic_cast`.
+
+### Type-erasing polymorphic reference wrappers
+***
+
+Sometimes you don't need to own a copy of an object; a reference will do. For
+that you can use `Poly` to capture a _reference_ to an object satisfying an
+interface rather than the whole object itself. The syntax is intuitive.
+
+``` Cpp
+    int i = 42;
+
+    // Capture a mutable reference to an object of any IRegular type:
+    Poly<IRegular &> intRef = i;
+
+    assert(42 == folly::poly_cast<int>(intRef));
+    // Assert that we captured the address of "i":
+    assert(&i == &folly::poly_cast<int>(intRef));
+```
+
+A reference-like `Poly` has a different interface than a value-like `Poly`.
+Rather than calling member functions with the `obj.fun()` syntax, you would
+use the `obj->fun()` syntax. This is for the sake of `const`-correctness.
+For example, consider the code below:
+
+``` Cpp
+    struct IFoo {
+      template <class Base>
+      struct Interface {
+        void Foo() { folly::poly_call<0>(*this); }
+      };
+      template <class T>
+      using Members = folly::PolyMembers<&T::Foo>;
+    };
+
+    struct SomeFoo {
+      void Foo() { std::printf("SomeFoo::Foo\n"); }
+    };
+
+    SomeFoo foo;
+    Poly<IFoo &> const anyFoo = foo;
+    anyFoo->Foo(); // prints "SomeFoo::Foo"
+```
+
+Notice in the above code that the `Foo` member function is non-`const`.
+Notice also that the `anyFoo` object is `const`. However, since it has
+captured a non-`const` reference to the `foo` object, it should still be
+possible to dispatch to the non-`const` `Foo` member function. When
+instantiated with a reference type, `Poly` has an overloaded `operator->`
+member that returns a pointer to the `IFoo` interface with the correct
+`const`-ness, which makes this work.
+
+The same mechanism also prevents users from calling non-`const` member
+functions on `Poly` objects that have captured `const` references, which
+would violate `const`-correctness.
+
+Sensible conversions exist between non-reference and reference `Poly`s. For
+instance:
+
+``` Cpp
+    Poly<IRegular> value = 42;
+    Poly<IRegular &> mutable_ref = value;
+    Poly<IRegular const &> const_ref = mutable_ref;
+
+    assert(&poly_cast<int>(value) == &poly_cast<int>(mutable_ref));
+    assert(&poly_cast<int>(value) == &poly_cast<int>(const_ref));
+```
+
+### Non-member functions (C++17)
+***
+
+If you wanted to write the interface `ILogicallyNegatable`, which captures
+all types that can be negated with unary `operator!`, you could do it
+as we've shown above, by binding `&T::operator!` in the nested `Members`
+alias template, but that has the problem that it won't work for types that
+have defined unary `operator!` as a free function. To handle this case,
+the `Poly` library lets you use a free function instead of a member function
+when creating a binding.
+
+With C++17 you may use a lambda to create a binding, as shown in the example
+below:
+
+``` Cpp
+    struct ILogicallyNegatable {
+      template <class Base>
+      struct Interface : Base {
+        bool operator!() const { return folly::poly_call<0>(*this); }
+      };
+      template <class T>
+      using Members = folly::PolyMembers<
+        +[](T const& t) -> decltype(bool(!t)) { return bool(!t); }>;
+    };
+```
+
+This requires some explanation. The unary `operator+` in front of the lambda
+is necessary! It causes the lambda to decay to a C-style function pointer,
+which is one of the types that `folly::PolyMembers` accepts. The `decltype` in
+the lambda return type is also necessary. Through the magic of SFINAE, it
+will cause `Poly<ILogicallyNegatable>` to reject any types that don't support
+unary `operator!`.
+
+If you are using a free function to create a binding, the first parameter is
+implicitly the `this` parameter. It will receive the type-erased object.
+
+### Non-member functions (C++14)
+***
+
+If you are using a C++14 compiler, the definition of `ILogicallyNegatable`
+above will fail because lambdas are not `constexpr`. We can get the same
+effect by writing the lambda as a named free function, as show below:
+
+``` Cpp
+    struct ILogicallyNegatable {
+      template <class Base>
+      struct Interface : Base {
+        bool operator!() const { return folly::poly_call<0>(*this); }
+      };
+      template <class T>
+      static auto negate(T const& t)
+        -> decltype(bool(!t)) { return bool(!t); }
+      template <class T>
+      using Members = FOLLY_POLY_MEMBERS(&negate<T>);
+    };
+```
+
+As with the example that uses the lambda in the preceding section, the first
+parameter is implicitly the `this` parameter. It will receive the type-erased
+object.
+
+### Multi-dispatch
+***
+
+What if you want to create an `IAddable` interface for things that can be
+added? Adding requires _two_ objects, both of which are type-erased. This
+interface requires dispatching on both objects, doing the addition only
+if the types are the same. For this we make use of the `PolySelf` template
+alias to define an interface that takes more than one object of the
+erased type.
+
+``` Cpp
+    struct IAddable {
+      template <class Base>
+      struct Interface : Base {
+        friend PolySelf<Base>
+        operator+(PolySelf<Base> const& a, PolySelf<Base> const& b) const {
+          return folly::poly_call<0>(a, b);
+        }
+      };
+      template <class T>
+      using Members = folly::PolyMembers<
+        +[](T const& a, T const& b) -> decltype(a + b) { return a + b; }>;
+    };
+```
+
+Given the above definition of `IAddable` we would be able to do the following:
+
+``` Cpp
+    Poly<IAddable> a = 2, b = 3;
+    Poly<IAddable> c = a + b;
+    assert(poly_cast<int>(c) == 5);
+```
+
+If `a` and `b` stored objects of different types, a `BadPolyCast` exception
+would be thrown.
+
+### Move-only types
+***
+
+If you want to store move-only types, then your interface should extend the
+`poly::IMoveOnly` interface.
+
+### Implementation notes
+***
+
+`Poly` will store "small" objects in an internal buffer, avoiding the cost of
+of dynamic allocations. At present, this size is not configurable; it is
+pegged at the size of two `double`s.
+
+`Poly` objects are always nothrow movable. If you store an object in one that
+has a potentially throwing move constructor, the object will be stored on the
+heap, even if it could fit in the internal storage of the `Poly` object.
+(So be sure to give your objects nothrow move constructors!)
+
+`Poly` implements type-erasure in a manner very similar to how the compiler
+accomplishes virtual dispatch. Every `Poly` object contains a pointer to a
+table of function pointers. Member function calls involve a double-
+indirection: once through the v-pointer, and other indirect function call
+through the function pointer.

package/external/folly/folly/docs/ProducerConsumerQueue.md

@@ -0,0 +1,82 @@
+`folly/ProducerConsumerQueue.h`
+-------------------------------
+
+The `folly::ProducerConsumerQueue` class is a one-producer
+one-consumer queue with very low synchronization overhead.
+
+The queue must be created with a fixed maximum size (and allocates
+that many cells of sizeof(T)), and it provides just a few simple
+operations:
+
+ * `read`: Attempt to read the value at the front to the queue into a variable,
+           returns `false` iff queue was empty.
+ * `write`: Emplace a value at the end of the queue, returns `false` iff the
+            queue was full.
+ * `frontPtr`: Retrieve a pointer to the item at the front of the queue, or
+               `nullptr` if it is empty.
+ * `popFront`: Remove the item from the front of the queue (queue must not be
+               empty).
+ * `isEmpty`: Check if the queue is empty.
+ * `isFull`: Check if the queue is full.
+ * `sizeGuess`: Returns the number of entries in the queue. Because of the
+                way we coordinate threads, this guess could be slightly wrong
+                when called by the producer/consumer thread, and it could be
+                wildly inaccurate if called from any other threads. Hence,
+                only call from producer/consumer threads!
+
+All of these operations are wait-free.  The read operations (including
+`frontPtr` and `popFront`) and write operations must only be called by the
+reader and writer thread, respectively. `isFull`, `isEmpty`, and `sizeGuess`
+may be called by either thread, but the return values from `read`, `write`, or
+`frontPtr` are sufficient for most cases.
+
+`write` may fail if the queue is full, and `read` may fail if the queue is
+empty, so in many situations it is important to choose the queue size such that
+the queue filling  or staying empty for long is unlikely.
+
+### Example
+***
+
+A toy example that doesn't really do anything useful:
+
+``` Cpp
+    folly::ProducerConsumerQueue<folly::fbstring> queue{size};
+
+    std::thread reader([&queue] {
+      for (;;) {
+        folly::fbstring str;
+        while (!queue.read(str)) {
+          //spin until we get a value
+          continue;
+        }
+
+        sink(str);
+      }
+    });
+
+    // producer thread:
+    for (;;) {
+      folly::fbstring str = source();
+      while (!queue.write(str)) {
+        //spin until the queue has room
+        continue;
+      }
+    }
+```
+
+Alternatively, the consumer may be written as follows to use the 'front' value
+in place, thus avoiding moves or copies:
+
+``` Cpp
+    std::thread reader([&queue] {
+      for (;;) {
+        folly::fbstring* pval;
+        do {
+          pval = queue.frontPtr();
+        } while (!pval); // spin until we get a value;
+
+        sink(*pval);
+        queue.popFront();
+      }
+    });
+```