Convenience Functions & DisabledPool

[mgyoo86]

Summary

Pool-aware convenience functions (zeros!, ones!, similar!) with backend-preserving DisabledPool{Backend} type.

Key Changes

Convenience Functions

Function	Returns	Description
zeros!(pool, [T,] dims...)	View	Zero-initialized, uses acquire! internally
ones!(pool, [T,] dims...)	View	One-initialized
similar!(pool, A, ...)	View	Match eltype/size of existing array
unsafe_zeros!, unsafe_ones!, unsafe_similar!	Array	Native array variants

Default element type: Float64 (CPU), Float32 (CUDA)

DisabledPool{Backend}

Zero-cost singleton that preserves backend context when pooling is disabled.

# USE_POOLING=false or MAYBE_POOLING_ENABLED[]=false
@with_pool :cuda pool begin
    # pool::DisabledPool{:cuda}
    v = zeros!(pool, 100)  # → CUDA.zeros(Float32, 100), not Array!
end

Why needed: Previously pool = nothing when disabled, losing :cuda context.

Utility Functions

• pooling_enabled(pool) - Returns true for active pool, false for DisabledPool
• default_eltype(pool) - Returns Float64 (CPU) or Float32 (CUDA)

Internal: Explicit _impl! Delegators

Macros transform zeros!(pool, ...) → _zeros_impl!(pool, ...). For DisabledPool, these delegate back to public API with explicit type signatures for proper CUDA inlining:

# Instead of variadic args... (may not inline well)
@inline _zeros_impl!(p::DisabledPool, ::Type{T}, dims::Vararg{Int,N}) where {T,N} = zeros!(p, T, dims...)

Breaking Changes

• Removed Nothing fallbacks: pool = nothing no longer works
• Migration: Replace pool === nothing with !pooling_enabled(pool)

Files Changed

• src/convenience.jl - Convenience functions + DisabledPool fallbacks + _impl! delegators
• src/acquire.jl - DisabledPool acquire methods + _impl! delegators
• src/types.jl - DisabledPool{Backend}, DISABLED_CPU, pooling_enabled()
• src/macros.jl - Emit DisabledPool{backend}() instead of nothing
• ext/.../convenience.jl - CUDA DisabledPool methods
• docs/ - Updated documentation

[codecov]

Codecov Report

❌ Patch coverage is 97.50000% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.03%. Comparing base (52fc1d0) to head (4c240ba).
⚠️ Report is 21 commits behind head on master.

Files with missing lines	Patch %	Lines
src/macros.jl	91.57%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #10      +/-   ##
==========================================
+ Coverage   94.48%   97.03%   +2.55%     
==========================================
  Files           7        8       +1     
  Lines         671      945     +274     
==========================================
+ Hits          634      917     +283     
+ Misses         37       28       -9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces convenience functions (zeros!, ones!, similar! and their unsafe_* variants) along with a backend-preserving DisabledPool{Backend} type that replaces the previous nothing pattern when pooling is disabled. This is a well-designed breaking change that improves type safety and maintains backend context (:cpu vs :cuda) throughout the codebase.

Key changes:

• New convenience functions with sensible defaults (Float64 for CPU, Float32 for CUDA)
• DisabledPool{Backend} type replaces nothing to preserve backend context when pooling is disabled
• Breaking change: removes Nothing fallbacks (migration path: use pooling_enabled(pool) instead of pool === nothing)

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/types.jl	Adds DisabledPool{Backend} type and pooling_enabled() utility
src/convenience.jl	Implements new convenience functions with DisabledPool fallbacks and _impl! delegators
src/acquire.jl	Updates DisabledPool fallbacks for acquire functions
src/state.jl	Adds type deduplication in @generated checkpoint!/rewind!, DisabledPool no-ops
src/macros.jl	Updates macro expansion to use DisabledPool, adds convenience function support
src/utils.jl	Updates _validate_pool_return signature
src/AdaptiveArrayPools.jl	Exports new functions
ext/AdaptiveArrayPoolsCUDAExt/convenience.jl	Implements CUDA-specific DisabledPool methods with Float32 default
ext/AdaptiveArrayPoolsCUDAExt/AdaptiveArrayPoolsCUDAExt.jl	Includes convenience.jl
test/test_convenience.jl	Comprehensive tests for new convenience functions
test/test_coverage.jl	Extensive coverage tests for edge cases and internal functions
test/cuda/*	CUDA-specific tests for DisabledPool and convenience functions
test/*.jl	Updates all tests from nothing to DISABLED_CPU
docs/*.md	Updates documentation with DisabledPool pattern and convenience function API
README.md	Updates examples and performance benchmarks

The implementation is sound with excellent test coverage. The breaking change is well-documented, and the migration path is clear. No critical issues identified.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.