Fused Iterator

What “fused” means in iterator contracts

A fused iterator is defined by what happens after exhaustion, not by how it produces items. Once it has returned no more items, it must keep returning none on later calls. That makes the iterator’s terminal state predictable, which is useful when consumers need a stable “done means done” contract.

This is a narrow but important behavioural guarantee. Many iterators are well-behaved in practice, but fused iterators formalise the expectation so downstream code can rely on exhaustion as a permanent state rather than a one-time observation.

Why the exhausted state matters

The key property is idempotence after completion. After exhaustion, repeated calls do not re-open the stream, revive buffered values, or require callers to defend against inconsistent results. That simplifies control flow in loops, state machines, and adapters that must poll an iterator more than once.

Without that guarantee, consumers may need extra bookkeeping to avoid treating a second empty result as a fresh failure, a transient condition, or a signal to retry. With a fused iterator, exhaustion becomes a clear end condition that can be checked repeatedly without changing meaning.

How fused iterators shape composition

Fused iterators are most useful when iterators are wrapped, chained, filtered, or consumed by helpers that may continue probing after completion. In those settings, the contract reduces ambiguity between “already finished” and “temporarily unavailable”. It also makes it easier to compose iterator adapters without each layer having to re-implement its own end-of-stream guard.

The concept is especially valuable in library code, where predictable terminal behaviour improves interoperability between independent iterator implementations. A fused contract gives the next layer confidence that once the source is spent, no later call will produce a surprise item.

Practical consequences for consumers and API design

For consumers, the main benefit is simpler reasoning: once the iterator is exhausted, it stays exhausted. For API designers, the main decision is whether to promise that permanence or leave exhaustion behaviour unspecified. When the guarantee is documented, callers can write cleaner logic and avoid defensive patterns that assume the iterator might recover after finishing.

Common misunderstanding: fused does not mean the iterator cannot be empty initially, only that an exhausted iterator remains exhausted. It is a contract about post-completion behaviour, not a guarantee of how many items will appear before completion.

Related resources from NHI Mgmt Group

• What happens when a fused load instruction is emitted with a negative offset that is not masked correctly?
• When should teams move from fused key trust to remotely provisioned keys?
• Iterator Age
• ImageSequence.Iterator