CollectivePulseBase<P> class abstract

The abstract base class for CollectivePulse implementations.

A CollectivePulseBase is the internal engine that bundles multiple independent pulses into a single atomic wave. Each sub‑pulse retains its own identity, trace, and lifecycle — they travel together but remain distinct.

How it works

• Extends _SinglePulseBase with a payload of type Iterable<Pulse<P>>.
• Overrides isComposite to return true, marking this as a bundle.
• Provides the payload getter that returns the bundled pulses.
• Manages the branch counter for completion tracking across all sub‑pulses.

Non‑obvious: the collective iterates over itself, not its payload

The iterator returns an iterator over the collective itself (a single element), not over the individual pulses. This is by design — the collective is a single unit that happens to contain multiple pulses. To access individual pulses, use the payload getter:

for (final p in collective.payload) {
  print(p.payload);
}

Non‑obvious: the branch counter tracks completion

The _branches counter is incremented in the constructor. This counter ensures that the collective's completion callback fires only when all sub‑pulses have finished processing. Without this, the framework wouldn't know when a composite pulse is truly complete.

Example

// You never create this directly — the framework does it for you:
final collective = Pulse.batch([pulse1, pulse2, pulse3]);
// collective is a CollectivePulseBase instance

See also:

• CollectivePulse – the public interface.
• Pulse.batch – the factory that creates collective pulses.
• Pulse.+ – the operator that creates collective pulses.