Return ReshapedArray from acquire! for N-D arrays

[mgyoo86]

Summary

Change acquire! N-D path to return ReshapedArray instead of SubArray{Array}.

Key benefit: Zero allocation even on cache miss - no unsafe_wrap call needed regardless of dimension pattern.

API Design

API	Return Type	Creation Cost	Use Case
acquire! 1D	SubArray{T,1,Vector{T}}	0 bytes	General 1D
acquire! N-D	ReshapedArray{T,N}	0 bytes	General N-D
unsafe_acquire!	Array{T,N}	0 (hit) / 112 (miss)	Type-unspecified paths

Why ReshapedArray?

Before (SubArray{Array})

acquire!(pool, Float64, 10, 10)
  └─> get_nd_array!()      # unsafe_wrap → 112 bytes on cache miss
      └─> view(array, :, :) # SubArray wrapper

After (ReshapedArray)

acquire!(pool, Float64, 10, 10)
  └─> get_view!(tp, 100)   # 1D SubArray (cached, 0 bytes)
      └─> reshape(view, (10,10))  # ReshapedArray (0 bytes)

Allocation Comparison

Scenario	Before (SubArray{Array})	After (ReshapedArray)
Cache hit	0 bytes	0 bytes
Cache miss	112 bytes	0 bytes
5+ dim patterns	112 bytes/miss (cache thrash)	0 bytes

When to Use Each API

Is your code path type-unspecified?
(abstract struct fields, runtime dispatch)

  YES → unsafe_acquire!()  # Returns Array (cached instance reusable)
  NO  → acquire!()         # Returns ReshapedArray (always 0 bytes)

Type-Specified Path (use acquire!)

function compute(pool, n::Int)
    m = acquire!(pool, Float64, n, n)  # ReshapedArray - compiler may optimize
    m .= 1.0
    return sum(m)
end

Type-Unspecified Path (use unsafe_acquire!)

struct Model
    chain  # No type parameter → type-unspecified
end

function forward!(model::Model, pool)
    x = unsafe_acquire!(pool, Float64, 64, 100)  # Array - cached instance reused
    model.chain(x)  # 0 bytes on cache hit
end

API Aliases

Added explicit naming aliases for users who prefer symmetric naming:

Primary	Alias	Returns
acquire!	acquire_view!	View types (SubArray/ReshapedArray)
unsafe_acquire!	acquire_array!	Array{T,N}

Both names are exported and fully interchangeable (same function via const binding).

Changes

1. src/core.jl: get_nd_view! uses reshape(1D_view, dims), added aliases
2. src/utils.jl: _validate_pool_return detects ReshapedArray
3. src/AdaptiveArrayPools.jl: Export acquire_view!, acquire_array!
4. test/: Updated type checks for ReshapedArray, added alias coverage tests

Commits

• refactor: return ReshapedArray from get_nd_view! instead of SubArray
• fix: detect ReshapedArray in _validate_pool_return
• test: update type checks for ReshapedArray returns
• feat: add acquire_view!/acquire_array! aliases

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.16%. Comparing base (94e5d5e) to head (bc3e7c6).
⚠️ Report is 19 commits behind head on master.

Files with missing lines	Patch %	Lines
src/utils.jl	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master       #4      +/-   ##
==========================================
- Coverage   97.39%   97.16%   -0.23%     
==========================================
  Files           6        6              
  Lines         422      424       +2     
==========================================
+ Hits          411      412       +1     
- Misses         11       12       +1     

☔ 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 refactors the N-dimensional array acquisition path in AdaptiveArrayPools to return Base.ReshapedArray instead of SubArray{Array}, eliminating the 112-byte allocation cost of unsafe_wrap on cache misses. The implementation now calls reshape(flat_view, dims) on a cached 1D view, providing zero-cost array shaping that works with any dimension pattern while maintaining BLAS compatibility via StridedArray.

Key Changes:

• Simplified get_nd_view! to use reshape() instead of view caching with unsafe_wrap
• Updated _validate_pool_return to properly unwrap and validate ReshapedArray instances
• Comprehensively updated tests to check for Base.ReshapedArray return types

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/core.jl	Refactored get_nd_view! to return ReshapedArray via reshape() instead of cached SubArray views; updated docstrings for acquire! and unsafe_acquire!
src/utils.jl	Added ReshapedArray detection branch in _validate_pool_return to unwrap ReshapedArray→SubArray→Array for pool memory overlap validation
test/test_multidimensional.jl	Updated type assertions from SubArray to Base.ReshapedArray and added StridedArray checks for BLAS compatibility verification
test/test_utils.jl	Updated comments and type assertions for validation tests to reflect ReshapedArray returns
Project.toml	Version bump from 0.2.0 to 0.2.1

---

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