Low-level interfaces for customizations

Atomix.IndexableRef{Indexable}

An object IndexableRef(data, indices) represents a reference to the location data[indices...].

A reference object supports Atomix.pointer, Atomix.asstorable, and eltype:

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.pointer(ref) === pointer(a, 1)
true

julia> Atomix.asstorable(ref, 1.0)
1

julia> eltype(ref)
Int64

To customize the behavior of atomic updates of an Indexable, define the following methods:

• Atomix.get(ref::Atomix.IndexableRef{Indexable}, order) -> v::eltype(ref)
• Atomix.set!(ref::Atomix.IndexableRef{Indexable}, v, order)
• Atomix.replace!(ref::Atomix.IndexableRef{Indexable}, expected, desired, success_order, failure_order) -> (; old, success).
• Atomix.modify!(ref::Atomix.IndexableRef{Indexable}, op, x, order) -> (old => new)

The ordering arguments (order, success_order, and failure_order) are one of:

• Atomix.monotonic
• Atomix.acquire
• Atomix.release
• Atomix.acquire_release (Atomix.acq_rel)
• Atomix.sequentially_consistent (Internal.seq_cst)

Atomix.get(ref, order) -> x
Atomix.get(ref) -> x

Atomically load the value x stored in ref with ordering order. The default ordering Atomix.sequentially_consistent is used when not specified.

Examples

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.get(ref)
111

Atomix.set!(ref, x, order)
Atomix.set!(ref, x)

Atomically store the value x in ref with ordering order. The default ordering Atomix.sequentially_consistent is used when not specified.

Examples

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.set!(ref, 123);

julia> a[1]
123

Atomix.modify!(ref, op, x, order) -> (old => new)
Atomix.modify!(ref, op, x) -> (old => new)

Atomically update ref from stored value old to new = op(old, x) with ordering order (default: Atomix.sequentially_consistent). Return a pair old => new.

Examples

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.modify!(ref, +, 123)
111 => 234

Atomix.replace!(ref, expected, desired, success_order, fail_order) -> (; old, success)
Atomix.replace!(ref, expected, desired, order) -> (; old, success)
Atomix.replace!(ref, expected, desired) -> (; old, success)

Atomically replace the value stored in ref to desired if expected is stored. A named tuple (; old::eltype(ref), success::Bool) is returned.

Examples

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.replace!(ref, 111, 123)
(old = 111, success = true)

Atomix.swap!(ref, new, order) -> old
Atomix.swap!(ref, new) -> old

Swap the old stored in ref with the new value and establish the memory ordering order (default: Atomix.sequentially_consistent).

Notes for implementers: Atomix.swap!(ref, new, order) is defined as Atomix.modify!(ref, Atomix.right, x, order). Thus, only Atomix.modify! has to be defined.

Examples

julia> using Atomix

julia> a = [111, 222, 333];

julia> ref = Atomix.IndexableRef(a, (1,));

julia> Atomix.swap!(ref, 123)
111

julia> a[1]
123