pl_isolate #

https://github.com/user-attachments/assets/31985cfa-f3b4-440e-8459-fdc4f8dc7fe1

A powerful Flutter plugin that simplifies isolate communication and management. Run heavy computations in separate isolates without blocking the UI thread.

Features #

• 🚀 Easy Isolate Management: Simple API to create and manage isolates
• 🔄 Automatic Disposal: Auto-dispose isolates after inactivity
• 🎯 Type-Safe Operations: Define operations with clear interfaces
• 🔐 Thread-Safe: Built-in synchronization for concurrent operations
• 📊 Multiple Isolates: Each operation can have its own isolate helper
• 🎨 UI Isolate Support: Support for both Dart isolates and UI isolates
• ⚡ Performance: Run CPU-intensive tasks without blocking the main thread
• 📦 Transferable Data for Large Payloads: Efficient support for sending/receiving large data between isolates using Dart's transferable objects

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  pl_isolate: ^1.0.0

Then run:

flutter pub get

Quick Start #

1. Define Your Operation #

Create an operation class that implements IsolateOperation:

import 'package:pl_isolate/pl_isolate.dart';

class MyCalculationOperation implements IsolateOperation {
  @override
  String get tag => 'calculation';

  @override
  Future<dynamic> run(dynamic args) async {
    // Your heavy computation here
    if (args is int) {
      int result = 0;
      for (var i = 0; i < args; i++) {
        result += i;
      }
      return result;
    }
    throw Exception('Invalid arguments');
  }
}

2. Create Your Isolate Helper #

Extend IsolateHelper to create your helper:

class MyIsolateHelper extends IsolateHelper<int> {
  @override
  bool get isDartIsolate => false; // Use false for regular isolates, true for UI isolates

  @override
  String get name => 'MyIsolateHelper'; // Unique name for this helper

  @override
  bool get isAutoDispose => true; // Auto-dispose after inactivity

  @override
  Stream get messages => throw UnimplementedError(); // Required but not used
}

3. Use the Helper #

class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  final MyIsolateHelper _helper = MyIsolateHelper();

  Future<void> _runCalculation() async {
    try {
      final result = await _helper.runIsolate(
        1000000, // Arguments
        MyCalculationOperation(), // Your operation
      );
      print('Result: $result');
    } catch (e) {
      print('Error: $e');
    }
  }

  @override
  void dispose() {
    _helper.dispose(); // Don't forget to dispose
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _runCalculation,
      child: Text('Run Calculation'),
    );
  }
}

Managing Multiple Tasks with IsolateManager #

When you need to queue different helpers and execute them with concurrency limits, use IsolateManager.

1. Initialize the Manager #

void main() {
  // Allow 2 concurrent tasks and up to 10 queued jobs.
  IsolateManager.init(2, 10);
  runApp(const MyApp());
}

2. Add Tasks to the Queue #

void scheduleTasks() {
  final manager = IsolateManager.instance;

  manager.addIsolateHelper(
    MyIsolateHelper(),
    MyCalculationOperation(),
    1000000,
  );

  manager.addIsolateHelper(
    OtherHelper(),
    OtherOperation(),
    {'duration': 2000},
  );
}

Each call enqueues the helper/operation pair along with its arguments. You can enqueue as many as maxSizeOfQueue.

3. Listen for Results (Optional) #

@override
void initState() {
  super.initState();
  IsolateManager.instance.listenIsolateResult((IsolateResult result) {
    if (result.errorMessage != null) {
      debugPrint('Task ${result.name} failed: ${result.errorMessage}');
    } else {
      debugPrint('Task ${result.name} completed: ${result.result}');
    }
  });
}

4. Run the Batch #

Future<void> runQueue() async {
  await IsolateManager.instance.runAllInBatches();
}

The manager executes the queue in batches, honoring the maxConcurrentTasks limit. Results are pushed through the listener as each task finishes.

5. Clean Up #

Call disposeAll() when you are done to release helpers left in the queue or running list.

@override
void dispose() {
  IsolateManager.instance.disposeAll();
  super.dispose();
}

Complete Example #

Here's a complete example showing multiple operations:

import 'package:flutter/material.dart';
import 'package:pl_isolate/pl_isolate.dart';

// Define operations
class CountOperation implements IsolateOperation {
  @override
  String get tag => 'count';

  @override
  Future<dynamic> run(dynamic args) async {
    if (args is int) {
      int count = 0;
      for (var i = 0; i < args; i++) {
        count++;
      }
      return count;
    }
    return 0;
  }
}

class SumOperation implements IsolateOperation {
  @override
  String get tag => 'sum';

  @override
  Future<dynamic> run(dynamic args) async {
    if (args is List) {
      return args.fold<int>(0, (sum, item) => sum + (item as int));
    }
    return 0;
  }
}

// Create helpers
class CountHelper extends IsolateHelper<int> {
  @override
  bool get isDartIsolate => false;
  @override
  String get name => 'CountHelper';
  @override
  bool get isAutoDispose => true;
  @override
  Stream get messages => throw UnimplementedError();
}

class SumHelper extends IsolateHelper<int> {
  @override
  bool get isDartIsolate => false;
  @override
  String get name => 'SumHelper';
  @override
  bool get isAutoDispose => true;
  @override
  Stream get messages => throw UnimplementedError();
}

// Use in your app
class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final CountHelper _countHelper = CountHelper();
  final SumHelper _sumHelper = SumHelper();

  String _countResult = 'No result';
  String _sumResult = 'No result';
  bool _isLoading = false;

  Future<void> _runCount() async {
    setState(() => _isLoading = true);
    try {
      final result = await _countHelper.runIsolate(
        10000000,
        CountOperation(),
      );
      setState(() {
        _countResult = 'Count: $result';
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _countResult = 'Error: $e';
        _isLoading = false;
      });
    }
  }

  Future<void> _runSum() async {
    setState(() => _isLoading = true);
    try {
      final result = await _sumHelper.runIsolate(
        List.generate(1000000, (i) => i),
        SumOperation(),
      );
      setState(() {
        _sumResult = 'Sum: $result';
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _sumResult = 'Error: $e';
        _isLoading = false;
      });
    }
  }

  @override
  void dispose() {
    _countHelper.dispose();
    _sumHelper.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Isolate Helper Example')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              if (_isLoading) CircularProgressIndicator(),
              Text(_countResult),
              ElevatedButton(
                onPressed: _isLoading ? null : _runCount,
                child: Text('Run Count'),
              ),
              SizedBox(height: 20),
              Text(_sumResult),
              ElevatedButton(
                onPressed: _isLoading ? null : _runSum,
                child: Text('Run Sum'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

API Reference #

IsolateHelper #

Abstract class for managing isolates.

Properties

• isDartIsolate (bool): true for Dart UI isolates, false for regular isolates
• name (String): Unique name for the helper
• isAutoDispose (bool): Whether to auto-dispose after inactivity
• isIsolateSpawn (bool): Whether the isolate is currently spawned
• autoDisposeInterval (Duration): Time before auto-dispose (default: 10 seconds)

Methods

• Future<T> runIsolate(dynamic args, IsolateOperation operation): Run an operation in the isolate
• Future<void> dispose(): Manually dispose the isolate

IsolateOperation #

Abstract class for defining operations.

Properties

• tag (String): Unique tag for the operation

Methods

• Future<dynamic> run(dynamic args): Execute the operation

Dart Isolate vs UI Isolate #

Regular Isolate (isDartIsolate: false) #

• Requires RootIsolateToken for platform channel access
• Use for computations that don't need UI access
• Better performance for CPU-intensive tasks

class MyHelper extends IsolateHelper<dynamic> {
  @override
  bool get isDartIsolate => false;
  // ... other properties
}

UI Isolate (isDartIsolate: true) #

• Can access UI-related APIs
• Use when you need platform channels or UI access
• Requires Flutter bindings to be initialized

class MyHelper extends IsolateHelper<dynamic> {
  @override
  bool get isDartIsolate => true;
  // ... other properties
}

Best Practices #

1. One Helper per Operation Type #

Each helper should manage one type of operation:

// Good: Separate helpers for different operations
class ImageProcessingHelper extends IsolateHelper<Uint8List> { ... }
class DataAnalysisHelper extends IsolateHelper<AnalysisResult> { ... }

// Avoid: One helper for multiple unrelated operations
class AllOperationsHelper extends IsolateHelper<dynamic> { ... }

2. Always Dispose Helpers #

Make sure to dispose helpers when they're no longer needed:

@override
void dispose() {
  _helper.dispose();
  super.dispose();
}

3. Handle Errors Properly #

Always wrap isolate operations in try-catch:

try {
  final result = await _helper.runIsolate(args, operation);
  // Handle success
} catch (e) {
  // Handle error
}

4. Use Auto-Dispose for Temporary Operations #

Enable auto-dispose for operations that are run infrequently:

@override
bool get isAutoDispose => true;

5. Pass Serializable Data #

Only pass data that can be serialized between isolates:

// Good: Primitive types, lists, maps
final result = await helper.runIsolate(42, operation);
final result = await helper.runIsolate([1, 2, 3], operation);
final result = await helper.runIsolate({'key': 'value'}, operation);

// Avoid: Complex objects, closures, functions
// These cannot be serialized between isolates

Advanced Usage #

Custom Auto-Dispose Interval #

Override autoDisposeInterval to customize the disposal time:

class MyHelper extends IsolateHelper<dynamic> {
  @override
  Duration get autoDisposeInterval => const Duration(seconds: 30);
  // ... other properties
}

Running Multiple Operations Concurrently #

Each helper can run operations independently:

// Run multiple operations at the same time
final result1 = _helper1.runIsolate(args1, operation1);
final result2 = _helper2.runIsolate(args2, operation2);
final result3 = _helper3.runIsolate(args3, operation3);

// Wait for all to complete
final results = await Future.wait([result1, result2, result3]);

Checking Isolate Status #

Monitor isolate state:

if (_helper.isIsolateSpawn) {
  print('Isolate is active');
} else {
  print('Isolate is inactive');
}

Troubleshooting #

Error: "Root isolate token is not set" #

Solution: If using isDartIsolate: false, make sure you're running in a Flutter app context. For UI isolates, use isDartIsolate: true.

Isolate Not Disposing #

Solution: Check if isAutoDispose is set to true and ensure no active operations are running.

Serialization Errors #

Solution: Ensure all data passed to runIsolate is serializable. Avoid passing complex objects, closures, or functions.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support #

For issues and feature requests, please use the GitHub Issues page.

Made with ❤️ by the NexPlugs team