Core Architecture

Relevant source files

• README.md
• sandbox/ConsoleApp/Program.cs
• src/ZLinq/Linq/CopyTo.cs
• src/ZLinq/Linq/Empty.cs
• src/ZLinq/Linq/Range.cs
• src/ZLinq/Linq/Repeat.cs
• src/ZLinq/Linq/SequenceEqual.cs
• src/ZLinq/ValueEnumerable.cs

This document explains the fundamental architecture of ZLinq, including its struct-based design philosophy, zero-allocation strategy, and the core abstractions that enable high-performance LINQ operations. For detailed information about the core types and their methods, see ValueEnumerable and IValueEnumerator. For information about converting existing collections, see Converting Collections to ValueEnumerable.

Design Philosophy

ZLinq achieves zero-allocation LINQ through three fundamental design principles:

1. Struct-based composition: All enumerators are value types, eliminating heap allocations during enumeration
2. Compile-time type specialization: Generic type parameters encode the entire operation chain, enabling fusion and optimization
3. Progressive optimization: Interface methods enable fallback strategies from fastest (precomputed) to slowest (element-by-element)

Unlike traditional LINQ which boxes enumerators and allocates for each operation in the chain, ZLinq builds a nested struct composition that exists entirely on the stack until materialization.

Sources: README.md44-75 src/ZLinq/ValueEnumerable.cs1-214

Core Type System

ZLinq's architecture centers on two primary abstractions that work together to enable zero-allocation enumeration:

Diagram: Core Type Relationships

Sources: src/ZLinq/ValueEnumerable.cs15-30 src/ZLinq/ValueEnumerable.cs33-60 src/ZLinq/ValueEnumerable.cs69-100

ValueEnumerable<TEnumerator, T>

The ValueEnumerable<TEnumerator, T> struct is the primary handle users interact with. It is defined as:

Key characteristics:

Property	Value	Purpose
Type	ref struct (.NET 9+) / struct (.NET 8-)	Stack allocation only
Field	TEnumerator Enumerator	Embedded enumerator state
Mutability	readonly	Copy semantics for state separation
Generic Parameter	TEnumerator	Encodes full operation chain at compile time

The ref struct constraint in .NET 9+ enables Span<T> integration while ensuring stack-only allocation. In earlier frameworks, it remains a regular struct but with the same zero-allocation guarantees.

Sources: src/ZLinq/ValueEnumerable.cs7-30 README.md44-64

IValueEnumerator

The IValueEnumerator<T> interface defines the enumeration contract with built-in optimization hooks:

Diagram: IValueEnumerator Interface Methods

Each method serves a specific optimization tier:

Method	Return Type	Purpose	Performance Tier
TryGetNext	bool	Element-by-element iteration	Slowest (always available)
TryGetNonEnumeratedCount	bool	Precomputed count	Fastest (if available)
TryGetSpan	bool	Direct memory access for SIMD	Fast (if contiguous)
TryCopyTo	bool	Bulk copy with offset support	Fast (if optimizable)

Sources: src/ZLinq/ValueEnumerable.cs33-60 README.md53-74

ValueEnumerator<TEnumerator, T>

The ValueEnumerator<TEnumerator, T> struct bridges ValueEnumerable to C#'s foreach pattern by implementing MoveNext() and Current:

This adapter is created by GetEnumerator() extension method and enables natural foreach syntax while maintaining zero allocation.

Sources: src/ZLinq/ValueEnumerable.cs69-100 src/ZLinq/ValueEnumerable.cs105-111

Struct Composition Pattern

ZLinq operations return new ValueEnumerable instances with different TEnumerator types, building a compile-time type chain:

Diagram: Struct Composition Through Operation Chaining

Each operation:

1. Takes a ValueEnumerable<TEnumerator, T> as input
2. Creates a new enumerator struct that wraps the input enumerator
3. Returns a new ValueEnumerable<TNewEnumerator, TNewResult>

This nesting continues until a terminal operation like ToArray() materializes the result.

Sources: README.md67-71 sandbox/ConsoleApp/Program.cs14-20

Progressive Optimization Strategy

ZLinq operations attempt optimizations in order from fastest to slowest:

Diagram: Optimization Decision Flow

Optimization Method Usage

Different operation types leverage different optimization methods:

Operation Category	Primary Optimization	Fallback
Count, LongCount	TryGetNonEnumeratedCount	TryGetNext loop
Sum, Average, Min, Max	TryGetSpan → SIMD	TryGetNext loop
ToArray, ToList	TryGetNonEnumeratedCount + TryCopyTo	Progressive allocation
First, Last, ElementAt	TryCopyTo with Index	TryGetNext loop
Contains, SequenceEqual	TryGetSpan → SIMD	TryGetNext loop

Sources: README.md73-74 src/ZLinq/Linq/CopyTo.cs9-37

Memory Management Strategy

ZLinq employs a three-tier memory allocation strategy:

Diagram: Memory Allocation Tiers

Stack-Only Operations

Operations like Select, Where, Take, and Skip use only stack-allocated enumerator structs:

No heap allocation occurs until materialization.

Pooled Operations

Operations requiring buffering (e.g., OrderBy, Reverse, TakeLast) rent arrays from ArrayPool<T>.Shared:

The disposal chain ensures arrays are returned when enumeration completes.

Materialization Strategy

Terminal operations like ToArray() use a progressive expansion strategy:

1. Check TryGetNonEnumeratedCount for exact size
2. If unknown, use SegmentedArrayProvider with initial stack buffer
3. Grow through pooled segments as needed
4. Allocate final right-sized array only once

Sources: README.md144-162 src/ZLinq/Linq/CopyTo.cs42-86

Type Constraint Resolution

ZLinq's approach to generic constraints enables extension method chaining without requiring 100,000+ boilerplate methods:

Diagram: Generic Constraint Solution

The signature ValueEnumerable<TEnumerator, T> where TEnumerator : struct, IValueEnumerator<T> allows C# to infer the full type chain, eliminating the need for combinatorial method generation while maintaining full type safety and zero allocation.

Sources: README.md67-72

Concrete Implementation Example

To illustrate how these abstractions work together, consider the FromRange enumerator:

Diagram: FromRange Implementation Structure

The FromRange struct demonstrates the pattern:

• Stores minimal state in fields (start, count, to, value)
• Implements TryGetNonEnumeratedCount to return count instantly
• Implements TryCopyTo with SIMD-accelerated filling
• Falls back to TryGetNext for element-by-element access

Sources: src/ZLinq/Linq/Range.cs125-219 src/ZLinq/Linq/Repeat.cs19-64

Framework-Specific Differences

ZLinq adapts its implementation based on target framework:

Feature	.NET 9+	.NET 8	.NET Standard 2.1	.NET Standard 2.0
ValueEnumerable	ref struct	struct	struct	struct
allows ref struct	Yes	No	No	No
Span<T> support	Full LINQ	Partial	Partial	None
SIMD operations	Full	Full	Limited	None
Vector<T>.Indices	Yes	Fallback	N/A	N/A

The ref struct designation in .NET 9+ enables Span<T> to flow through LINQ chains naturally while maintaining stack-only allocation guarantees.

Sources: src/ZLinq/ValueEnumerable.cs10-19 src/ZLinq/Linq/Range.cs180-209

Disposal Chain

All enumerators implement IDisposable to ensure proper resource cleanup:

Diagram: Disposal Propagation

Each enumerator's Dispose() method:

1. Calls Dispose() on its wrapped source enumerator
2. Returns any rented arrays to ArrayPool<T>.Shared
3. Clears references to prevent memory leaks

The C# using statement ensures proper disposal even with early exits or exceptions.

Sources: README.md161-162 src/ZLinq/ValueEnumerable.cs99-100

Summary

ZLinq's core architecture achieves zero-allocation LINQ through:

1. Struct-based composition - All enumerators are value types stored on the stack
2. Generic type encoding - Operation chains encoded in compile-time type parameters
3. Progressive optimization - Multiple fallback strategies from fast to slow
4. Pooled temporary storage - ArrayPool for operations requiring buffers
5. Disposal chain - Automatic resource cleanup through IDisposable

This architecture enables LINQ operations that match or exceed hand-written loop performance while maintaining the expressiveness of LINQ syntax.

Sources: README.md44-76 src/ZLinq/ValueEnumerable.cs1-214