[shared_preferences] Add README discussion of reload (#3508)
[shared_preferences] Add README discussion of reload
diff --git a/packages/shared_preferences/shared_preferences/CHANGELOG.md b/packages/shared_preferences/shared_preferences/CHANGELOG.md
index cae65a8..db8eb38 100644
--- a/packages/shared_preferences/shared_preferences/CHANGELOG.md
+++ b/packages/shared_preferences/shared_preferences/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.0.20
+
+* Adds README discussion of `reload()`.
+
## 2.0.19
* Updates README to use code excerpts.
diff --git a/packages/shared_preferences/shared_preferences/README.md b/packages/shared_preferences/shared_preferences/README.md
index 3796600..67770ec 100644
--- a/packages/shared_preferences/shared_preferences/README.md
+++ b/packages/shared_preferences/shared_preferences/README.md
@@ -61,6 +61,30 @@
await prefs.remove('counter');
```
+### Multiple instances
+
+In order to make preference lookup via the `get*` methods synchronous,
+`shared_preferences` uses a cache on the Dart side, which is normally only
+updated by the `set*` methods. Usually this is an implementation detail that
+does not affect callers, but it can cause issues in a few cases:
+- If you are using `shared_preferences` from multiple isolates, since each
+ isolate has its own `SharedPreferences` singleton and cache.
+- If you are using `shared_preferences` in multiple engine instances (including
+ those created by plugins that create background contexts on mobile devices,
+ such as `firebase_messaging`).
+- If you are modifying the underlying system preference store through something
+ other than the `shared_preferences` plugin, such as native code.
+
+If you need to read a preference value that may have been changed by anything
+other than the `SharedPreferences` instance you are reading it from, you should
+call `reload()` on the instance before reading from it to update its cache with
+any external changes.
+
+If this is problematic for your use case, you can thumbs up
+[this issue](https://github.com/flutter/flutter/issues/123078) to express
+interest in APIs that provide direct (asynchronous) access to the underlying
+preference store, and/or subscribe to it for updates.
+
### Testing
In tests, you can replace the standard `SharedPreferences` implementation with
diff --git a/packages/shared_preferences/shared_preferences/pubspec.yaml b/packages/shared_preferences/shared_preferences/pubspec.yaml
index 756b88a..f085c2a 100644
--- a/packages/shared_preferences/shared_preferences/pubspec.yaml
+++ b/packages/shared_preferences/shared_preferences/pubspec.yaml
@@ -3,7 +3,7 @@
Wraps NSUserDefaults on iOS and SharedPreferences on Android.
repository: https://github.com/flutter/packages/tree/main/packages/shared_preferences/shared_preferences
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+shared_preferences%22
-version: 2.0.19
+version: 2.0.20
environment:
sdk: ">=2.17.0 <3.0.0"
