(refac!): Default acquire! → Array, remove unsafe_* API#33
Merged
Conversation
BREAKING CHANGE: `acquire!` now returns `Array{T,N}` instead of `SubArray`.
New API surface:
- `acquire!(pool, T, dims...)` → Array{T,N} (was SubArray)
- `acquire_array!(pool, T, dims...)` → alias for acquire!
- `acquire_view!(pool, T, dims...)` → SubArray (was old acquire!)
- `zeros!`, `ones!`, `similar!` → Array (was SubArray)
Removed (no deprecation):
- `unsafe_acquire!`, `unsafe_zeros!`, `unsafe_ones!`, `unsafe_similar!`
Motivation: Julia 1.11+ setfield!-based Array wrapper reuse makes
zero-alloc Array returns possible, eliminating the need for the
unsafe_ prefix and making Array the natural default.
…ility Array structural invalidation via setfield!(:size) requires Julia 1.11+. After the acquire! → Array default change, these tests need version gating since legacy path uses N-way cache (C struct Array, no setfield!). - Gate size(v)==(0,) assertions with @static if VERSION >= v"1.11-" - Remove redundant duplicate test blocks (now identical post-refactor) - Merge legacy 5-way N-way cache tests (eviction expected with CACHE_WAYS=4)
…ve unsafe_*) - Replace all unsafe_acquire!/unsafe_zeros!/unsafe_ones!/unsafe_similar! references - Update return type descriptions: acquire! now returns Array, not views - Add acquire_view! as the new view API (was old acquire! behavior) - Update acquire_array! as alias for acquire! - Update API tables, code examples, and comparison sections across all docs
…acy acquire_view! - safe_prod docstring: generalize "unsafe_wrap" → "array creation operations" - legacy acquire_view!: add _set_pending_callsite! for borrow tracking parity with modern path
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #33 +/- ##
==========================================
- Coverage 97.02% 96.53% -0.50%
==========================================
Files 14 14
Lines 2658 2566 -92
==========================================
- Hits 2579 2477 -102
- Misses 79 89 +10
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR updates AdaptiveArrayPools’ public API to make acquire! (and convenience functions) return native Array{T,N} by default, removes the unsafe_* API surface, and adds acquire_view! as the explicit view-returning API, with corresponding updates across macros, CUDA extension glue, docs, and tests.
Changes:
- Switch default acquisition to
Array(acquire!,zeros!,ones!,similar!) and introduceacquire_view!for the old view behavior. - Remove
unsafe_acquire!/unsafe_zeros!/unsafe_ones!/unsafe_similar!and retarget macro transformations to_acquire_impl!/_acquire_view_impl!. - Update test suite and documentation to match new return types and migration guidance.
Reviewed changes
Copilot reviewed 49 out of 49 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/test_zero_allocation.jl | Update zero-alloc patterns for new defaults |
| test/test_state.jl | Adjust state assertions for Array-returning acquire! |
| test/test_safety.jl | Update safety/invalidation expectations by version |
| test/test_nway_cache.jl | Update cache tests for Array-returning acquire! |
| test/test_multidimensional.jl | Update multi-dim return type assertions |
| test/test_macro_internals.jl | Update macro internals tests for new call names |
| test/test_macro_expansion.jl | Update macro expansion expectations for view/array split |
| test/test_fallback_reclamation.jl | Update fallback-type tests to acquire! |
| test/test_disabled_pooling.jl | Update disabled pooling expectations for convenience funcs |
| test/test_debug.jl | Update debug/runtime escape tests for new defaults |
| test/test_coverage.jl | Update coverage tests for removed unsafe APIs |
| test/test_convenience.jl | Update convenience function tests to Array-returning behavior |
| test/test_compile_escape.jl | Update compile-time escape classification for new API |
| test/test_borrow_registry.jl | Update borrow registry tests to acquire! |
| test/test_bitarray.jl | Update Bit/Bool behavior tests under new defaults |
| test/test_basic.jl | Update basic type assertions for acquire! |
| test/test_backend_macro_expansion.jl | Update backend macro expansion tests for view API |
| test/test_aliases.jl | Update alias/identity expectations for new API surface |
| test/legacy/test_nway_cache.jl | Update legacy cache tests for legacy branch behavior |
| test/cuda/test_nway_cache.jl | Update CUDA cache tests for new call names/semantics |
| test/cuda/test_extension.jl | Update CUDA extension tests for new defaults |
| test/cuda/test_disabled_pool.jl | Remove unsafe-disabled-pool tests; keep remaining coverage |
| test/cuda/test_convenience.jl | Update CUDA convenience function tests to new defaults |
| test/cuda/test_allocation.jl | Update CUDA allocation tests for new acquisition API |
| src/types.jl | Update core type docs/notes for new acquisition semantics |
| src/state.jl | Update invalidation comments to match new API naming |
| src/macros.jl | Remove unsafe transforms; add _acquire_view_impl! path |
| src/legacy/types.jl | Update legacy docs to match new API naming |
| src/legacy/state.jl | Update legacy invalidation commentary |
| src/legacy/bitarray.jl | Update Bit acquisition internals for new view/array split |
| src/legacy/acquire.jl | Legacy branch: acquire! returns Array; add acquire_view! |
| src/debug.jl | Update runtime escape detection docs/comments for new defaults |
| src/convenience.jl | Remove unsafe convenience API; document new return types |
| src/bitarray.jl | Update Bit acquisition internals for new view/array split |
| src/acquire.jl | Make acquire! return Array; add acquire_view! implementations |
| src/AdaptiveArrayPools.jl | Update exports to remove unsafe_* API surface |
| ext/AdaptiveArrayPoolsCUDAExt/convenience.jl | Remove unsafe disabled-pool CUDA convenience methods |
| ext/AdaptiveArrayPoolsCUDAExt/acquire.jl | Retarget CUDA impl hooks to _acquire_view_impl! |
| docs/src/reference/api.md | Update API reference for new defaults and aliases |
| docs/src/features/safety.md | Update safety examples to “pool-acquired array” |
| docs/src/features/cuda-support.md | Update CUDA docs for new API split |
| docs/src/features/configuration.md | Reframe CACHE_WAYS as affecting acquire! |
| docs/src/basics/safety-rules.md | Update guidance: avoid resizing acquire! arrays |
| docs/src/basics/quick-start.md | Update quick-start return type guidance |
| docs/src/basics/api-essentials.md | Update essentials page for new APIs/return types |
| docs/src/architecture/type-dispatch.md | Update architecture docs to Array-by-default model |
| docs/src/architecture/how-it-works.md | Update high-level explanation for new API split |
| docs/src/architecture/design-docs.md | Update design-docs index text for new API model |
| README.md | Update README messaging for new defaults and removed unsafe APIs |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
…scape detection tests
- Remove duplicate acquire!/test_throws from test_coverage.jl (was unsafe_acquire! → acquire! rename artifact), replace with acquire_view! coverage
- Fix stale comments in debug.jl and types.jl docstring (acquire! → acquire_view! for view paths)
- Add defensive ReshapedArray{Array/BitArray} branches in _validate_pool_return (unreachable via normal API since reshape(::Array) returns Array via jl_reshape_array, but guards edge cases)
- Add escape detection tests for acquire_view! N-D (ReshapedArray{SubArray}) and reshape!(pool, ...) (Array)
- Add v0.2→v0.3 migration guide
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Flip the default return type of
acquire!from views (SubArray/ReshapedArray) to nativeArray{T,N}, remove the entireunsafe_*API surface, and introduceacquire_view!as the explicit view API.Breaking change — all
unsafe_acquire!,unsafe_zeros!,unsafe_ones!,unsafe_similar!are removed with no deprecation period.Motivation
On Julia 1.11+,
Arraybecame a mutable struct enablingsetfield!-based wrapper reuse with zero allocation — the same guarantee views had. This eliminated the original reason views were the default (zero-alloc advantage). With Array now zero-alloc too, it's the more natural default:Ptr{T}) without conversion::Array{T,N}type constraints directlyThe
unsafe_*prefix was misleading — these functions were never unsafe in the memory-safety sense. Removing them simplifies the API from 8 acquire functions to 3.New API Surface
acquire!(pool, T, dims...)Array{T,N}acquire_view!(pool, T, dims...)SubArray/ReshapedArrayacquire!behavioracquire_array!(pool, T, dims...)Array{T,N}acquire!zeros!,ones!,similar!Array{T,N}trues!,falses!BitArray{N}reshape!Array{T,N}Removed:
unsafe_acquire!,unsafe_zeros!,unsafe_ones!,unsafe_similar!Bit sentinel:
acquire!(pool, Bit, ...)still returnsBitVector/BitArray{N}(unchanged)CUDA: No behavioral change —
CuArrayreturned for bothacquire!andacquire_view!Migration Guide
Search-and-replace for upgrading:
unsafe_acquire!→acquire!(or just delete —acquire!already returns Array)unsafe_zeros!→zeros!unsafe_ones!→ones!unsafe_similar!→similar!