On this page:
atomic-fixnum?
make-atomic-fixnum
5.2.1 Basic Atomic Fixnum Operations
atomic-fixnum-get
atomic-fixnum-set!
atomic-fixnum-add!
atomic-fixnum-update!
5.2.2 Conditional Atomic Fixnum Operations
atomic-fixnum-compare-and-set!
atomic-fixnum-compare-and-exchange!
atomic-fixnum-compare-and-add!
5.2.3 Compound Atomic Fixnum Operations
atomic-fixnum-get-then-set!
atomic-fixnum-get-then-add!
atomic-fixnum-add-then-get!
atomic-fixnum-get-then-update!
atomic-fixnum-update-then-get!
8.0

5.2 Atomic Fixnums

 (require rebellion/concurrency/atomic/fixnum)
  package: rebellion

An atomic fixnum is a thread-safe, future-safe, kill-safe, break-safe, and lock-free mutable object containing a single fixnum. The most basic operation on an atomic fixnum is a compare and set, which attempts to set the atomic fixnum to a new value if and only if its current value is equal to some specific value. When Racket is compiled with support for futures, this operation is implemented with a single hardware instruction.

All other operations on atomic fixnums are implemented in terms of atomic compare and set with a retry loop. For example, atomic-fixnum-add! gets the current value of the atomic fixnum, adds it with an input number, then attempts to set the value to the computed result if and only if the atomic fixnum’s current value at the time of the compare-and-set is equal to its value at the time the result was computed. If that isn’t the case due to contention with competing threads or futures, then atomic-fixnum-add! retries the operation again. This is a form of Optimistic Concurrency Control (OCC).

procedure

(atomic-fixnum? v)  boolean?

  v : any/c
A predicate for atomic fixnums.

procedure

(make-atomic-fixnum initial-value    
  [#:name name])  atomic-fixnum?
  initial-value : fixnum?
  name : (or/c interned-symbol? #false) = #false
Constructs a new atomic fixnum named name and set to initial-value. Providing a name is recommended for debugging and logging purposes.

5.2.1 Basic Atomic Fixnum Operations

procedure

(atomic-fixnum-get num)  fixnum?

  num : atomic-fixnum?
Returns the current value of num.

Examples:
> (define num (make-atomic-fixnum 42))
> (atomic-fixnum-get num)

42

procedure

(atomic-fixnum-set! num replacement)  void?

  num : atomic-fixnum?
  replacement : fixnum?
Changes the current value of num to replacement.

Examples:

procedure

(atomic-fixnum-add! num amount)  void?

  num : atomic-fixnum?
  amount : fixnum?
Adds amount to num.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

procedure

(atomic-fixnum-update! num updater)  void?

  num : atomic-fixnum?
  updater : (-> fixnum? fixnum?)
Applies updater to the current value of num and sets num to the value returned by updater.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Because the update may be retried, updater should be safe to apply multiple times. Beware that any side effects in updater may be executed more than once.

Examples:

5.2.2 Conditional Atomic Fixnum Operations

procedure

(atomic-fixnum-compare-and-set! num    
  expected    
  replacement)  boolean?
  num : atomic-fixnum?
  expected : fixnum?
  replacement : fixnum?
Attempts a compare and set operation on num, setting it to replacement if and only if its current value is equal to expected. Returns a boolean indicating whether or not the operation succeeded.

Examples:

procedure

(atomic-fixnum-compare-and-exchange! num    
  expected    
  replacement)  fixnum?
  num : atomic-fixnum?
  expected : fixnum?
  replacement : fixnum?
Attempts a compare and exchange operation on num, setting it to replacement if and only if its current value is equal to expected. Returns the value of num before the exchange, which will be equal to replacement if and only if the operation suceeeded.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

procedure

(atomic-fixnum-compare-and-add! num    
  expected    
  amount)  boolean?
  num : atomic-fixnum?
  expected : fixnum?
  amount : fixnum?
Attempts a compare and add operation on num, adding amount to it if and only if its current value is equal to expected. Returns a boolean indicating whether or not the operation succeeded.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

5.2.3 Compound Atomic Fixnum Operations

procedure

(atomic-fixnum-get-then-set! num    
  replacement)  fixnum?
  num : atomic-fixnum?
  replacement : fixnum?
Sets num to replacement and returns its previous value.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

procedure

(atomic-fixnum-get-then-add! num amount)  fixnum?

  num : atomic-fixnum?
  amount : fixnum?
Adds amount to num and returns its previous value.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

procedure

(atomic-fixnum-add-then-get! num amount)  fixnum?

  num : atomic-fixnum?
  amount : fixnum?
Adds amount to num and returns its new value.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Examples:

procedure

(atomic-fixnum-get-then-update! num    
  updater)  fixnum?
  num : atomic-fixnum?
  updater : (-> fixnum? fixnum?)
Applies updater to num and returns its previous value.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Because the update may be retried, updater should be safe to apply multiple times. Beware that any side effects in updater may be executed more than once.

Examples:

procedure

(atomic-fixnum-update-then-get! num    
  updater)  fixnum?
  num : atomic-fixnum?
  updater : (-> fixnum? fixnum?)
Applies updater to num and returns its new value.

This operation is not guaranteed to terminate. The operation may be retried if num is concurrently mutated, and there are no limits on how many times it may be retried.

Because the update may be retried, updater should be safe to apply multiple times. Beware that any side effects in updater may be executed more than once.

Examples: