Squadron Marshaling

Squadron Custom Class Marshaling Guide

In Squadron, passing base types (int, double, String, bool, null, nullable variants, List, Map) between the main thread and worker threads is handled automatically. However, passing custom classes requires serialization/deserialization because thread boundaries (isolates on Native, Web Workers on Web) do not share memory.

Note on Spelling: While British English uses marshalling (two 'l's), American English uses marshaling (one 'l'). Squadron follows the American spelling and uses SquadronMarshaler (one 'l') in its class names.

1. Cross-Platform Constraints & Serialization Approaches

• Native (VM / Isolates): On the VM, marshaling is generally avoidable. Dart's Isolate send ports handle many custom object graphs natively via underlying VM serialization/copying.
• Web (Web Workers): Marshaling becomes mandatory and critical on the Web (and even more so in cross-platform code supporting both Web and VM). Web Workers operate over message channels using strict structured cloning where complex custom classes cannot be sent directly unless converted into transferable primitives (like List, Map, or JSArrayBuffer).

When passing custom classes across thread boundaries, Squadron provides two primary ways to handle serialization:

• Approach A: Implement serialization directly within the custom class (via marshal() / unmarshal() or standard toJson() / fromJson()).
• Approach B: Implement a dedicated marshaler class via the SquadronMarshaler interface. Note that marshaler classes are used as annotations (for service method arguments/return types or on the custom class itself), and as a result must provide const constructors and be instantiable as const instances.

2. Approach A: Direct Serialization in Custom Classes

You can implement serialization directly within your custom class without writing a separate marshaler class:

• Dedicated methods: Implement an instance method SomeTransferable marshal({MarshalingContext? context}) and a factory constructor or static method static MyCustomType unmarshal(SomeTransferable transferable, {MarshalingContext? context}).
• Standard JSON methods: squadron_builder can also automatically detect and use standard toJson() and fromJson() methods when present. (Note: The JSON approach is simple and straightforward, but does not support a MarshalingContext, meaning it cannot handle circular references or object identity preservation across complex object graphs).

Example: Direct marshal() & unmarshal()

import 'package:squadron/squadron.dart';

class TaskItem {
  final String id;
  final String description;

  TaskItem(this.id, this.description);

  // Serialize to a transferable List or Map
  List marshal({MarshalingContext? context}) {
    return [id, description];
  }

  // Deserialize back from the transferable representation
  static TaskItem unmarshal(dynamic transferable, {MarshalingContext? context}) {
    final list = transferable as List;
    return TaskItem(list[0] as String, list[1] as String);
  }
}

Example: Standard toJson() & fromJson()

class TaskItemJson {
  final String id;
  final String description;

  TaskItemJson(this.id, this.description);

  Map<String, dynamic> toJson() => {
        'id': id,
        'description': description,
      };

  factory TaskItemJson.fromJson(Map<String, dynamic> json) =>
      TaskItemJson(json['id'] as String, json['description'] as String);
}

3. Approach B: Dedicated Marshalers via the SquadronMarshaler Interface

For cleaner separation of concerns, you can implement a separate marshaler class using the SquadronMarshaler interface (GenericMarshaler & MarshalingContext). Because these dedicated marshaler classes are used as annotations (e.g., @PersonMarshaler()), they must have a const constructor and be usable as const instances.

To send custom classes across threads via a separate marshaler, implement SquadronMarshaler<T, S>:

• T: The original custom class type.
• S: The transferable / serializable representation type (typically List or Map).

abstract class SquadronMarshaler<T, S> {
  const SquadronMarshaler();

  S marshal(T data, [MarshalingContext? context]);
  T unmarshal(S data, [MarshalingContext? context]);
}

Rule: unmarshal(marshal(data)) must produce an instance of T equivalent to the original data.

• Important Equivalence Note: Because marshaling and unmarshaling create a brand-new instance across the thread boundary, identical(original, unmarshaled) will always return false, and the equality operator (==) will return false unless explicitly overloaded in your class T.

Using GenericMarshaler & MarshalingContext

For complex object graphs, deep structures, or circular references, Squadron provides GenericMarshaler and MarshalingContext.

• MarshalingContext: Tracks object references during serialization and deserialization to prevent infinite loops (e.g., circular graphs or shared references) and preserve object identity within the same payload transfer.

Example Marshaling Implementation:

part of 'person.dart';

class PersonMarshaler extends GenericMarshaler<Person> {
  const PersonMarshaler();

  @override
  dynamic marshal(Person data, [MarshalingContext? context]) {
    var res = context?.getReference<List>(data);
    if (res != null) return res;

    res = [
      data.lastName,
      data.firstName,
      data.dateOfBirth,
    ];

    // Register reference before recursing to handle circular references
    context?.setReference(data, res);

    return res;
  }

  @override
  Person unmarshal(dynamic data, [MarshalingContext? context]) {
    data as List;
    var res = context?.getReference<Person>(data);
    if (res != null) return res;

    res = Person._(data[0], data[1], data[2]);
    context?.setReference(data, res);

    return res;
  }
}