Skip to content

docs: Document the root-isolate requirement for Amplify (#5302) #7273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cadivus wants to merge 1 commit into
base: feat/isolate-guard-auth
Choose a base branch
from
Draft

docs: Document the root-isolate requirement for Amplify (#5302) #7273

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions packages/amplify/amplify_flutter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,32 @@ The top level module for Amplify Flutter.
| Storage | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Notifications | ✅ | ✅ | 🔴 | 🔴 | 🔴 | 🔴 |

## Isolates

Amplify must be configured and used on the **root isolate** — an app's main
isolate, or the Dart entry point of a headless `FlutterEngine`.

Dart state is isolate-local, so an isolate started with `Isolate.spawn` can
construct its own Amplify instance. Two limits make it unsafe to use one:

- **Platform channels only work in one direction.** After
`BackgroundIsolateBinaryMessenger.ensureInitialized`, a secondary isolate can
call into the host, but it can never receive messages back — Flutter delivers
host messages to the root isolate only. Every callback-driven API is therefore
root-isolate-only, permanently: DataStore `observe` and Hub events, push
notification handlers, and Hosted UI redirects.
- **Persistent state is shared and not synchronized.** The native SDKs and the
credential store are one per process, and Amplify does not serialize access to
them across isolates. Two isolates refreshing tokens can interleave their
writes and leave an inconsistent credential set.

`AmplifyDataStore.configure` and `AmplifyAuthCognito.addPlugin` fail fast with an
explanatory error when called from a secondary isolate, rather than failing later
in a way that is hard to attribute.

Progress on broader isolate support is tracked in
[#5302](https://github.com/aws-amplify/amplify-flutter/issues/5302).

## Getting Started

### Visit our [Web Site](https://docs.amplify.aws/) to learn more about AWS Amplify.
Expand Down
Loading