📨 Cross Isolate Messenger
Cross Isolate Messenger is a lightweight Dart utility for reliable message passing and durability across Flutter isolates.
It ensures that messages are not lost during app lifecycle events by persisting them using SharedPreferences, and allows seamless replay and garbage collection.
✨ Features
- 📨 Reliable queue: Ensures messages sent from background isolates reach the UI.
- 🔁 Replay & persistence: Messages are stored and replayed until acknowledged.
- 🧼 Garbage collection: Acknowledged messages are purged automatically.
- 🔀 Stream-based: UI receives messages via
Stream<T>. - 🔗 IsolateNameServer: Automatically manages isolate communication.
🧩 Requirements
✅ Only for native platforms (Android, iOS, macOS) – Uses
SharedPreferences.
🚀 Usage
Define your message
class MyMessage {
final String id;
final String payload;
MyMessage(this.id, this.payload);
Map<String, dynamic> toJson() => {'id': id, 'payload': payload};
static MyMessage fromJson(Map<String, dynamic> json) =>
MyMessage(json['id'], json['payload']);
}
UI Isolate (Main isolate)
final queue = await PersistentQueue.getInstance<MyMessage>(
MyMessage.fromJson,
(msg) => msg.toJson(),
);
queue.bindUIIsolate();
queue.stream.listen((msg) async {
print("Received: \${msg.payload}");
await queue.ack(msg.id);
});
Background Isolate
final queue = await PersistentQueue.getInstance<MyMessage>(
MyMessage.fromJson,
(msg) => msg.toJson(),
);
await queue.send(MyMessage('msg-id-001', 'Hello from background isolate!'));
🧼 Clean Up
await queue.clearAll();
📦 Full Example
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final queue = await PersistentQueue.getInstance<MyMessage>(
MyMessage.fromJson,
(msg) => msg.toJson(),
);
queue.bindUIIsolate();
queue.stream.listen((msg) async {
print("UI Isolate received: \${msg.payload}");
await queue.ack(msg.id);
});
Isolate.spawn(runBackgroundIsolate, null);
runApp(const MaterialApp(home: Scaffold(body: Center(child: Text('PersistentQueue Example')))));
}
void runBackgroundIsolate(_) async {
final queue = await PersistentQueue.getInstance<MyMessage>(
MyMessage.fromJson,
(msg) => msg.toJson(),
);
await queue.send(MyMessage('msg-id-\${DateTime.now().millisecondsSinceEpoch}', 'Hello from background isolate!'));
}
📚 Related
📄 License
MIT
👷 TODO