Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document GenericMemory and AtomicMemory #54642

Merged
merged 7 commits into from
Jun 10, 2024
Merged

Document GenericMemory and AtomicMemory #54642

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
501e7de
Document GenericMemory and AtomicMemory
oscardssmith May 31, 2024
25d3595
update docs to refrence intrinsics until there is an actual stable in…
oscardssmith Jun 4, 2024
2189584
Update base/genericmemory.jl
oscardssmith Jun 5, 2024
54e5809
Update base/genericmemory.jl
oscardssmith Jun 5, 2024
ee46aad
Update base/genericmemory.jl
oscardssmith Jun 5, 2024
d0fac47
Update base/genericmemory.jl
oscardssmith Jun 5, 2024
9f7959f
adress review
oscardssmith Jun 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions base/genericmemory.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Fixed-size [`DenseVector{T}`](@ref DenseVector).
A [`DenseVector{T}`](@ref DenseVector). Fixed-size, in the sense that the length of a value of this type doesn't change after construction.

Maybe it'd be better to be more precise regarding "fixed-size"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really see this is clearer. Is there an ambiguity with the original version? Would "constant length" be clearer?

Copy link
Contributor

@nsajko nsajko Jun 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps the current version is OK. My motivation is to avoid confusion with the StaticArrays.jl-sense of "constant length", where the length is in the type domain.


`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)
Comment on lines +16 to +17
Copy link
Contributor

@jakobnissen jakobnissen Jun 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const Generic = bitcast(Core.AddrSpace{CUDA}, 0)
const Global = bitcast(Core.AddrSpace{CUDA}, 1)
const Generic = Core.AddrSpace{CUDA}(0x00)
const Global = Core.AddrSpace{CUDA}(0x01)

This code doesn't work since a) bitcast is not public, and b) the integer must be a 1-byte integer for bitcast to work

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this was unresolved with the force push.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops. Will re-resolve once #54681 merges.

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.
Expand All @@ -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.
Expand All @@ -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)
oscardssmith marked this conversation as resolved.
Show resolved Hide resolved

!!! compat "Julia 1.11"
This type requires Julia 1.11 or later.
Expand Down
1 change: 1 addition & 0 deletions doc/src/base/arrays.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Base.StridedArray
Base.StridedVector
Base.StridedMatrix
Base.StridedVecOrMat
Base.GenericMemory
Base.Memory
Base.memoryref
Base.Slices
Expand Down