From ff32420e576bb01b702b68332848da100e68fad4 Mon Sep 17 00:00:00 2001 From: Andrew Clark Date: Tue, 27 Mar 2018 16:50:12 -0700 Subject: [PATCH] Caveat about async in create-subscription README (#12469) * Caveat about async in create-subscription README * Address Sophie's comments * Dan's nits --- packages/create-subscription/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/create-subscription/README.md b/packages/create-subscription/README.md index 33089f4cb5..26308fe1e7 100644 --- a/packages/create-subscription/README.md +++ b/packages/create-subscription/README.md @@ -11,6 +11,16 @@ Other cases have **better long-term solutions**: * I/O subscriptions (e.g. notifications) that update infrequently should use [`simple-cache-provider`](https://github.com/facebook/react/blob/master/packages/simple-cache-provider/README.md) instead. * Complex libraries like Relay/Apollo should manage subscriptions manually with the same techniques which this library uses under the hood (as referenced [here](https://gist.github.com/bvaughn/d569177d70b50b58bff69c3c4a5353f3)) in a way that is most optimized for their library usage. +## Limitations in async mode + +The main motivation for `create-subscription` is to provide a way for library authors to ensure compatibility with React's upcoming asynchronous rendering mode. `create-subscription` guarantees correctness in async mode, accounting for the subtle bugs and edge cases that a library author might otherwise miss. + +However, it achieves correctness by sometimes de-opting to synchronous mode, obviating the benefits of async rendering. This is an inherent limitation of storing state outside of React's managed state queue and rendering in response to a change event. + +The effect of de-opting to sync mode is that the main thread may periodically be blocked (in the case of CPU-bound work), and placeholders may appear earlier than desired (in the case of IO-bound work). + +For **full compatibility** with asynchronous rendering, including both **time-slicing** and **React Suspense**, the suggested longer term solution is to move to one of the patterns described in the previous section. + ## What types of subscriptions can this support? This abstraction can handle a variety of subscription types, including: