txt: ## atomicint.md
  class atomicint
  
  Integer (native storage at the platform's atomic operation size)
  
  ```raku
  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 `atomicint`s.
  
  ```raku
  # 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.
  
  ```raku
  # 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](#class_atomicint "go to top of document")[§](#Routines "direct link")
  
  ## [sub atomic-assign](#class_atomicint "go to top of document")[§](#sub_atomic-assign "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-fetch "direct link")
  
  ```raku
  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:
  
  ```raku
  my atomicint $i = 0;
  start { atomic-assign($i, 1) }
  while atomic-fetch($i) == 0 { }
  ```
  
  Is certain to terminate, while in:
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-fetch-inc "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-fetch-dec "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-fetch-add "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-fetch-sub "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-inc-fetch "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_atomic-dec-fetch "direct link")
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#sub_cas "direct link")
  
  ```raku
  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:
  
  ```raku
  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:
  
  ```raku
  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`](/type/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:
  
  ```raku
  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](#class_atomicint "go to top of document")[§](#Operators "direct link")
  
  ## [infix ⚛=](#class_atomicint "go to top of document")[§](#infix_⚛= "direct link")
  
  ```raku
  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 ⚛](#class_atomicint "go to top of document")[§](#prefix_⚛ "direct link")
  
  ```raku
  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:
  
  ```raku
  my atomicint $i = 0;
  start { $i ⚛= 1 }
  while ⚛$i == 0 { }
  ```
  
  Is certain to terminate, while in:
  
  ```raku
  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 ++⚛](#class_atomicint "go to top of document")[§](#prefix_++⚛ "direct link")
  
  ```raku
  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 ⚛++](#class_atomicint "go to top of document")[§](#postfix_⚛++ "direct link")
  
  ```raku
  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 --⚛](#class_atomicint "go to top of document")[§](#prefix_--⚛ "direct link")
  
  ```raku
  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 ⚛--](#class_atomicint "go to top of document")[§](#postfix_⚛-- "direct link")
  
  ```raku
  multi postfix:<⚛-->(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 ⚛+=](#class_atomicint "go to top of document")[§](#infix_⚛+= "direct link")
  
  ```raku
  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 ⚛-=](#class_atomicint "go to top of document")[§](#infix_⚛-= "direct link")
  
  ```raku
  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 ⚛−=](#class_atomicint "go to top of document")[§](#infix_⚛−= "direct link")
  
  Synonym for ⚛-= using U+2212 minus.
  