Document unsafe_wrap(Array, ...) lifetimes, and support host buffers

[maleadt]

unsafe_wrap(Array, a::oneArray) gives you a CPU Array that shares memory with a oneArray, without copying. The returned Array does not keep a alive, though, which wasn't documented anywhere: if a is garbage collected, the Array silently refers to freed memory. The docstring now has a prominent warning about that (and about synchronizing before touching the memory), matching what the other back-ends document for the same function.

It also works for arrays backed by host buffers now, not only shared buffers, since those are just as accessible from the CPU:

a = oneVector{Int, oneL0.HostBuffer}([1, 2])
b = unsafe_wrap(Array, a)   # previously a MethodError
b[1] = 100
Array(a)                    # [100, 2]

Tested on an Iris Xe.

[github-actions]

Your PR requires formatting changes to meet the project's style guidelines.
Please consider running Runic (git runic main) to apply these changes.

Click here to view the suggested changes.

diff --git a/src/array.jl b/src/array.jl
index 9df190c..ff2ca3f 100644
--- a/src/array.jl
+++ b/src/array.jl
@@ -613,8 +613,10 @@ a shared buffer (as created by `oneArray{T}(undef, ...)`) or a host buffer.
     asynchronously, so call `synchronize()` before accessing the returned array after
     using `arr` on the device.
 """
-function Base.unsafe_wrap(::Type{Array},
-                          arr::oneArray{T,N,<:Union{oneL0.SharedBuffer,oneL0.HostBuffer}}) where {T,N}
+function Base.unsafe_wrap(
+        ::Type{Array},
+        arr::oneArray{T, N, <:Union{oneL0.SharedBuffer, oneL0.HostBuffer}}
+    ) where {T, N}
   # TODO: can we make this more convenient by increasing the buffer's refcount and using
   #       a finalizer on the Array? does that work when taking views etc of the Array?
   ptr = reinterpret(Ptr{T}, pointer(arr))
diff --git a/test/array.jl b/test/array.jl
index f71d6ce..3989278 100644
--- a/test/array.jl
+++ b/test/array.jl
@@ -102,12 +102,12 @@ end
   oneAPI.@sync copyto!(a, 2, [200], 1, 1)
   @test b == [100, 200]
 
-  # the same works for arrays backed by host memory
-  c = oneVector{Int,oneL0.HostBuffer}([1, 2])
-  d = unsafe_wrap(Array, c)
-  @test d == [1, 2]
-  d[1] = 100
-  @test Array(c) == [100, 2]
+    # the same works for arrays backed by host memory
+    c = oneVector{Int, oneL0.HostBuffer}([1, 2])
+    d = unsafe_wrap(Array, c)
+    @test d == [1, 2]
+    d[1] = 100
+    @test Array(c) == [100, 2]
 end
 
 # https://github.com/JuliaGPU/CUDA.jl/issues/2191

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.87%. Comparing base (85dd4cf) to head (6725848).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #650   +/-   ##
=======================================
  Coverage   80.87%   80.87%           
=======================================
  Files          56       56           
  Lines        4088     4088           
=======================================
  Hits         3306     3306           
  Misses        782      782           

☔ View full report in Codecov by Harness.
📢 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.