Squadron

<table><tr> <td valign="top"> <img src="https://raw.githubusercontent.com/d-markey/squadron/main/squadron_logo.svg" width="120" alt="Squadron logo" /> </td> <td>

Squadron - Multithreading and worker pools in Dart

Offload CPU-bound and long running tasks and give your apps some air!
Works everywhere: Desktop, Server, Mobile, and Browser (JS & WASM).

Quick Start • Why Squadron? • Wiki Documentation • Samples

</td> </tr></table>

🚀 Why Squadron?

Dart is single-threaded by nature. While Isolate.run() is great for one-off tasks, it creates overhead for frequent operations. Squadron provides:

• 🔄 Persistent Worker Pools: Keep workers alive and ready to process tasks instantly.
• 🌐 Seamless Web Support: Uniform API for Isolates (Native) and Web Workers (JS/Wasm).
• 🛡️ Type Safety: Automatic code generation ensures your thread boundaries are type-safe.
• 🚫 Cancellation: Gracefully cancel long-running tasks.
• 📡 Streaming: Native support for Stream return types from workers.

---

🏗️ Architecture

sequenceDiagram
    autonumber
    
    participant App as Main App (UI)
    box rgb(40, 100, 200, 0.1) Squadron / Generated Code
        participant Pool as HelloWorldWorkerPool/Worker
    end
    box rgb(0, 150, 0, 0.1) Background Thread
        participant Service as User Service
    end
    
    App->>Pool: worker.hello('Squadron')
    Pool->>Service: Assign Task (Marshaled)
    activate Service
    Note over Service: Executing on background Isolate/Web Worker
    Service-->>Pool: Return Result (Unmarshaled)
    deactivate Service
    Pool-->>App: Future<String> Result

---

📖 Table of Contents

• Getting Started
• Implementing a Service
• Generating Workers
• Running your Worker
• Web Support (JS & Wasm)
• Advanced Concepts
  • Data Transfer & Marshaling
  • Exception Handling
  • Logging
• Community & Credits

---

<a name="getting_started"></a>1. Getting Started

Add Squadron to your dependencies and squadron_builder to your dev dependencies:

dependencies:
  squadron: ^7.4.0

dev_dependencies:
  build_runner:
  squadron_builder: ^9.0.0

Run dart pub get to install.

<a name="implement"></a>2. Implementing a Service

Create a class with the logic you want to run in the background. Use @SquadronService and @SquadronMethod annotations.

// file: hello_world.dart
import 'dart:async';
import 'package:squadron/squadron.dart';

import 'hello_world.activator.g.dart';
part 'hello_world.worker.g.dart';

@SquadronService(baseUrl: '~/workers', targetPlatform: TargetPlatform.all)
base class HelloWorld {
  @SquadronMethod()
  FutureOr<String> hello([String? name]) {
    name = name?.trim() ?? 'World';
    return 'Hello, $name!';
  }
}

<a name="build"></a>3. Generating Workers

Squadron uses code generation to handle the boilerplate of thread communication. Run the following command:

dart run build_runner build

This creates HelloWorldWorker and HelloWorldWorkerPool. These classes implement the same interface as your service but proxy calls to background threads.

<a name="run"></a>4. Running your Worker

In your application, instantiate the worker and use it like a normal service.

[!IMPORTANT]
Always stop your workers. Failure to call worker.stop() will keep your program running indefinitely.

import 'hello_world.dart';

void main() async {
  final worker = HelloWorldWorker();
  try {
    // Squadron starts the worker automatically on the first call
    final message = await worker.hello('Squadron');
    print(message);
  } finally {
    worker.stop(); // Clean up the background thread
  }
}

---

<a name="web"></a>🌍 Web Support (JS & Wasm)

Squadron is designed for a "write once, run anywhere" experience. When targeting the web, you must compile your worker entry points:

# Compile to JavaScript
dart compile js ".\src\lib\hello_world.web.g.dart" -o "..\web\workers\hello_world.web.g.dart.js"
# Compile to Web Assembly
dart compile wasm ".\src\lib\hello_world.web.g.dart" -o "..\web\workers\hello_world.web.g.dart.wasm"

Squadron will automatically detect the runtime environment and choose the correct implementation.

---

<a name="advanced"></a>🛠️ Advanced Concepts

<a name="marshaling"></a>Data Transfer & Marshaling

Because workers run in separate memory spaces, data must be serialized ("marshaled") to cross thread boundaries. While base types (Strings, Numbers, Lists, Maps) are handled automatically, custom objects require a SquadronMarshaler.

📖 Learn more: Data Transfer and Types & Marshaling Wiki

<a name="exceptions"></a>Exception Handling

Exceptions thrown in a worker are caught, serialized, and re-thrown on the caller's side, preserving the stack trace and error information where possible.

📖 Learn more: Exception Management Wiki

<a name="logging"></a>Logging

Debugging background workers can be tricky. Squadron provides mechanisms to forward log messages from workers back to the main thread's debugger or console.

📖 Learn more: Observability and Logging Wiki

---

<a name="thanks"></a>Special Thanks

• Saad Ardati for feedback on Flutter integration.
• Martin Fink for major improvements to Stream support.
• Klemen Tusar for the Chopper JSON decoder sample.
• James O'Leary for sponsorship and contributions.

---

View the Full Wiki • API Reference