package kcas

  1. Overview
  2. Docs

Module Kcas.LocSource

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.

Sourcetype !'a t = private
  1. | 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.

Sourceval 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.

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

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

Sourceval 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.

Sourceval get_mode : 'a t -> Mode.t

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

Sourceval get_id : 'a t -> int

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

Sourceval get : 'a t -> 'a

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

Sourceval 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.

Sourceval 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.

Sourceval 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.

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

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

Sourceval 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).

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

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

Sourceval 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).

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

incr r atomically increments r.

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

decr r atomically decrements r.