Summary: [Folly] Fix `folly/hash/detail/Crc32CombineDetail.cpp` with `-Werror=attributes`.

Reviewed By: tehnerd

Differential Revision: D9507179

fbshipit-source-id: 67ce235a5e1555973a276de2b4009acab2329ddc

Summary:
[Folly] Compute the crc32c and crc32 powers tables at compile time v.s. hardcoding the tables.

We translate `gf_multiply_sw` to C++11 `constexpr` form for those cases which still require gcc49.

Reviewed By: djwatson

Differential Revision: D9495241

fbshipit-source-id: 39aa8b53f7bd8a6dec1ba49013636c57972ef93b

Summary:
Modify the implementations of thenValue and thenError to be in terms of thenImplementation rather than then.

This is a preliminary transformation before splitting then and deprecating parts of it in turn.

Reviewed By: marshallcline

Differential Revision: D9494305

fbshipit-source-id: 38cd165866f98514ee506dc01f625b7df1db211b

Summary:
This is part of "the great r-valuification of folly::Future":

* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).thenMulti(...)` instead of `f.thenMulti(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9437627

fbshipit-source-id: f62dc095ce57904057a97c83c958de5227a112a8

Differential Revision: D9499697

fbshipit-source-id: b04e9e0d1bf4abf1b5ff497cefbc26da0176eaa2

Summary: In some cases, it may be necessary to unicode-escape regular ASCII characters in JSON serialization (example: for JSON sent to browsers that may be interpreted as HTML, "<" should be escaped). Allow additional escape characters to be specified via a bitmap in the serializer options.

Reviewed By: yfeldblum, luciang

Differential Revision: D8980189

fbshipit-source-id: 000c5279ab0f37a3ee4b2eb38f20afa49dcc5a27

Summary:
Problem:
- There are several tests enabled which rely on using
  shared_ptr_internals found in
  folly/concurrency/detail/AtomicSharedPtr-detail.h and
  the implementation only works for libstdc++ and not with other vendors
  such as libc++ and libcpp.
- This results in a hard error when compiling with Clang with libc++.

Solution:
- Add a CMake configure check to detect whether one is using libstdc++.
  FOLLY_USE_LIBSTDCPP macro is set to 1 if using libstdc++, 0 otherwise.
- Use FOLLY_USE_LIBSTDCPP to conditionally run the tests relying on
  shared_ptr_internals only when using libstdc++.

Note:
- A longer-term solution would be to implement the similar
  shared_ptr_internals with the libc++ types and provide a fallback
  locking approach for libcpp (MSVC standard library implementation).

Pull Request resolved: https://github.com/facebook/folly/pull/900

Reviewed By: djwatson

Differential Revision: D9312236

Pulled By: yfeldblum

fbshipit-source-id: 657eddc1e530b00bd5f5b10e7155bc3b6aac3726

Summary: [Folly] Cut unnecessary uses of `Super::` in `F14Policy.h`.

Reviewed By: shixiao

Differential Revision: D9478746

fbshipit-source-id: ea5b57a66e265ea459a66ff3756a2a54326e73f2

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).thenMulti(...)` instead of `f.thenMulti(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9437767

fbshipit-source-id: f40d0660a50ccfec1040e42c8028efde956a4b48

Summary:
[Folly] Work around member alias bugs in some compilers in `F14Policy.h`.

MSVC appears to have a hard time with some cases of `using typename Base::MemberAlias;` - replace with `using MemberAlias = typename Base::MemberAlias;`.

Reviewed By: shixiao

Differential Revision: D9478688

fbshipit-source-id: 5cbf63839cc2b3a085ed633cc4e5703d61990033

Summary:
I find myself wanting something like this pretty often, so I tried my hand at adding it myself.

The `groupByAdjacent` operator creates groups bounded wherever the selector changes. It's especially useful for processing sources that've already been sorted on the selector, such as from a database query.

Given the following source sequence with keys `A` and `B`:

```
[A1, A2, A3, B1, B2, B3, A4, A5, B4, B5]
```

a regular `groupBy` would return something like:

```
[A:[A1, A2, A3, A4, A5], B:[B1, B2, B3, B4, B5]]
```

while this `groupByAdjacent` would return:

```
[A:[A1, A2, A3], B:[B1, B2, B3], A:[A4, A5], B:[B4, B5]]
```

Given a source where the items are presorted by selector, `groupByAdjacent` should behave identically to `groupBy`, except that `groupByAdjacent` supports infinite sources since it doesn't need to collect the entire source in memory before creating any output.

Reviewed By: yfeldblum

Differential Revision: D9475326

fbshipit-source-id: 1c8db3abadce5e68394e5fa38bf4bee0b413a03f

Summary:
It is where `std::logic_error` is defined.

Fixes https://github.com/facebook/folly/issues/913

Reviewed By: yfeldblum

Differential Revision: D9436370

fbshipit-source-id: a4425d7d29f0bd55ea536a49a8923f22944ecbd0

Summary:
`F14NodeMap` has proven to be a safe and more performant drop-in replacement
for `std::unordered_map`. With the ability to do heterogeneous lookup and
mutation, we no longer need `StringKeyedUnorderedMap`, whose main purpose was
to avoid unnecessary string copies during lookups and inserts.

Reviewed By: nbronson

Differential Revision: D9124737

fbshipit-source-id: 81d5be1df9096ac258a3dc1523a6a0f5d6b9e862

Summary: in the opensource spec I forgot to specify the github org as facebookincubator in D9337956 vs regular facebook, this caused travis builds for proxygen and anything that depends on fizz to fail

Reviewed By: knekritz

Differential Revision: D9482739

fbshipit-source-id: ba5a8f465c81ec1b9f037114ce1da3614a838699

Summary: ThreadCachedInts use after free fix

Reviewed By: djwatson

Differential Revision: D9445106

fbshipit-source-id: 989969e54178b5f908f6ca94cde4088ffb2da490

Summary:
`boost::scoped_ptr<T>` is obsolete so replace it with `std::unique_ptr<T[]>`.
This also fixes the modular build by eliminating problematic using directives.

Reviewed By: shixiao

Differential Revision: D9480193

fbshipit-source-id: 8eaa642fe16e91b8f8144f5a10f21729ed984257

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).semi()` instead of `f.semi()`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9478283

fbshipit-source-id: 7d2f54a8aaa9156b2b274aafc9695fd996f29641

Summary: Fix the broken folly/tests/.. build

Reviewed By: yfeldblum

Differential Revision: D9477364

fbshipit-source-id: 0b227ebb3eb7e062bff8883ba31b398672273c16

Summary: [Folly] Fix forwarding in `ParkingLot<T>::WaitNode` ctor.

Reviewed By: aary

Differential Revision: D9478603

fbshipit-source-id: 1da4c985bee7293356b1f5e1b43678282703b8ce

Summary:
Prior to this diff, the two `Future::within(Duration, Timekeeper* = nullptr)` overloads were the same typewise but they used different symbols:

Return-type differences:
* rvalue-qualified overload returned `Future<T>`
* lvalue-qualified overload returned `auto` (which resolved to `Future<T>`)

Parameter *name* differences:
* rvalue-qualified overload has unnamed formal-parameters (it is a declaration but not a definition).
* lvalue-qualified overload has named formal-parameters (it is both a declaration and a definition).

These seemingly innocuous differences caused gcc to choke: when the `this` object was a `Future<...>` object returned by value, gcc reported the following error: "error: call of overloaded ‘within(std::chrono::minutes)’ is ambiguous", specifically pointing to the two `Future::within(Duration, Timekeeper* = nullptr)` overloads.

Conversely clang had no problem with that callsite.

gcc stopped issuing the spurious error-message after this diff's changes, that is, after making the signatures of the two overloads identical in every respect except for the rvalue-qualification vs. lvalue-qualification.

Reviewed By: yfeldblum

Differential Revision: D9474736

fbshipit-source-id: 758001090e5487bd70c9853940807cbdeba8ac94

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).onTimeout(...)` instead of `f.onTimeout(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9441928

fbshipit-source-id: 28cb393588fa32becb44c89c6afd0ed482f5cf7e

Summary:
Prior to this diff, the two `Future::semi()` overloads were logically the same but used different symbols:
* rvalue-qualified overload returned `Future<T>`
* lvalue-qualified overload returned `auto` (which resolved to `Future<T>`)

This seemingly innocuous difference caused gcc to choke: when the `this` object was a `Future<...>` object returned by value, gcc reported the following error: "error: call of overloaded ‘semi()’ is ambiguous", specifically pointing to the two `Future::semi()` overloads.

Conversely clang had no problem with that callsite.

gcc stopped issuing the spurious error-message after this diff's changes, that is, after making the signatures of the two overloads identical in every respect except for the rvalue-qualification vs. lvalue-qualification.

Reviewed By: LeeHowes

Differential Revision: D9475854

fbshipit-source-id: 5fb20f6c57eaf6a5f9b7cb6cdb49782e40704953

Summary: This was causing type inference problems for default parameter continuations, and as the callable that thenValue takes must have a parameter it serves no purpose.

Reviewed By: yfeldblum

Differential Revision: D9441278

fbshipit-source-id: 8a6962772a58f51c93ef95abc06acb4939bc4a95

Summary: Add RcuBenchmark as an (RcuTest, Perf) replacement

Reviewed By: djwatson

Differential Revision: D9443217

fbshipit-source-id: c751b98e0dd38128a157cfdfad6b21b87dbfb41c

Summary:
Certain toolchains on iOS platforms don't apply EBO to F14 BasePolicy and
F14Table, which makes the size calculations incorrect.

This diff disables the test pending further investigation (T33121191).

Reviewed By: nbronson

Differential Revision: D9467473

fbshipit-source-id: 50435b3fcdeb81a6a892e280fdc919486f0ed107

Summary: Update cmake configurations + legocastle jobs in order to add fizz as a dependency to wangle

Reviewed By: reanimus

Differential Revision: D9337956

fbshipit-source-id: 40f25694c2b3fd8aa37d254bc63a664f4c8ee526

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).onError(...)` instead of `f.onError(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Codemod changes:

* expr.MMM(...) ==> std::move(expr).MMM(...)  // if expr is not already an xvalue
* expr->MMM(...) ==> std::move(*expr).MMM(...)

Note: operator precedence of that last step is safe - no need to parenthesize `expr`. Reason: `->` binds more tightly than unary `*`.

Reviewed By: LeeHowes

Differential Revision: D9445122

fbshipit-source-id: 1202bc2dd2e054b541458aa20829abe4c7f52b33

Summary: The message is useful once, but not for every time the header is included and the condition checked.

Reviewed By: shixiao

Differential Revision: D9457501

fbshipit-source-id: 35c2c2f0510e9be9b747ab7c760a7cc36ad500b4

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).semi()` instead of `f.semi()`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9442672

fbshipit-source-id: ea0e97915b8143e2f36e956be708dc36a735cca5

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).within(...)` instead of `f.within(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9442173

fbshipit-source-id: 910914fd9da80627b335419542b5bb358b21f680

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).onError(...)` instead of `f.onError(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9441271

fbshipit-source-id: c65614a5529bf50bb9a209e3941d20f3688f2a80

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).thenMulti(...)` instead of `f.thenMulti(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9437727

fbshipit-source-id: 7656aff65db69a5cb51b621b7d7b1b01ef0d3e12

Summary:
These conversions enable a few bits of folly to compile with
more stringent compiler warnings than the baseline.  One site actually
had a bug in an error path, the rest are just churn.

Reviewed By: sathyaphoenix

Differential Revision: D9398429

fbshipit-source-id: d9836eabe93be7aeebd59581df8fb6d278c74112

Summary: MSVC is having issues with this, so explicitly refer to `AllocTraits` via `Super`.

Reviewed By: wez

Differential Revision: D9387914

fbshipit-source-id: 1751b029d678151cbce90cdffdce586498cdf756

Summary:
This is part of "the great r-valuification of folly::Future":
* This is something we should do for safety in general.
* Several of folly::Future's methods are lvalue-qualified even though they act as though they are rvalue-qualified, that is, they provide a postcondition that says, in effect, callers should act as though the method invalidated its `this` object (regardless of whether that invalidation was actual or logical).
* This violates the C++ principle to "Express ideas directly in code" (see Core Guidelines), and generally makes it more confusing for callers as well as hiding the actual semantics from tools (linters, compilers, etc.).
* This dichotomy and confusion has manifested itself by some failures around D7840699 since lvalue-qualification hides that operation's move-out semantics - leads to some use of future operations that are really not correct, but are not obviously incorrect.
* The goal of rvalueification is to make sure methods that are logically rvalue-qualified are actually rvalue-qualified, which forces callsites to acknowledge that rvalueification, e.g., `std::move(f).thenMulti(...)` instead of `f.thenMulti(...)`. This syntactic change in the callsites forces callers to acknowledge the method's rvalue semantics.

Reviewed By: LeeHowes

Differential Revision: D9415878

fbshipit-source-id: 3dd78941c60ee41f4284b5842e57c1c25005d15a

Summary:
Introduce a RequestToken class to RequestContext.  Map indicies are now uint32_t.

New interfaces are exposed using RequestToken, previous std::string interface forwards
to new interface.  This is a regression for the previous std::string interface since it
must do two hash lookups now, however, the new interface is faster.

Reviewed By: A5he

Differential Revision: D9197415

fbshipit-source-id: ffb8be51c609233fecfdff205a3ea4d4bb68de4b

Summary:
Non-functional comment-only changes.

Goal: Adjust Promise's code-docs so they are consistent with Future and SemiFuture, e.g., change "valid() must be true" to "`valid() == true`"

Reviewed By: LeeHowes

Differential Revision: D9415137

fbshipit-source-id: dbb8df00919779b339e5b08337eba0df1a210ac2

Summary:
This is a non-functional comment-only change.

Reason: doc-comment tools interpret embedded code-blocks via 2-space-indentation instead of "```"

Reviewed By: LeeHowes

Differential Revision: D9414916

fbshipit-source-id: d7dd29b0d67f1a361a99fba5b95aa3a6e095041c

Summary:
Support 4-byte UTF-8 strings.

https://en.wikipedia.org/wiki/UTF-8
| Number of bytes | Bits for code point | First code point | Last code point |   Byte 1 |   Byte 2 |   Byte 3 |   Byte 4
|               1 |                   7 |           U+0000 |          U+007F | 0xxxxxxx
|               2 |                  11 |           U+0080 |          U+07FF | 110xxxxx | 10xxxxxx
|               3 |                  16 |           U+0800 |          U+FFFF | 1110xxxx | 10xxxxxx | 10xxxxxx
|               4 |                  21 |          U+10000 |        U+10FFFF | 11110xxx | 10xxxxxx | 10xxxxxx | 10xxxxxx

`utf8ToCodePoint` now correctly returns the code point for 4-byte UTF-8 strings.

The JSON standard (http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) says:

> Any code point may be represented as a hexadecimal escape sequence. The meaning of such a hexadecimal
number is determined by ISO/IEC 10646. If the code point is in the Basic Multilingual Plane (U+0000 through
U+FFFF), then it may be represented as a six-character sequence: a reverse solidus, followed by the
lowercase letter u, followed by four hexadecimal digits that encode the code point. Hexadecimal digits can be

This was the behavior implemented for 2-3-byte UTF-8 strings which all fit in the U+0000 through U+FFFF range (see above diagram).

> To escape a code point that is not in the Basic Multilingual Plane, the character may be represented as a
twelve-character sequence, encoding the UTF-16 surrogate pair corresponding to the code point. So for
example, a string containing only the G clef character (U+1D11E) may be represented as "\uD834\uDD1E".
However, whether a processor of JSON texts interprets such a surrogate pair as a single code point or as an
explicit surrogate pair is a semantic decision that is determined by the specific processor.

When `encode_non_ascii == true` we now also support encoding 4-byte UTF-8 strings as 2 UTF-16 surrogate pairs.

Reviewed By: ot

Differential Revision: D9357479

fbshipit-source-id: 5c47bee4e71d5888b8264d8d3524d2084769adb0

Summary:
It may be surprising to some users of AsyncSocket that buffered
writes always result in a success/error callback, even on shutdown.
This commit explicitly documents this part of the API and adds
some suggestions on how to handle it.

Reviewed By: simpkins

Differential Revision: D9405722

fbshipit-source-id: 07c2d1caa2c7c023592f734f7ced1ebbcbf4c628