kcas 0.7.0 · OCaml Package

Shared memory locations.

This module is essentially compatible with the Stdlib.Atomic module, except that a number of functions take some optional arguments that one usually need not worry about.

type !'a t = private

| Loc : {
1. state : 'state;
2. id : 'id;
} -> 'a t
(*
The shape is transparent to allow the compiler to perform optimizations on array accesses. User code should treat this type as abstract.
*)

Type of shared memory locations.

val make : ?padded:bool -> ?mode:Mode.t -> 'a -> 'a t

make initial creates a new shared memory location with the initial value.

The optional padded argument defaults to false. If explicitly specified as ~padded:true the location will be allocated in a way to avoid false sharing. For relatively long lived shared memory locations this can improve performance and make performance more stable at the cost of using more memory. It is not recommended to use ~padded:true for short lived shared memory locations.

The optional mode argument defaults to `Obstruction_free. If explicitly specified as `Lock_free, the location will always be accessed using the lock-free operating mode. This may improve performance in rare cases where a location is updated frequently and obstruction-free read-only accesses would almost certainly suffer from interference.

Locations are allocated such that accessing the locations inside a transaction in allocation order from oldest to youngest is as fast as possible.

val make_contended : ?mode:Mode.t -> 'a -> 'a t

make_contended initial is equivalent to make ~padded:true initial.

val make_array : ?padded:bool -> ?mode:Mode.t -> int -> 'a -> 'a t array

make_array n initial creates an array of n new shared memory locations with the initial value.

The locations are allocated in such an order that accessing the locations in the array inside a transaction in order from the highest index to the lowest index is as fast as possible.

val get_mode : 'a t -> Mode.t

get_mode r returns the operating mode of the shared memory location r.

val get_id : 'a t -> int

get_id r returns the unique id of the shared memory location r.

val get : 'a t -> 'a

get r reads the current value of the shared memory location r.

val get_as : ?timeoutf:float -> ('a -> 'b) -> 'a t -> 'b

get_as f loc is equivalent to f (get loc). The given function f may raise the Retry.Later exception to signal that the conditional load should be retried only after the location has been modified outside of the conditional load. It is also safe for the given function f to raise any other exception to abort the conditional load.

val compare_and_set : ?backoff:Backoff.t -> 'a t -> 'a -> 'a -> bool

compare_and_set r before after atomically updates the shared memory location r to the after value if the current value of r is the before value.

val update : ?timeoutf:float -> ?backoff:Backoff.t -> 'a t -> ('a -> 'a) -> 'a

update r f repeats let b = get r in compare_and_set r b (f b) until it succeeds and then returns the b value. The given function f may raise the Retry.Later exception to signal that the update should only be retried after the location has been modified outside of the update. It is also safe for the given function f to raise any other exception to abort the update.

val modify : 
  ?timeoutf:float ->
  ?backoff:Backoff.t ->
  'a t ->
  ('a -> 'a) ->
  unit

modify r f is equivalent to update r f |> ignore.

val exchange : ?backoff:Backoff.t -> 'a t -> 'a -> 'a

exchange r after atomically updates the shared memory location r to the after value and returns the current value (before the exchange).

val set : ?backoff:Backoff.t -> 'a t -> 'a -> unit

set r after atomically updates the shared memory location r to the after value.

val fetch_and_add : ?backoff:Backoff.t -> int t -> int -> int

fetch_and_add r n atomically increments the value of r by n, and returns the current value (before the increment).

val incr : ?backoff:Backoff.t -> int t -> unit

incr r atomically increments r.

val decr : ?backoff:Backoff.t -> int t -> unit

decr r atomically decrements r.

package kcas