Add documentation for atomicint.

Together with all of the atomic integer operations.

Author: jnthn

doc/Type/atomicint.pod6

@@ -0,0 +1,264 @@
+=begin pod
+
+=TITLE class atomicint
+
+=SUBTITLE Integer (native storage at the platform's atomic operation size)
+
+    class atomicint is Int is repr('P6int') { }
+
+An C<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.
+
+    # 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 C<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;
+    start { for ^20000 { $total⚛++ } } xx 4;
+    say $total;
+
+    # Either works correctly or dies, depending on platform.
+    my int $total = 0;
+    start { for ^20000 { $total⚛++ } } xx 4;
+    say $total;
+
+    # Wrong due to lack of use of the atomic increment operator.
+    my atomicint $total = 0;
+    start { for ^20000 { $total++ } } xx 4;
+    say $total;
+
+=head1 Routines
+
+=head2 atomic-assign
+
+Defined as: 
+
+    multi sub atomic-assign(atomcint $ is rw, int $value)
+    multi sub atomic-assign(atomcint $ is rw, Int() $value)
+
+Performs an atomic assignment to a native integer, which may be in a lexical,
+attribute, or native array element. If C<$value> cannot unbox to a 64-bit
+native integer due to being too large, an exception will be thrown. If the
+size of C<atomicint> is only 32 bits, then an out of range C<$value> will be
+silently truncated. The C<atomic-assign> routine ensures that any required
+barriers are performed such that the changed value will be "published" to
+other threads.
+
+=head2 atomic-fetch
+
+Defined as: 
+
+    multi sub atomic-fetch(atomcint $ 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 atomc-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 C<$i> is not updated in the
+loop, and so lift the read out of the loop, thus causing the program to never
+terminate.
+
+=head2 atomic-inc
+
+Defined as:
+
+    multi sub atomic-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.
+
+=head2 atomic-dec
+
+Defined as:
+
+    multi sub atomic-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.
+
+=head2 atomic-add
+
+Defined as:
+
+    multi sub atomic-add(atomicint $ is rw, int $value)
+    multi sub atomic-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 C<$value> is too big to
+unbox to a 64-bit integer, an exception will be thrown. If C<$value> otherwise
+overflows C<atomicsize> then it will be silently truncated before the addition
+is performed.
+
+=head2 cas
+
+Defined as:
+
+    multi sub cas(atomicint $target is rw, int $expected, int $value)
+    multi sub cas(atomicint $target is rw, Int() $expected, Int() $value)
+    multi sub cas(atomicint $target is rw, &operation)
+
+Performs an atomic compare and swap of the native integer value in location
+C<$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 C<$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 int $master = 0;
+    await start { 
+        if cas($master, 0, 1) == 0 {
+            say "Master!"
+        }
+    } xx 4
+
+Will reliably only ever print C<Master!> one time, as only one of the threads
+will be successful in changing the 0 into a 1.
+
+Both C<$expected> and C<$value> will be coerced to C<Int> and unboxed if
+needed. An exception will be thrown if they value cannot be represented as a
+64-bit integer. If the size of C<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 C<$exepcted> and the result of the code object as C<$value>. If
+this fails, it will read the latest value, and retry, until a CAS operation
+succeeds. Therefore, an atomic multiply of an C<atomicint> C<$i> by 2 could
+be implemented as:
+
+    cas $i, -> int $current { $current * 2 }
+
+If another thread changed the value while C<$current * 2> was being calculated
+then the block would be called again with the latest value for a futher
+attempt, and this would be repeated until success.
+
+=head1 Operators
+
+=head2 infix ⚛=
+
+    multi sub infix:<⚛=>(atomcint $ is rw, int $value)
+    multi sub infix:<⚛=>(atomcint $ is rw, Int() $value)
+
+Performs an atomic assignment to a native integer, which may be in a lexical,
+attribute, or native array element. If C<$value> cannot unbox to a 64-bit
+native integer due to being too large, an exception will be thrown. If the
+size of C<atomicint> is only 32 bits, then an out of range C<$value> will be
+silently truncated. The C<⚛=> operator ensures that any required barriers are
+performed such that the changed value will be "published" to other threads.
+
+=head2 prefix ⚛
+
+    multi sub prefix:<⚛>(atomcint $ 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 C<$i> is not updated in the
+loop, and so lift the read out of the loop, thus causing the program to never
+terminate.
+
+=head2 prefix ⚛++
+
+    multi sub prefix:<⚛++>(atomcint $ 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.
+
+=head2 postfix ⚛++
+
+    multi sub postfix:<⚛++>(atomcint $ 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.
+
+=head2 prefix ⚛--
+
+    multi sub prefix:<⚛-->(atomcint $ 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.
+
+=head2 postfix ⚛--
+
+    multi sub postfix:<⚛-->(atomcint $ 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.
+
+=head2 infix ⚛+=
+
+Defined as:
+
+    multi sub infix:<⚛+=>(atomicint $ is rw, int $value)
+    multi sub 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 C<$value> is too big to unbox to a
+64-bit integer, an exception will be thrown. If C<$value> otherwise overflows
+C<atomicsize> then it will be silently truncated before the addition is
+performed.
+
+=end pod