Document GenericMemory and AtomicMemory (#54642)

Closes #53854. After talking with @vtjnash, we are ready to commit to the `GenericMemory` interface. Sorry @nsajko that this took me so long to get around to. --------- Co-authored-by: Marek Kaluba <[email protected]> Co-authored-by: Neven Sajko <[email protected]>
JuliaLang · Jun 10, 2024 · 589fd1a · 589fd1a
1 parent 7197c9e
commit 589fd1a
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 5 deletions.
diff --git a/base/genericmemory.jl b/base/genericmemory.jl
@@ -3,9 +3,21 @@
 ## genericmemory.jl: Managed Memory
 
 """
- GenericMemory{kind::Symbol, T, addrspace=Core.CPU} <: AbstractVector{T}
+ GenericMemory{kind::Symbol, T, addrspace=Core.CPU} <: DenseVector{T}
 
-One-dimensional dense array with elements of type `T`.
+Fixed-size [`DenseVector{T}`](@ref DenseVector).
+
+`kind` can currently be either `:not_atomic` or `:atomic`. For details on what `:atomic` implies, see [`AtomicMemory`](@ref)
+
+`addrspace` can currently only be set to Core.CPU. It is designed to to permit extension by other systems
+such as GPUs, which might define values such as:
+```
+module CUDA
+const Generic = bitcast(Core.AddrSpace{CUDA}, 0)
+const Global = bitcast(Core.AddrSpace{CUDA}, 1)
+end
+```
+The exact semantics of these other addrspaces is defined by the specific backend, but will error if the user is attempting to access these on the CPU.
 
 !!! compat "Julia 1.11"
  This type requires Julia 1.11 or later.
@@ -15,7 +27,7 @@ GenericMemory
 """
  Memory{T} == GenericMemory{:not_atomic, T, Core.CPU}
 
-One-dimensional dense array with elements of type `T`.
+Fixed-size [`DenseVector{T}`](@ref DenseVector).
 
 !!! compat "Julia 1.11"
  This type requires Julia 1.11 or later.
@@ -25,8 +37,18 @@ Memory
 """
  AtomicMemory{T} == GenericMemory{:atomic, T, Core.CPU}
 
-One-dimensional dense array with elements of type `T`, where each element is
-independently atomic when accessed, and cannot be set non-atomically.
+Fixed-size [`DenseVector{T}`](@ref DenseVector).
+Access to its any of its elements is performed atomically (with `:monotonic` ordering).
+Setting any of the elements must be accomplished using the `@atomic` macro and explicitly specifying ordering.
+
+!!! warning
+ Each element is independently atomic when accessed, and cannot be set non-atomically.
+ Currently the `@atomic` macro and higher level interface have not been completed,
+ but the building blocks for a future implementation are the internal intrinsics
+ `Core.memoryrefget`, `Core.memoryrefset!`, `Core.memoryref_isassigned`, `Core.memoryrefswap!`,
+ `Core.memoryrefmodify!`, and `Core.memoryrefreplace!`.
+
+For details, see [Atomic Operations](@ref man-atomic-operations)
 
 !!! compat "Julia 1.11"
  This type requires Julia 1.11 or later.

diff --git a/doc/src/base/arrays.md b/doc/src/base/arrays.md
@@ -30,6 +30,7 @@ Base.StridedArray
 Base.StridedVector
 Base.StridedMatrix
 Base.StridedVecOrMat
+Base.GenericMemory
 Base.Memory
 Base.memoryref
 Base.Slices