react-native-windows 0.81.35 → 0.81.37

package/external/folly/folly/docs/Dynamic.md

@@ -0,0 +1,220 @@
+`folly/dynamic.h`
+-----------------
+
+`folly/dynamic.h` provides a runtime dynamically typed value for
+C++, similar to the way languages with runtime type systems work
+(e.g. Python). It can hold types from a predetermined set of types
+(ints, bools, arrays of other dynamics, etc), similar to something like
+`std::variant`, but the syntax is intended to be a little more like
+using the native type directly.
+
+### Overview
+***
+
+Here are some code samples to get started (assumes a `using
+folly::dynamic;` was used):
+
+``` Cpp
+    dynamic twelve = 12; // creates a dynamic that holds an integer
+    dynamic str = "string"; // yep, this one is an fbstring
+
+    // A few other types.
+    dynamic nul = nullptr;
+    dynamic boolean = false;
+
+    // Arrays can be initialized with dynamic::array.
+    dynamic array = dynamic::array("array ", "of ", 4, " elements");
+    assert(array.size() == 4);
+    dynamic emptyArray = dynamic::array;
+    assert(emptyArray.empty());
+
+    // Maps from dynamics to dynamics are called objects.  The
+    // dynamic::object constant is how you make an empty map from dynamics
+    // to dynamics.
+    dynamic map = dynamic::object;
+    map["something"] = 12;
+    map["another_something"] = map["something"] * 2;
+
+    // Dynamic objects may be initialized this way
+    dynamic map2 = dynamic::object("something", 12)("another_something", 24);
+```
+
+### Runtime Type Checking and Conversions
+***
+
+Any operation on a dynamic requires checking at runtime that the
+type is compatible with the operation. If it isn't, you'll get a
+`folly::TypeError`. Other exceptions can also be thrown if
+you try to do something impossible (e.g. if you put a very large
+64-bit integer in and try to read it out as a double).
+
+More examples should hopefully clarify this:
+
+``` Cpp
+    dynamic dint = 42;
+
+    dynamic str = "foo";
+    dynamic anotherStr = str + "something"; // fine
+    dynamic thisThrows = str + dint; // TypeError is raised
+```
+
+Explicit type conversions can be requested for some of the basic types:
+
+``` Cpp
+    dynamic dint = 12345678;
+    dynamic doub = dint.asDouble(); // doub will hold 12345678.0
+    dynamic str = dint.asString(); // str == "12345678"
+
+    dynamic hugeInt = std::numeric_limits<int64_t>::max();
+    dynamic hugeDoub = hugeInt.asDouble();  // throws a folly/Conv.h error,
+                                            // since it can't fit in a double
+```
+
+For more complicated conversions, see [DynamicConverter](DynamicConverter.md).
+
+### Comparison Operators and Hashing
+#### Equality Operators
+Equality operators (`==`, `!=`) are supported for all types.
+
+For dynamics of the same type, the underlying equality operator shall apply.
+
+For comparisons between different numeric types (double and int64), numeric
+equality will apply - thus `2.0 == 2`.
+
+Values of any other different types will be deemed to not be equal.
+
+#### Ordering operators
+Ordering operators (`<`, `<=`, `>`, `>=`) are supported for all types, except
+`dynamic::object` which will throw if it is involved in an ordering operator.
+
+For dynamics of the same type, the underlying ordering operator shall apply.
+
+For comparisons between different numeric types (double and int64), numeric
+ordering will apply - thus `1.5 < 2`.
+
+Ordering of values between other different types will maintain total ordering
+properties and be consistent within a given binary run, and thus safe for use in
+e.g. `std::set`. The actual ordering is undefined and could change across
+versions, thus a dependency should not be taken outside of the total ordering
+property within a given binary.
+
+#### Hashing
+Hashing is supported by all types, and the hashes of two values will match if
+they are equal per `dynamic::operator==`.
+
+As a result, numerical types have the same numerical hashing regardless of int64
+vs double - so e.g. `std::hash<dynamic>()(2)` will give the same value as
+`std::hash<dynamic>()(2.0)`.
+
+### Iteration and Lookup
+***
+
+You can iterate over dynamic arrays as you would over any C++ sequence container.
+
+``` Cpp
+    dynamic array = dynamic::array(2, 3, "foo");
+
+    for (auto& val : array) {
+      doSomethingWith(val);
+    }
+```
+
+You can iterate over dynamic maps by calling `items()`, `keys()`,
+`values()`, which behave similarly to the homonymous methods of Python
+dictionaries.
+
+``` Cpp
+    dynamic obj = dynamic::object(2, 3)("hello", "world")("x", 4);
+
+    for (auto& pair : obj.items()) {
+      // Key is pair.first, value is pair.second
+      processKey(pair.first);
+      processValue(pair.second);
+    }
+
+    for (auto& key : obj.keys()) {
+      processKey(key);
+    }
+
+    for (auto& value : obj.values()) {
+      processValue(value);
+    }
+```
+
+You can find an element by key in a dynamic map using the `find()` method,
+which returns an iterator compatible with `items()`:
+
+``` Cpp
+    dynamic obj = dynamic::object(2, 3)("hello", "world")("x", 4);
+
+    auto pos = obj.find("hello");
+    // pos->first is "hello"
+    // pos->second is "world"
+
+    auto pos = obj.find("no_such_key");
+    // pos == obj.items().end()
+```
+
+
+### Use for JSON
+***
+
+The original motivation for implementing this type was to try to
+make dealing with json documents in C++ almost as easy as it is
+in languages with dynamic type systems (php or javascript, etc).
+The reader can judge whether we're anywhere near that goal, but
+here's what it looks like:
+
+``` Cpp
+    // Parsing JSON strings and using them.
+    std::string jsonDocument = R"({"key":12,"key2":[false, null, true, "yay"]})";
+    dynamic parsed = folly::parseJson(jsonDocument);
+    assert(parsed["key"] == 12);
+    assert(parsed["key2"][0] == false);
+    assert(parsed["key2"][1] == nullptr);
+
+    // Building the same document programmatically.
+    dynamic sonOfAJ = dynamic::object
+      ("key", 12)
+      ("key2", dynamic::array(false, nullptr, true, "yay"));
+
+    // Printing.  (See also folly::toPrettyJson)
+    auto str = folly::toJson(sonOfAJ);
+    assert(jsonDocument.compare(str) == 0);
+```
+
+### Performance
+***
+
+Dynamic typing is more expensive than static typing, even when
+you do it in C++. ;)
+
+However, some effort has been made to keep `folly::dynamic` and
+the json (de)serialization at least reasonably performant for
+common cases. The heap is only used for arrays and objects, and
+move construction is fully supported. String formatting
+internally also uses the highly performant `folly::to<>` (see
+`folly/Conv.h`).
+
+A trade off to keep in mind though, is that
+`sizeof(folly::dynamic)` is 64 bytes. You probably don't want to
+use it if you need to allocate large numbers of them (prefer
+static types, etc).
+
+### Some Design Rationale
+***
+
+**Q. Why doesn't a dynamic string support begin(), end(), and operator[]?**
+
+The value_type of a dynamic iterator is `dynamic`, and `operator[]`
+(or the `at()` function) has to return a reference to a dynamic.  If
+we wanted this to work for strings, this would mean we'd have to
+support dynamics with a character type, and moreover that the internal
+representation of strings would be such that we can hand out
+references to dynamic as accessors on individual characters.  There
+are a lot of potential efficiency drawbacks with this, and it seems
+like a feature that is not needed too often in practice.
+
+**Q. Isn't this just a poor imitation of the C# language feature?**
+
+Pretty much.

package/external/folly/folly/docs/DynamicConverter.md

@@ -0,0 +1,71 @@
+`folly/DynamicConverter.h`
+--------------------------
+
+When dynamic objects contain data of a known type, it is sometimes
+useful to have its well-typed representation. A broad set of
+type-conversions are contained in `DynamicConverter.h`, and
+facilitate the transformation of dynamic objects into their well-typed
+format.
+
+### Usage
+***
+
+Simply pass a dynamic into a templated convertTo:
+
+```cpp
+    dynamic d = { { 1, 2, 3 }, { 4, 5 } }; // a vector of vector of int
+    auto vvi = convertTo<fbvector<fbvector<int>>>(d);
+```
+
+### Supported Types
+***
+
+convertTo naturally supports conversions to
+
+1. arithmetic types (such as int64_t, unsigned short, bool, and double)
+2. fbstring, std::string
+3. containers and map-containers
+
+NOTE:
+
+convertTo<Type> will assume that Type is a container if
+* it has a Type::value_type, and
+* it has a Type::iterator, and
+* it has a constructor that accepts two InputIterators
+
+Additionally, convertTo<Type> will assume that Type is a map if
+* it has a Type::key_type, and
+* it has a Type::mapped_type, and
+* value_type is a pair of const key_type and mapped_type
+
+If Type meets the container criteria, then it will be constructed
+by calling its InputIterator constructor.
+
+### Customization
+***
+
+If you want to use convertTo to convert dynamics into your own custom
+class, then all you have to do is provide a template specialization
+of DynamicConverter with the static method convert. Make sure you put it
+in namespace folly.
+
+Example:
+
+``` Cpp
+    struct Token {
+      int kind_;
+      fbstring lexeme_;
+      
+      explicit Token(int kind, const fbstring& lexeme)
+        : kind_(kind), lexeme_(lexeme) {}
+    };
+    namespace folly {
+    template <> struct DynamicConverter<Token> {
+      static Token convert(const dynamic& d) {
+        int k = convertTo<int>(d["KIND"]);
+        fbstring lex = convertTo<fbstring>(d["LEXEME"]);
+        return Token(k, lex);
+      }
+    };
+    }
+```

package/external/folly/folly/docs/Executors.md

@@ -0,0 +1,63 @@
+<section class="dex_document"><h1>Thread pools &amp; Executors</h1><p class="dex_introduction">Run your concurrent code in a performant way</p><h2 id="all-about-thread-pools">All about thread pools <a href="#all-about-thread-pools" class="headerLink">#</a></h2>
+
+<h3 id="how-do-i-use-the-thread">How do I use the thread pools? <a href="#how-do-i-use-the-thread" class="headerLink">#</a></h3>
+
+<p>Wangle provides two concrete thread pools (IOThreadPoolExecutor, CPUThreadPoolExecutor) as well as building them in as part of a complete async framework.  Generally you might want to grab the global executor, and use it with a future, like this:</p>
+
+<div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code"><span class="no">auto</span> <span class="no">f</span> <span class="o">=</span> <span class="nf" data-symbol-name="someFutureFunction">someFutureFunction</span><span class="o">().</span><span class="nf" data-symbol-name="via">via</span><span class="o">(</span><span class="nf" data-symbol-name="getCPUExecutor">getCPUExecutor</span><span class="o">()).</span><span class="nf" data-symbol-name="then">then</span><span class="o">(...)</span></pre></div>
+
+<p>Or maybe you need to construct a thrift/memcache client, and need an event base:</p>
+
+<div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code"><span class="no">auto</span> <span class="no">f</span> <span class="o">=</span> <span class="nf" data-symbol-name="getClient">getClient</span><span class="o">(</span><span class="nf" data-symbol-name="getIOExecutor">getIOExecutor</span><span class="o">()-&gt;</span><span class="na" data-symbol-name="getEventBase">getEventBase</span><span class="o">())-&gt;</span><span class="na" data-symbol-name="callSomeFunction">callSomeFunction</span><span class="o">(</span><span class="no">args</span><span class="o">...)</span>
+         <span class="o">.</span><span class="nf" data-symbol-name="via">via</span><span class="o">(</span><span class="nf" data-symbol-name="getCPUExecutor">getCPUExecutor</span><span class="o">())</span>
+         <span class="o">.</span><span class="nf" data-symbol-name="then">then</span><span class="o">([](</span><span class="no">Result</span> <span class="no">r</span><span class="o">)&#123;</span> <span class="o">....</span> <span class="k">do</span> <span class="no">something</span> <span class="no">with</span> <span class="no">result</span><span class="o">&#125;);</span></pre></div>
+
+<h3 id="vs-c-11-s-std-launch">vs. C++11&#039;s std::launch <a href="#vs-c-11-s-std-launch" class="headerLink">#</a></h3>
+
+<p>The current C++11 std::launch only has two modes: async or deferred.  In a production system, neither is what you want:  async will launch a new thread for every launch without limit, while deferred will defer the work until it is needed lazily, but then do the work <strong>in the current thread synchronously</strong> when it is needed.</p>
+
+<p>Wangle&#039;s thread pools always launch work as soon as possible, have limits to the maximum number of tasks / threads allowed, so we will never use more threads than absolutely needed.  See implementation details below about each type of executor.</p>
+
+<h3 id="why-do-we-need-yet-anoth">Why do we need yet another set of thread pools? <a href="#why-do-we-need-yet-anoth" class="headerLink">#</a></h3>
+
+<p>Unfortunately none of the existing thread pools had every feature needed - things based on pipes are too slow.   Several older ones didn&#039;t support std::function.</p>
+
+<h3 id="why-do-we-need-several-d">Why do we need several different types of thread pools? <a href="#why-do-we-need-several-d" class="headerLink">#</a></h3>
+
+<p>If you want epoll support, you need an fd - event_fd is the latest notification hotness.   Unfortunately, an active fd triggers all the epoll loops it is in, leading to thundering herd - so if you want a fair queue (one queue total vs. one queue per worker thread), you need to use some kind of semaphore.  Unfortunately semaphores can&#039;t be put in epoll loops, so they are incompatible with IO.   Fortunately, you usually want to separate the IO and CPU bound work anyway to give stronger tail latency guarantees on IO.</p>
+
+<h3 id="iothreadpoolexecutor">IOThreadPoolExecutor <a href="#iothreadpoolexecutor" class="headerLink">#</a></h3>
+
+<ul>
+<li>Uses event_fd for notification, and waking an epoll loop.</li>
+<li>There is one queue (NotificationQueue specifically) per thread/epoll.</li>
+<li>If the thread is already running and not waiting on epoll, we don&#039;t make any additional syscalls to wake up the loop, just put the new task in the queue.</li>
+<li>If any thread has been waiting for more than a few seconds, its stack is madvised away.   Currently however tasks are scheduled round robin on the queues, so unless there is <strong>no</strong> work going on, this isn&#039;t very effective.</li>
+<li>::getEventBase() will return an EventBase you can schedule IO work on directly, chosen round-robin.</li>
+<li>Since there is one queue per thread, there is hardly any contention on the queues - so a simple spinlock around an std::deque is used for the tasks.  There is no max queue size.</li>
+<li>By default, there is one thread per core - it usually doesn&#039;t make sense to have more IO threads than this, assuming they don&#039;t block.</li>
+</ul>
+
+<h3 id="cputhreadpoolexecutor">CPUThreadPoolExecutor <a href="#cputhreadpoolexecutor" class="headerLink">#</a></h3>
+
+<ul>
+<li>A single queue backed by folly/LifoSem and folly/MPMC queue.  Since there is only a single queue, contention can be quite high, since all the worker threads and all the producer threads hit the same queue.  MPMC queue excels in this situation.  MPMC queue dictates a max queue size.</li>
+<li>LifoSem wakes up threads in Lifo order - i.e. there are only few threads as necessary running, and we always try to reuse the same few threads for better cache locality.</li>
+<li>Inactive threads have their stack madvised away.  This works quite well in combination with Lifosem - it almost doesn&#039;t matter if more threads than are necessary are specified at startup.</li>
+<li>stop() will finish all outstanding tasks at exit</li>
+<li>Supports priorities - priorities are implemented as multiple queues - each worker thread checks the highest priority queue first.  Threads themselves don&#039;t have priorities set, so a series of long running low priority tasks could still hog all the threads.  (at last check pthreads thread priorities didn&#039;t work very well)</li>
+</ul>
+
+<h3 id="threadpoolexecutor">ThreadPoolExecutor <a href="#threadpoolexecutor" class="headerLink">#</a></h3>
+
+<p>Base class that contains the thread startup/shutdown/stats logic, since this is pretty disjoint from how tasks are actually run</p>
+
+<h3 id="observers">Observers <a href="#observers" class="headerLink">#</a></h3>
+
+<p>An observer interface is provided to listen for thread start/stop events.  This is useful to create objects that should be one-per-thread, but also have them work correctly if threads are added/removed from the thread pool.</p>
+
+<h3 id="stats">Stats <a href="#stats" class="headerLink">#</a></h3>
+
+<p>PoolStats are provided to get task count, running time, waiting time, etc.</p>
+</section>
+

package/external/folly/folly/docs/FBString.md

@@ -0,0 +1,46 @@
+`folly/FBString.h`
+------------------
+
+`fbstring` is a drop-in replacement for `std::string`. The main
+benefit of `fbstring` is significantly increased performance on
+virtually all important primitives. This is achieved by using a
+three-tiered storage strategy and by cooperating with the memory
+allocator. In particular, `fbstring` is designed to detect use of
+jemalloc and cooperate with it to achieve significant improvements in
+speed and memory usage.
+
+`fbstring` supports 32- and 64-bit and little- and big-endian
+architectures.
+
+### Storage strategies
+***
+
+* Small strings (<= 23 chars) are stored in-situ without memory
+  allocation.
+
+* Medium strings (24 - 255 chars) are stored in malloc-allocated
+  memory and copied eagerly.
+
+* Large strings (> 255 chars) are stored in malloc-allocated memory and
+  copied lazily.
+
+### Implementation highlights
+***
+
+* 100% compatible with `std::string`.
+
+* Thread-safe reference counted copy-on-write for "large"
+  strings (> 255 chars).
+
+* Uses `malloc` instead of allocators.
+
+* Jemalloc-friendly. `fbstring` automatically detects if application
+  uses jemalloc and if so, significantly improves allocation
+  strategy by using non-standard jemalloc extensions.
+
+* `find()` is implemented using simplified Boyer-Moore
+  algorithm. Casual tests indicate a 30x speed improvement over
+  `string::find()` for successful searches and a 1.5x speed
+  improvement for failed searches.
+
+* Offers conversions to and from `std::string`.

package/external/folly/folly/docs/FBVector.md

@@ -0,0 +1,200 @@
+`folly/FBVector.h`
+------------------
+
+Simply replacing `std::vector` with `folly::fbvector` (after
+having included the `folly/FBVector.h` header file) will
+improve the performance of your C++ code using vectors with
+common coding patterns. The improvements are always non-negative,
+almost always measurable, frequently significant, sometimes
+dramatic, and occasionally spectacular.
+
+### Sample
+***
+```cpp
+    folly::fbvector<int> numbers({0, 1, 2, 3});
+    numbers.reserve(10);
+    for (int i = 4; i < 10; i++) {
+      numbers.push_back(i * 2);
+    }
+    assert(numbers[6] == 12);
+```
+### Motivation
+***
+
+`std::vector` is the stalwart abstraction many use for
+dynamically-allocated arrays in C++. It is also the best known
+and most used of all containers. It may therefore seem a
+surprise that `std::vector` leaves important - and sometimes
+vital - efficiency opportunities on the table. This document
+explains how our own drop-in abstraction `fbvector` improves key
+performance aspects of `std::vector`. Refer to
+folly/test/FBVectorTest.cpp for a few benchmarks.
+
+### Memory Handling
+***
+
+It is well known that `std::vector` grows exponentially (at a
+constant factor) in order to avoid quadratic growth performance.
+The trick is choosing a good factor. Any factor greater than 1
+ensures O(1) amortized append complexity towards infinity. But a
+factor that's too small (say, 1.1) causes frequent vector reallocation, and
+one that's too large (say, 3 or 4) forces the vector to consume much more
+memory than needed.
+
+The initial HP implementation by Stepanov used a
+growth factor of 2; i.e., whenever you'd `push_back` into a vector
+without there being room, it would double the current capacity. This
+was not a good choice: it can be mathematically proven that a growth factor of
+2 is rigorously the <i>worst</i> possible because it never allows the vector 
+to reuse any of its previously-allocated memory. Despite other compilers
+reducing the growth factor to 1.5, gcc has staunchly maintained its factor of
+2. This makes `std::vector` cache- unfriendly and memory manager unfriendly.
+
+To see why that's the case, consider a large vector of capacity C.
+When there's a request to grow the vector, the vector
+(assuming no in-place resizing, see the appropriate section in
+this document) will allocate a chunk of memory next to its current chunk,
+copy its existing data to the new chunk, and then deallocate the old chunk.
+So now we have a chunk of size C followed by a chunk of size k * C. Continuing
+this process we'll then have a chunk of size k * k * C to the right and so on.
+That leads to a series of the form (using ^^ for power):
+
+    C, C*k,  C*k^^2, C*k^^3, ...
+
+If we choose k = 2 we know that every element in the series will
+be strictly larger than the sum of all previous ones because of
+the remarkable equality:
+
+    1 + 2^^1 + 2^^2 + 2^^3... + 2^^n = 2^^(n+1) - 1
+
+This means that any new chunk requested will be larger
+than all previously used chunks combined, so the vector must
+crawl forward in memory; it can't move back to its deallocated chunks.
+But any number smaller than 2 guarantees that you'll at some point be 
+able to reuse the previous chunks. For instance, choosing 1.5 as the factor
+allows memory reuse after 4 reallocations; 1.45 allows memory reuse after 3
+reallocations; and 1.3 allows reuse after only 2 reallocations.
+
+Of course, the above makes a number of simplifying assumptions
+about how the memory allocator works, but definitely you don't
+want to choose the theoretically absolute worst growth factor.
+`fbvector` uses a growth factor of 1.5. That does not impede good
+performance at small sizes because of the way `fbvector`
+cooperates with jemalloc (below).
+
+### The jemalloc Connection
+***
+
+Virtually all modern allocators allocate memory in fixed-size
+quanta that are chosen to minimize management overhead while at
+the same time offering good coverage at low slack. For example, an
+allocator may choose blocks of doubling size (32, 64, 128,
+<t_co>, ...) up to 4096, and then blocks of size multiples of a
+page up until 1MB, and then 512KB increments and so on.
+
+As discussed above, `std::vector` also needs to (re)allocate in
+quanta. The next quantum is usually defined in terms of the
+current size times the infamous growth constant. Because of this
+setup, `std::vector` has some slack memory at the end much like
+an allocated block has some slack memory at the end.
+
+It doesn't take a rocket surgeon to figure out that an allocator-
+aware `std::vector` would be a marriage made in heaven: the
+vector could directly request blocks of "perfect" size from the
+allocator so there would be virtually no slack in the allocator.
+Also, the entire growth strategy could be adjusted to work
+perfectly with allocator's own block growth strategy. That's
+exactly what `fbvector` does - it automatically detects the use
+of jemalloc and adjusts its reallocation strategy accordingly.
+
+But wait, there's more. Many memory allocators do not support in-
+place reallocation, although most of them could. This comes from
+the now notorious design of `realloc()` to opaquely perform
+either in-place reallocation or an allocate-memcpy-deallocate
+cycle. Such lack of control subsequently forced all clib-based
+allocator designs to avoid in-place reallocation, and that
+includes C++'s `new` and `std::allocator`. This is a major loss of
+efficiency because an in-place reallocation, being very cheap,
+may mean a much less aggressive growth strategy. In turn that
+means less slack memory and faster reallocations.
+
+### Object Relocation
+***
+
+One particularly sensitive topic about handling C++ values is
+that they are all conservatively considered <i>non-
+relocatable</i>. In contrast, a relocatable value would preserve
+its invariant even if its bits were moved arbitrarily in memory.
+For example, an `int32_t` is relocatable because moving its 4 bytes
+would preserve its actual value, so the address of that value
+does not "matter" to its integrity.
+
+C++'s assumption of non-relocatable values hurts everybody for
+the benefit of a few questionable designs. The issue is that
+moving a C++ object "by the book" entails (a) creating a new copy
+from the existing value; (b) destroying the old value. This is
+quite vexing and violates common sense; consider this
+hypothetical conversation between Captain Picard and an
+incredulous alien:
+
+Incredulous Alien: "So, this teleporter, how does it work?"<br>
+Picard: "It beams people and arbitrary matter from one place to
+another."<br> Incredulous Alien: "Hmmm... is it safe?"<br>
+Picard: "Yes, but earlier models were a hassle. They'd clone the
+person to another location. Then the teleporting chief would have
+to shoot the original. Ask O'Brien, he was an intern during those
+times. A bloody mess, that's what it was."
+
+Only a tiny minority of objects are genuinely non-relocatable:
+
+* Objects that use internal pointers, e.g.:
+```cpp
+    class Ew {
+      char buffer[1024];
+      char * pointerInsideBuffer;
+    public:
+      Ew() : pointerInsideBuffer(buffer) {}
+      ...
+    }
+```
+* Objects that need to update "observers" that store pointers to them.
+
+The first class of designs can always be redone at small or no
+cost in efficiency. The second class of objects should not be
+values in the first place - they should be allocated with `new`
+and manipulated using (smart) pointers. It is highly unusual for
+a value to have observers that alias pointers to it.
+
+Relocatable objects are of high interest to `std::vector` because
+such knowledge makes insertion into the vector and vector
+reallocation considerably faster: instead of going to Picard's
+copy-destroy cycle, relocatable objects can be moved around
+simply by using `memcpy` or `memmove`. This optimization can
+yield arbitrarily high wins in efficiency; for example, it
+transforms `vector< vector<double> >` or `vector< hash_map<int,
+string> >` from risky liabilities into highly workable
+compositions.
+
+In order to allow fast relocation without risk, `fbvector` uses a
+trait `folly::IsRelocatable` defined in `"folly/Traits.h"`. By default,
+`folly::IsRelocatable::value` conservatively yields false. If
+you know that your type `Widget` is in fact relocatable, go right
+after `Widget`'s definition and write this:
+```cpp
+    // at global namespace level
+    namespace folly {
+      struct IsRelocatable<Widget> : boost::true_type {};
+    }
+```
+If you don't do this, `fbvector<Widget>` will fail to compile
+with a `static_assert`.
+
+### Miscellaneous
+***
+
+`fbvector` uses a careful implementation all around to make
+sure it doesn't lose efficiency through the cracks. Some future
+directions may be in improving raw memory copying (`memcpy` is
+not an intrinsic in gcc and does not work terribly well for
+large chunks) and in furthering the collaboration with
+jemalloc. Have fun!