atomicint Reference

Integer (native storage at the platform's atomic operation size)

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

sub atomic-assign #

multi atomic-assign(atomicint $ is rw, int $value)
multi atomic-assign(atomicint $ is rw, Int() $value)

Performs an atomic assignment to a native integer, which may be in a lexical, attribute, or native array element. If $value cannot unbox to a 64-bit native integer due to being too large, an exception will be thrown. If the size of atomicint is only 32 bits, then an out of range $value will be silently truncated. The atomic-assign routine ensures that any required barriers are performed such that the changed value will be "published" to

sub atomic-fetch #

multi atomic-fetch(atomicint $ is rw)

Performs an atomic read of a native integer, which may live in a lexical, attribute, or native array element. Using this routine instead of simply using the variable ensures that the latest update to the variable from other threads will be seen, both by doing any required hardware barriers and also preventing the compiler from lifting reads. For example: Is certain to terminate, while in: It would be legal for a compiler to observe that $i is not updated in the

sub atomic-fetch-inc #

multi atomic-fetch-inc(atomicint $ is rw)

Performs an atomic increment on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before incrementing it. Overflow will wrap around silently.

sub atomic-fetch-dec #

multi atomic-fetch-dec(atomicint $ is rw)

Performs an atomic decrement on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before decrementing it. Overflow will wrap around silently.

sub atomic-fetch-add #

multi atomic-fetch-add(atomicint $ is rw, int $value)
multi atomic-fetch-add(atomicint $ is rw, Int() $value)

Performs an atomic addition on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before the addition was performed. Overflow will wrap around silently. If $value is too big to unbox to a 64-bit integer, an exception will be thrown. If $value otherwise overflows atomicint then it will be silently truncated before the addition

sub atomic-fetch-sub #

multi atomic-fetch-sub(atomicint $ is rw, int $value)
multi atomic-fetch-sub(atomicint $ is rw, Int() $value)

Performs an atomic subtraction on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before the subtraction was performed. Underflow will wrap around silently. If $value is too big to unbox to a 64-bit integer, an exception will be thrown. If $value otherwise overflows atomicint then it will be silently truncated before the

sub atomic-inc-fetch #

multi atomic-inc-fetch(atomicint $ is rw)

Performs an atomic increment on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value resulting from the increment. Overflow will wrap around silently.

sub atomic-dec-fetch #

multi atomic-dec-fetch(atomicint $ is rw)

Performs an atomic decrement on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value resulting from the decrement. Overflow will wrap around silently.

sub cas #

multi cas(atomicint $target is rw, int $expected, int $value)
multi cas(atomicint $target is rw, Int() $expected, Int() $value)
multi cas(atomicint $target is rw, &operation)

Performs an atomic compare and swap of the native integer value in location $target. The first two forms have semantics like: Except it is performed as a single hardware-supported atomic instruction, as if all memory access to $target were blocked while it took place. Therefore it is safe to attempt the operation from multiple threads without any other synchronization. For example: Will reliably only ever print Master! one time, as only one of the threads

infix ⚛= #

multi infix:<⚛=>(atomicint $ is rw, int $value)
multi infix:<⚛=>(atomicint $ is rw, Int() $value)

Performs an atomic assignment to a native integer, which may be in a lexical, attribute, or native array element. If $value cannot unbox to a 64-bit native integer due to being too large, an exception will be thrown. If the size of atomicint is only 32 bits, then an out of range $value will be silently truncated. The ⚛= operator ensures that any required barriers are performed such that the changed value will be "published" to other threads.

prefix ⚛ #

multi prefix:<⚛>(atomicint $ is rw)

Performs an atomic read of a native integer, which may live in a lexical, attribute, or native array element. Using this operator instead of simply using the variable ensures that the latest update to the variable from other threads will be seen, both by doing any required hardware barriers and also preventing the compiler from lifting reads. For example: Is certain to terminate, while in: It would be legal for a compiler to observe that $i is not updated in the

prefix ++⚛ #

multi prefix:<++⚛>(atomicint $ is rw)

Performs an atomic increment on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value resulting from the increment. Overflow will wrap around silently.

postfix ⚛++ #

multi postfix:<⚛++>(atomicint $ is rw)

Performs an atomic increment on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before incrementing it. Overflow will wrap around silently.

prefix --⚛ #

multi prefix:<--⚛>(atomicint $ is rw)

Performs an atomic decrement on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value resulting from the decrement. Overflow will wrap around silently.

postfix ⚛-- #

multi postfix:<⚛-->(atomicint $ is rw)

Returns (atomicint $ is rw.

Performs an atomic decrement on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Returns the value as seen before decrementing it. Overflow will wrap around silently.

infix ⚛+= #

multi infix:<⚛+=>(atomicint $ is rw, int $value)
multi infix:<⚛+=>(atomicint $ is rw, Int() $value)

Performs an atomic addition on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Evaluates to the result of the addition. Overflow will wrap around silently. If $value is too big to unbox to a 64-bit integer, an exception will be thrown. If $value otherwise overflows atomicint then it will be silently truncated before the addition is

infix ⚛-= #

multi infix:<⚛-=>(atomicint $ is rw, int $value)
multi infix:<⚛-=>(atomicint $ is rw, Int() $value)

Performs an atomic subtraction on a native integer. This will be performed using hardware-provided atomic operations. Since the operation is atomic, it is safe to use without acquiring a lock. Evaluates to the result of the subtraction. Underflow will wrap around silently. If $value is too big to unbox to a 64-bit integer, an exception will be thrown. If $value otherwise overflows atomicint then it will be silently truncated before the

infix ⚛−= #

Synonym for ⚛-= using U+2212 minus.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

14 no-output

class atomicint is Int is repr('P6int') { }

# Would typically only work on a 64-bit machine and VM build.
my int64 $active = 0;
$active⚛++;

# Would typically only work on a 32-bit machine and VM build.
my int32 $active = 0;
$active⚛++;

# Will work portably, though can only portably assume range of 32 bits.
my atomicint $active = 0;
$active⚛++;

# Correct (will always output 80000)
my atomicint $total = 0;
await start { for ^20000 { $total⚛++ } } xx 4;
say $total;

# *** WRONG *** due to lack of use of the atomicint type.
# Either works correctly or dies, depending on platform.
my int $total = 0;
await start { for ^20000 { $total⚛++ } } xx 4;
say $total;

# *** WRONG *** due to lack of use of the atomic increment operator.
my atomicint $total = 0;
await start { for ^20000 { $total++ } } xx 4;
say $total;

my atomicint $i = 0;
start { atomic-assign($i, 1) }
while atomic-fetch($i) == 0 { }

my atomicint $i = 0;
start { atomic-assign($i, 1) }
while $i == 0 { }

my int $seen = $target;
if $seen == $expected {
$target = $value;
}
return $seen;

my atomicint $master = 0;
await start {
    if cas($master, 0, 1) == 0 {
        say "Master!"
    }
} xx 4

cas $i, -> int $current { $current * 2 }

my atomicint $i = 0;
start { $i ⚛= 1 }
while ⚛$i == 0 { }

my atomicint $i = 0;
start { $i ⚛= 1 }
while $i == 0 { }