class atomicint

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

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

An atomicint is a native integer sized such that CPU-provided atomic operations can be performed upon it. On a 32-bit CPU it will typically be 32 bits in size, and on an a 64-bit CPU it will typically be 64 bits in size. It exists to allow writing portable code that uses atomic operations.

Note: Rakudo releases before 2017.08 had no support for atomicints.

# 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⚛++;

The use of the atomicint type does not automatically provide atomicity; it must be used in conjunction with the atomic operations.

# 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;

Routines

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 other threads.

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:

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

Is certain to terminate, while in:

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

It would be legal for a compiler to observe that $i is not updated in the loop, and so lift the read out of the loop, thus causing the program to never terminate.

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 is performed.

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 subtraction is performed.

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:

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

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:

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

Will reliably only ever print Master! one time, as only one of the threads will be successful in changing the 0 into a 1.

Both $expected and $value will be coerced to Int and unboxed if needed. An exception will be thrown if the value cannot be represented as a 64-bit integer. If the size of atomicint is only 32 bits then the values will be silently truncated to this size.

The third form, taking a code object, will first do an atomic fetch of the current value and invoke the code object with it. It will then try to do an atomic compare and swap of the target, using the value passed to the code object as $expected and the result of the code object as $value. If this fails, it will read the latest value, and retry, until a CAS operation succeeds. Therefore, an atomic multiply of an atomicint $i by 2 could be implemented as:

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

If another thread changed the value while $current * 2 was being calculated then the block would be called again with the latest value for a further attempt, and this would be repeated until success.

Operators

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:

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

Is certain to terminate, while in:

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

It would be legal for a compiler to observe that $i is not updated in the loop, and so lift the read out of the loop, thus causing the program to never terminate.

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)

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)

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 performed.

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 subtraction is performed.

infix ⚛−=

Synonym for ⚛-= using U+2212 minus.

Routines

sub atomic-assign

sub atomic-fetch

sub atomic-fetch-inc

sub atomic-fetch-dec

sub atomic-fetch-add

sub atomic-fetch-sub

sub atomic-inc-fetch

sub atomic-dec-fetch

sub cas

Operators

infix ⚛=

prefix ⚛

prefix ++⚛

postfix ⚛++

prefix --⚛

postfix ⚛--

infix ⚛+=

infix ⚛-=

infix ⚛−=

See Also