jon.recoil.org

Module Portable_kernel.Subatomic

A Subatomic.t is a hybrid between ref and Atomic.t. When you have uncontended access to a subatomic, you can do non-atomic reads/writes to it, like a ref. When you have shared access to a subatomic, you can do atomic reads/writes to it, like an Atomic. Nothing can be done to a contended subatomic.

The safety of this interface depends on two differences from each of its counterparts:

Conceptually, 'a Atomic.t could be implemented as a globally-shared 'a Subatomic.t:

  type 'a isolated =
    | Isolated : ('a, 'k) Capsule.Data.t * 'k Capsule.Key.t -> 'a isolated
  [@@unboxed]

  type 'a atomic = 'a subatomic isolated
type !('a : value_or_null) t = 'a Basement.Subatomic.t
include sig ... end
val equal : 'a. ('a -> 'a -> bool) -> 'a Portable_kernel.Subatomic.t -> 'a Portable_kernel.Subatomic.t -> bool
val sexp_of_t : 'a. ('a -> Sexplib0.Sexp.t) -> 'a Portable_kernel.Subatomic.t -> Sexplib0.Sexp.t
include sig ... end
include sig ... end
val t_of_sexp : 'a. (Sexplib0.Sexp.t -> 'a) -> Sexplib0.Sexp.t -> 'a Portable_kernel.Subatomic.t
val make : ('a : value_or_null). 'a -> 'a Portable_kernel.Subatomic.t @@ portable

Create a subatomic reference; has the same codegen as constructing an Atomic.t or a ref.

val make_alone : ('a : value_or_null). 'a -> 'a Portable_kernel.Subatomic.t @@ portable

Create a subatomic reference that is alone on a cache line. See Atomic.make_alone for details.

val get : ('a : value_or_null). 'a Portable_kernel.Subatomic.t @ local -> 'a

Read the current value of a subatomic.

  • get performs a non-atomic read on an uncontended subatomic.
  • get [@synchro atomic] and Shared.get perform an atomic read on a shared subatomic.
val set : 'a. 'a Portable_kernel.Subatomic.t @ local -> 'a -> unit

Update the current value of a subatomic.

  • set performs a non-atomic write on an uncontended subatomic.
  • set [@synchro atomic] and Shared.set perform an atomic write on a shared subatomic.
val exchange : 'a. 'a Portable_kernel.Subatomic.t @ local -> 'a -> 'a

Update the current value of a subatomic, and return the previous value.

  • update performs a non-atomic read/write on an uncontended subatomic.
  • update [@synchro atomic] and Shared.update perform an atomic read/write on a shared subatomic.
val compare_and_set : 'a. 'a Portable_kernel.Subatomic.t @ local -> if_phys_equal_to:'a -> replace_with:'a -> Portable_kernel.Atomic.Compare_failed_or_set_here.t

If the current value of the subatomic is phys_equal to if_phys_equal, then update it to replace_with and return Set_here; otherwise, return Compare_failed (with the subatomic left unchanged).

  • compare_and_set performs a non-atomic read/compare/write on an uncontended subatomic.
  • compare_and_set [@synchro atomic] and Shared.compare_and_set perform an atomic read/compare/write on a shared subatomic.
val compare_exchange : 'a. 'a Portable_kernel.Subatomic.t @ local -> if_phys_equal_to:'a -> replace_with:'a -> 'a

If the current value of the subatomic is phys_equal to if_phys_equal, then update it to replace_with and return the previous value; otherwise, return current (unchanged) value.

  • compare_exchange performs a non-atomic read/compare/write on an uncontended subatomic.
  • compare_exchange [@synchro atomic] and Shared.compare_exchange perform an atomic read/compare/write on a shared subatomic.
val update : 'a. 'a Portable_kernel.Subatomic.t @ local -> pure_f:('a -> 'a) @ local -> unit

Update t to be the result of pure_f (get t); if t is changed before the whole operation is complete, retry until success. pure_f may be called multiple times, so should be free of side effects.

  • update performs a non-atomic read/compare/write on an uncontended subatomic. pure_f still may be called multiple times due to nonportable threading or if pure_f is not actually pure.
  • update [@synchro atomic] and Shared.update perform an atomic read/compare/write on a shared subatomic.
val get_and_update : 'a. 'a Portable_kernel.Subatomic.t @ local -> pure_f:('a -> 'a) @ local -> 'a

Update t to be the result of pure_f (get t), and return the old value; if t is changed before the whole operation is complete, retry until success. pure_f may be called multiple times, so should be free of side effects.

  • get_and_update performs a non-atomic read/compare/write on an uncontended subatomic. pure_f still may be called multiple times due to nonportable threading or if pure_f is not actually pure.
  • get_and_update [@synchro atomic] and Shared.get_and_update perform an atomic read/compare/write on a shared subatomic.
val fetch_and_add : int Portable_kernel.Subatomic.t @ local -> int -> int

Increments the value of a subatomic by the given value, and return the previous value (before the increment).

  • fetch_and_add performs a non-atomic update on an uncontended subatomic.
  • fetch_and_add [@synchro atomic] and Shared.fetch_and_add perform an atomic update on a shared subatomic.
val add : int Portable_kernel.Subatomic.t @ local -> int -> unit

Add the given value to the subatomic.

  • add performs a non-atomic update on an uncontended subatomic.
  • add [@synchro atomic] and Shared.add perform an atomic update on a shared subatomic.
val sub : int Portable_kernel.Subatomic.t @ local -> int -> unit

Subtract the given value from the subatomic.

  • sub performs a non-atomic update on an uncontended subatomic.
  • sub [@synchro atomic] and Shared.sub perform an atomic update on a shared subatomic.
val logand : int Portable_kernel.Subatomic.t @ local -> int -> unit

Apply bitwise-and of the given value to the subatomic.

  • logand performs a non-atomic update on an uncontended subatomic.
  • logand [@synchro atomic] and Shared.logand perform an atomic update on a shared subatomic.
val logor : int Portable_kernel.Subatomic.t @ local -> int -> unit

Apply bitwise-or of the given value to the subatomic.

  • logor performs a non-atomic update on an uncontended subatomic.
  • logor [@synchro atomic] and Shared.logor perform an atomic update on a shared subatomic.
val logxor : int Portable_kernel.Subatomic.t @ local -> int -> unit

Apply bitwise-xor of the given value to the subatomic.

  • logxor performs a non-atomic update on an uncontended subatomic.
  • logxor [@synchro atomic] and Shared.logxor perform an atomic update on a shared subatomic.
val incr : int Portable_kernel.Subatomic.t @ local -> unit

Increment a subatomic by 1.

  • incr performs a non-atomic update on an uncontended subatomic.
  • incr [@synchro atomic] and Shared.incr perform an atomic update on a shared subatomic.
val decr : int Portable_kernel.Subatomic.t @ local -> unit

Decrement a subatomic by 1.

  • decr performs a non-atomic update on an uncontended subatomic.
  • decr [@synchro atomic] and Shared.decr perform an atomic update on a shared subatomic.
module Shared : sig ... end
module Loc : sig ... end

A Subatomic.Loc.t is the subatomic analog of Atomic.Loc.t, i.e. a subatomic reference to a field of a record.