📨 Cross Isolate Messenger

januscaler

pub package

All Contributors

Cross Isolate Messenger is a lightweight Dart utility for message passing and persistence across multiple Dart isolates in Flutter applications.

It uses SharedPreferences under the hood for durability, making it ideal for native platforms (Android, iOS, macOS) where isolates might need to resume processing messages after being restarted or delayed.

✨ Features

  • 🔄 Message persistence: Messages are stored in SharedPreferences until acknowledged.
  • 🚦 Isolate communication: Broadcast messages across Dart isolates using named channels.
  • 🧠 LRU cache-based deduplication: Prevents duplicate processing across restarts or replay.
  • 🧱 Generic and extensible: Supports custom classes via decoders and multiple message streams via unique portNames.

🧩 Requirements

✅ Native platforms only – This package relies on SharedPreferences, so it will not function on web or unsupported platforms like Windows or Linux (without SharedPreferences support).

🛠 Usage

1. Create an instance (per channel)

final queue = CrossIsolateQueue<Map<String, dynamic>>.getInstance('chat_channel');
await queue.initialize();

queue.stream.listen((msg) {
  print('Received message: $msg');
});

2. Send a message from another isolate

await CrossIsolateQueue.send('chat_channel', {
  'id': 'message-001',
  'content': 'Hello from another isolate!',
});

3. Acknowledge a message

await queue.ack('message-001');

🔁 Custom Message Types

Define a class and a decoder:

class MyMessage {
  final String id;
  final String content;

  MyMessage(this.id, this.content);

  factory MyMessage.fromJson(Map<String, dynamic> json) =>
      MyMessage(json['id'], json['content']);
}

Use the decoder when creating the queue:

final customQueue = CrossIsolateQueue<MyMessage>.getInstance(
  'custom_channel',
  decoder: (json) => MyMessage.fromJson(json),
);
await customQueue.initialize();

🧼 Clean Up

await queue.dispose();

⚠ Limitations

  • ❌ Not supported on web or desktop platforms without SharedPreferences.

📚 Related

📄 License

MIT

👷 TODO

  • Add fallback for unsupported platforms
  • Add testing harness for isolate message passing

Libraries

cross_isolate_messenger