Documentation: An example for allocating Unified Memory arrays

[fghorow]

"""This is a hack from the JuliaCon 2019 Hackathon;
Credit to Tim Bessard and Rohan McLure for helping me with the
intricacies of the memory slinging.

This allocates "unified" memory on both the host cpu and the gpu.
"Unified" memory is communicated between the host and the gpu at the discretion of the CUDA driver.
The intention is that the communication overlaps with the computation, without the programmer needing to
know about the underlying details.

IMPORTANT!
This assumes that prealloc_array is already built elsewhere. (That fits my particular use case.)
The user is responsible for copying the contents of prealloc_array into the cpu array.
The user is responsible for calling Mem.free(buf) after the arrays go out of scope.

julia> using CUDAdrv, CuArrays
julia> foo = Array{Float32,1}([1., 2., 3., 4.]); nothing
julia> ca,ga,b = build_cu_unified_array_similar(foo); nothing
julia> ca .= foo; nothing
julia> ga ≈ ca
True
julia> ca ≈ foo
True

"""
function build_cu_unified_array_similar(prealloc_array::Array{T,N}) where {T,N}
buf = Mem.alloc(Mem.UnifiedBuffer, sizeof(prealloc_array))
cpu_array = unsafe_wrap(Array, convert(Ptr{T}, buf), size(prealloc_array))
gpu_array = unsafe_wrap(CuArray, convert(CuPtr{T}, buf), size(prealloc_array))
return cpu_array, gpu_array, buf
end