Annotations

Squadron uses annotations to guide the code generation process and handle complex scenarios like custom data types or platform-specific builds.

---

@SquadronService

Applied to a class to mark it as a Squadron Service. The builder will generate a corresponding Worker and optionally a WorkerPool.

Parameters

• pool (bool, default: true): If true, a WorkerPool class is generated alongside the Worker.
• targetPlatform (int): Specifies the supported platforms.
  • TargetPlatform.vm: Native platforms (Mobile/Desktop/Server).
  • TargetPlatform.js: Web (JavaScript).
  • TargetPlatform.wasm: Web (Web Assembly).
  • TargetPlatform.web: Shortcut for js | wasm.
  • TargetPlatform.all: Shortcut for vm | web.
• baseUrl (String): For Web platforms, specifies the URL where the worker scripts are hosted.
• version (int): Optional version number appended to the worker URL (e.g., ?v=1) for cache busting on the web.

Special Constructors

• @SquadronService.vm(): Shortcut for native platforms.
• @SquadronService.web(): Shortcut for Web platforms.
• @SquadronService.local(): Marks a service that can be shared with other workers but doesn't need its own dedicated thread immediately (or is part of a larger orchestration).

---

@SquadronMethod

Applied to methods within a @SquadronService class to expose them to the worker thread.

Parameters

• inspectRequest (bool, default: false): Only used on Web platforms. If true, Squadron will deeply analyze the WorkerRequest contents to identify transferable objects (like Channel objects) that require special handling or ownership transfer when being sent to the worker.
• inspectResponse (bool, default: false): Only used on Web platforms. Same as inspectRequest, but for deeply analyzing the WorkerResponse produced by the worker to identify transferable objects being sent back to the main thread.
• withContext (bool?): Controls whether a Marshaling Context should be used. This preserves object identities if the same object is sent multiple times. If null, it's enabled automatically when marshaling is required.

---

Marshaler Annotations

Squadron supports custom serialization for complex types. You can create a marshaler by implementing SquadronMarshaler<T, S> and use it as an annotation on parameters or the class itself.

Example

@PersonMarshaler() // Applied to the class: all instances will use this marshaler
class Person { ... }

// OR

@SquadronMethod()
@PersonMarshaler() // Applied to the method: the return value will use this marshaler
FutureOr<Person> getMe() { ... }

// OR

@SquadronMethod()
FutureOr<double> getAge(@PersonMarshaler() Person p) { ... } // Applied to a parameter

Common interfaces:

• SquadronMarshaler<T, S>: Base interface for custom serialization.
• GenericMarshaler<T>: Often used for simple toJson/fromJson style marshaling.

---

@sharedService

A special annotation used when a service instance needs to be passed to and shared by multiple workers. This is useful for singleton-like behavior where different workers need to access common state or resources.

Next Step: Learn more about Workers and Pools.