HubHandle typedef

HubHandle = ({Pulse? Function(Pulse pulse) emit, Future<Pulse?> Function(Pulse pulse) emitAsync, Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest, Cell root, Iterable<Cell> spokes})

A management handle for a Signal Distribution Hub, providing a unified interface to control a multi-destination routing cluster.

When to use

You get this from Cell.hub. Use it when you need to fan‑out a single pulse to multiple specialised handlers based on Pulse.type.

How it works

The handle contains a root cell (the ingress) and a set of spokes (the handlers). When you emit or ingest a pulse, it's routed to the appropriate spoke(s) based on the hub's configuration.

Non‑obvious

• If you provide a custom relay, the default routing is bypassed – you must manually deliver pulses to the spokes.
• The hub's ingest with serializedCompletion: true waits for all spokes to finish processing before completing the Future.

Implementation

typedef HubHandle = ({
  /// The central ingress node that governs the distribution hub. This node
  /// acts as the central gateway and **Integrity Gate** for the cluster.
  Cell root,

  /// The collection of specialized downstream nodes (branches) that
  /// receive signals fanned out from the [root].
  Iterable<Cell> spokes,

  /// Synchronously injects a [Pulse] into the hub's [root] at **Native Speed**.
  ///
  /// Returns the resulting pulse if it successfully passed the **Integrity
  /// Gate** and was broadcast; returns `null` if neutralized by a policy guard.
  Pulse? Function(Pulse pulse) emit,

  /// Asynchronously injects a stimulus, ensuring **Serialized Transformation**
  /// through the system's **Conactive Lock**.
  ///
  /// This modality is required if the [root] or any [spokes] involve
  /// I/O-bound validation or cross-domain security checks.
  Future<Pulse?> Function(Pulse pulse) emitAsync,

  /// The **Primary Distribution Ingress** handle.
  ///
  /// This handle is the "Entry Port" for the switching fabric. It is used
  /// to introduce a single [Pulse] that will be demultiplexed across
  /// all registered `spokes` according to the hub's [manifest].
  ///
  /// ### The Consequence of [serializedCompletion]:
  /// This parameter defines the **Convergent Boundary** for the fan-out
  /// operation:
  ///
  /// *   **Synchronous Convergence (`true`)**: The returned [Future] will
  ///     only resolve once the signal has propagated through the root AND
  ///     all associated spokes have finished their transformations. This
  ///     guarantees that the entire **Collection** has stabilized before
  ///     the caller proceeds.
  /// *   **Parallel Propagation (`false`)**: The [Future] resolves once the
  ///     signal is safely enqueued at the `root`. The distribution to
  ///     spokes happens as a background task, maximizing throughput for
  ///     high-frequency telemetry or logging scenes.
  Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest
});