Design Documents

For in-depth analysis of design decisions, implementation tradeoffs, and architectural choices, see the design documents in the repository:

API Design

hybridapidesign.md Two-API strategy (acquire! vs unsafe_acquire!) and type stability analysis

Caching & Performance

ndarrayapproach_comparison.md N-way cache design, boxing analysis, and ReshapedArray benchmarks
fixedslotscodegen_design.md Zero-allocation iteration via @generated functions and fixed-slot type dispatch

Macro Internals

untrackedacquiredesign.md Macro-based untracked acquire detection and 1-based sentinel pattern

Backend Extensions

cudaextensiondesign.md CUDA backend architecture and package extension loading

Document Overview

Document	Focus Area	Key Insights
hybridapidesign	API strategy	View types for zero-alloc, Array for FFI
ndarrayapproach_comparison	Caching	N-way associative cache reduces header allocation
fixedslotscodegen_design	Codegen	@generated functions enable type-stable iteration
untrackedacquiredesign	Macro safety	Sentinel pattern ensures correct cleanup
cudaextensiondesign	GPU support	Seamless CPU/CUDA API parity

See Also

How It Works - High-level architecture overview
Type Dispatch & Cache - Technical deep-dive
@with_pool Macro Internals - Macro transformation details