From 90c432f226da00d026a9d6c7886b43679c59ea35 Mon Sep 17 00:00:00 2001 From: Oscar Smith Date: Mon, 10 Jun 2024 12:45:39 -0400 Subject: [PATCH] Document GenericMemory and AtomicMemory (#54642) Closes https://github.com/JuliaLang/julia/issues/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 Co-authored-by: Neven Sajko (cherry picked from commit 589fd1a0266eef6d8d234a59754a72a1802757cb) --- base/genericmemory.jl | 32 +++++++++++++++++++++++++++----- doc/src/base/arrays.md | 1 + 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/base/genericmemory.jl b/base/genericmemory.jl index c1dc215a68d33..82a956411aabd 100644 --- 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 index 20e8e81614b9e..9acf11ea4fa68 100644 --- 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