Module Atomic.Loc

Atomic "locations"

type 'a t = 'a Atomic.Loc.t

A value of type 'a Atomic.Loc.t represents an "atomic location" - a reference to an atomic mutable field within a record. They can be obtained using the [%atomic.loc] construct - for example, if you have a record like:

  type t =
    { name : string
    ; mutable count : int [@atomic]
    }

and a value r : t, you can obtain an Atomic.Loc.t pointing to the count field with the expression [%atomic.loc r.count]. You can then use the functions in this module to perform atomic operations on that atomic field, for example:

  let incr_count (r : t) = Atomic.Loc.incr [%atomic.loc r.count]

The functions in this module mirror the functions on atomic refs in Atomic, and the same guidance holds: if you have an atomic mutable field containing an integer, you should mutate it using the atomic operations on integers (fetch_and_add, add, sub, logand, logor, logxor, incr, or decr). If you have an atomic mutable field of some other type, you should use update or get_and_update.

val sexp_of_t : 'a. ('a -> Sexplib0.Sexp.t) -> 'a t -> Sexplib0.Sexp.t
val get : 'a. 'a t @ contended -> 'a

get [%atomic.loc r.f] gets the current value of r.f.

val set : 'a. 'a t @ contended -> 'a -> unit

set [%atomic.loc r.f] v sets the value of r.f to v.

Use atomic operations, update, or get_and_update instead of geting the value, modifying it in-place, then seting it

val exchange : 'a. 'a t @ contended -> 'a -> 'a

exchange [%atomic.loc] r.f v sets the value of r.f to v, and returns the previous value

val compare_and_set : 'a. 'a t @ contended -> if_phys_equal_to:'a -> replace_with:'a -> Compare_failed_or_set_here.t

compare_and_set [%atomic.loc r.f] ~if_phys_equal_to ~replace_with sets the new value of r.f to replace_with only if its current value is physically equal to if_phys_equal_to -- the comparison and the set occur atomically. Returns Set_here if the value was set to replace_with by this call to compare_and_set, or Compare_failed if the current value was not physically equal to if_phys_equal_to and hence the atomic reference was left unchanged.

val compare_exchange : 'a. 'a t @ contended -> if_phys_equal_to:'a -> replace_with:'a -> 'a

compare_exchange [%atomic.loc r.f] ~if_phys_equal_to ~replace_with sets the new value of r.f to replace_with only if its current value is physically equal to if_phys_equal_to -- the comparison and the set occur atomically. Returns the previous value of r.f, or the current (unchanged) value if the comparison failed.

val update : 'a. 'a t @ local contended -> (pure_f:('a -> 'a) @ local -> unit) @ local

update t ~pure_f atomically updates t to be the result of pure_f (get t). pure_f may be called multiple times, so should be free of side effects.

val get_and_update : 'a. 'a t @ local contended -> (pure_f:('a -> 'a) @ local -> 'a) @ local

get_and_update t ~pure_f atomically updates t to be the result of pure_f (get t). pure_f may be called multiple times, so should be free of side effects. Returns the old value.

val fetch_and_add : int t @ contended -> int -> int

fetch_and_add [%atomic.loc r.f] n atomically increments the value of r.f by n, and returns the previous value (before the increment).

val add : int t @ contended -> int -> unit

add [%atomic.loc r.f] i atomically adds i to the value of r.f

val sub : int t @ contended -> int -> unit

sub [%atomic.loc r.f] i atomically subtracts i from the value of r.f

val logand : int t @ contended -> int -> unit

logand [%atomic.loc r.f] i atomically bitwise-ands i onto r.f.

val logor : int t @ contended -> int -> unit

logor [%atomic.loc r.f] i atomically bitwise-ands i onto r.f.

val logxor : int t @ contended -> int -> unit

logxor [%atomic.loc r.f] i atomically bitwise-xors i onto r.f.

val incr : int t @ local contended -> unit

incr [%atomic.loc r.f] atomically increments the value of r.f by 1.

val decr : int t @ local contended -> unit

decr [%atomic.loc r.f] atomically decrements the value of r.f by 1.