Worker Pool

A Dart/Flutter package for managing a pool of isolates to execute tasks concurrently, with support for resource management, constant sharing, and proper cleanup.

中文版 README

Features

• Isolate Pool Management: Efficiently manages a pool of Dart isolates for concurrent task execution
• Resource Management: Initialize and clean up resources in isolates with custom finalizers
• Constant Sharing: Share constants between the main thread and isolates
• Task Queue: Automatically queues tasks when all isolates are busy
• Timeout Handling: Configurable timeouts for task execution
• Health Monitoring: Automatic worker restart based on task count or inactivity
• Function Registration: Register functions that can be executed in isolates
• Statistics: Get pool statistics for monitoring performance

Getting Started

Prerequisites

• Dart SDK ^3.8.1
• Flutter >=1.17.0 (for Flutter projects)

Installation

Add worker_pool to your pubspec.yaml:

dependencies:
  worker_pool:
    path: /path/to/worker_pool

Or if published to pub.flutter-io.cn:

dependencies:
  worker_pool: last_version

Usage

See the full example in the example/ directory.

1. Define a function

Create a top-level or static function to be executed in an isolate.

// A simple function to run in an isolate
Future<int> fibonacci(int n) async {
  if (n <= 1) return n;
  return await fibonacci(n - 1) + await fibonacci(n - 2);
}

2. Initialize the Worker Pool

Create a WorkerPoolConfig and register your function. Then initialize the pool.

import 'package:worker_pool/worker_pool.dart';

void main() async {
  // Create a configuration and register the function
  final config = WorkerPoolConfig(
    predefinedFunctions: {
      'fib': fibonacci,
    },
  );

  // Initialize the worker pool
  final pool = await WorkerPool.initialize(config);
}

3. Submit a Task

Use the submit method with the registered function name to execute the task.

try {
  final result = await pool.submit<int, int>('fib', 40);
  print('Result: $result');
} catch (e) {
  print('An error occurred: $e');
}

4. Dispose the Pool

Clean up the resources when you are done.

await pool.dispose();

Configuration Options

The WorkerPoolConfig class provides several configuration options:

Option	Description	Default
poolSize	Number of isolates to maintain in the pool.	Platform.numberOfProcessors
resourceInitializers	List of functions to initialize resources in isolates	[]
resourceFinalizers	Map of finalizer functions for resource cleanup	{}
constantProviders	List of functions to provide constants to isolates	[]
healthCheckInterval	Interval for health checks	5 minutes
isolateTimeout	Timeout for task execution	30 seconds
maxTasksPerIsolate	Maximum tasks per isolate before restart	1000
predefinedFunctions	Map of functions that can be executed in isolates	{}

Additional Information

Error Handling

The worker pool handles errors gracefully:

• Task execution errors are propagated to the caller
• Isolate crashes are automatically recovered by restarting the worker
• Timeouts are handled with TimeoutException

Performance Considerations

• Tasks should be CPU-intensive to benefit from isolate-based concurrency
• I/O operations should use async/await and may not benefit from isolates
• Consider the overhead of data serialization when passing arguments to isolates

Testing

The project includes comprehensive unit tests to ensure functionality and reliability:

flutter test

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

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