LanguageExt.Core ► Concurrency ► Atom

Atoms provide a way to manage shared, synchronous, independent state without locks. You can use them to wrap up immutable data structures and then atomically update them using the various Swap methods, or read them by calling the Value property.

If a conflict is encountered during a Swap operation, the operation is re-run using the latest state, and so you should minimise the time spent in the Swap function, as well as make sure there are no side-effects, otherwise all bets are off.

See the concurrency section of the wiki for more info.

Usage

record Person(string Name, string Surname);

// Create a new atom
var person = Atom(new Person("Paul", "Louth"));

// Modify it atomically
person.Swap(p => p with { Surname = $"{p.Name}y" });

// Take a snapshot of the state of the atom 
var snapshot = p.Value;

Contents

Atom <A>

Swap (Func<A, A> f)
SwapEff (Func<A, Eff<A>> f)
SwapEff <RT> (Func<A, Eff<RT, A>> f)
SwapAsync (Func<A, ValueTask<A>> f)
SwapAff (Func<A, Aff<A>> f)
SwapAff (Func<A, ValueTask<A>> f)
SwapAff <RT> (Func<A, Aff<RT, A>> f)
Swap <X> (X x, Func<X, A, A> f)
SwapEff <X> (X x, Func<X, A, Eff<A>> f)
SwapEff <RT, X> (X x, Func<X, A, Eff<RT, A>> f)
SwapAsync <X> (X x, Func<X, A, ValueTask<A>> f)
SwapAff <X> (X x, Func<X, A, Aff<A>> f)
SwapAff <X> (X x, Func<X, A, ValueTask<A>> f)
SwapAff <RT, X> (X x, Func<X, A, Aff<RT, A>> f)
Swap <X, Y> (X x, Y y, Func<X, Y, A, A> f)
SwapEff <X, Y> (X x, Y y, Func<X, Y, A, Eff<A>> f)
SwapEff <RT, X, Y> (X x, Y y, Func<X, Y, A, Eff<RT, A>> f)
SwapAsync <X, Y> (X x, Y y, Func<X, Y, A, ValueTask<A>> f)
SwapAff <X, Y> (X x, Y y, Func<X, Y, A, Aff<A>> f)
SwapAff <X, Y> (X x, Y y, Func<X, Y, A, ValueTask<A>> f)
SwapAff <RT, X, Y> (X x, Y y, Func<X, Y, A, Aff<RT, A>> f)
Value
ToString ()

Atom <M, A>

Swap (Func<M, A, A> f)
SwapEff (Func<M, A, Eff<A>> f)
SwapEff <RT> (Func<M, A, Eff<RT, A>> f)
SwapAsync (Func<M, A, ValueTask<A>> f)
SwapAff (Func<M, A, Aff<A>> f)
SwapAff (Func<M, A, ValueTask<A>> f)
SwapAff <RT> (Func<M, A, Aff<RT, A>> f)
Swap <X> (X x, Func<M, X, A, A> f)
SwapEff <X> (X x, Func<M, X, A, Eff<A>> f)
SwapEff <RT, X> (X x, Func<M, X, A, Eff<RT, A>> f)
SwapAsync <X> (X x, Func<M, X, A, ValueTask<A>> f)
SwapAff <X> (X x, Func<M, X, A, Aff<A>> f)
SwapAff <X> (X x, Func<M, X, A, ValueTask<A>> f)
SwapAff <RT, X> (X x, Func<M, X, A, Aff<RT, A>> f)
Swap <X, Y> (X x, Y y, Func<M, X, Y, A, A> f)
SwapEff <X, Y> (X x, Y y, Func<M, X, Y, A, Eff<A>> f)
SwapEff <RT, X, Y> (X x, Y y, Func<M, X, Y, A, Eff<RT, A>> f)
SwapAsync <X, Y> (X x, Y y, Func<M, X, Y, A, ValueTask<A>> f)
SwapAff <X, Y> (X x, Y y, Func<M, X, Y, A, Aff<A>> f)
SwapAff <X, Y> (X x, Y y, Func<M, X, Y, A, ValueTask<A>> f)
SwapAff <RT, X, Y> (X x, Y y, Func<M, X, Y, A, Aff<RT, A>> f)
Value
ToString ()

AtomChangedEvent <in A>

class Atom <A> Source #

Atoms provide a way to manage shared, synchronous, independent state without locks.

The intended use of atom is to hold an immutable data structure. You change the value by applying a function to the old value. This is done in an atomic manner by Swap.

Internally, Swap reads the current value, applies the function to it, and attempts to CompareExchange it in. Since another thread may have changed the value in the intervening time, it may have to retry, and does so in a spin loop.

The net effect is that the value will always be the result of the application of the supplied function to a current value, atomically. However, because the function might be called multiple times, it must be free of side effects.

Atoms are an efficient way to represent some state that will never need to be coordinated with any other, and for which you wish to make synchronous changes.

See the concurrency section of the wiki for more info.

Properties

property A Value Source #

Current state

Methods

method Option<A> Swap (Func<A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff (Func<A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT> (Func<A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync (Func<A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff (Func<A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff (Func<A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT> (Func<A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Option<A> Swap <X> (X x, Func<X, A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff <X> (X x, Func<X, A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT, X> (X x, Func<X, A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync <X> (X x, Func<X, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff <X> (X x, Func<X, A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff <X> (X x, Func<X, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT, X> (X x, Func<X, A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Option<A> Swap <X, Y> (X x, Y y, Func<X, Y, A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff <X, Y> (X x, Y y, Func<X, Y, A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT, X, Y> (X x, Y y, Func<X, Y, A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync <X, Y> (X x, Y y, Func<X, Y, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff <X, Y> (X x, Y y, Func<X, Y, A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff <X, Y> (X x, Y y, Func<X, Y, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT, X, Y> (X x, Y y, Func<X, Y, A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method string ToString () Source #

class Atom <M, A> Source #

Atoms provide a way to manage shared, synchronous, independent state without locks.

The intended use of atom is to hold an immutable data structure. You change the value by applying a function to the old value. This is done in an atomic manner by Swap.

Internally, Swap reads the current value, applies the function to it, and attempts to CompareExchange it in. Since another thread may have changed the value in the intervening time, it may have to retry, and does so in a spin loop.

The net effect is that the value will always be the result of the application of the supplied function to a current value, atomically. However, because the function might be called multiple times, it must be free of side effects.

Atoms are an efficient way to represent some state that will never need to be coordinated with any other, and for which you wish to make synchronous changes.

See the concurrency section of the wiki for more info.

Properties

property A Value Source #

Current state

Methods

method Option<A> Swap (Func<M, A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff (Func<M, A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT> (Func<M, A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync (Func<M, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff (Func<M, A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff (Func<M, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT> (Func<M, A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Option<A> Swap <X> (X x, Func<M, X, A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff <X> (X x, Func<M, X, A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT, X> (X x, Func<M, X, A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync <X> (X x, Func<M, X, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff <X> (X x, Func<M, X, A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff <X> (X x, Func<M, X, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT, X> (X x, Func<M, X, A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Option<A> Swap <X, Y> (X x, Y y, Func<M, X, Y, A, A> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Eff<A> SwapEff <X, Y> (X x, Y y, Func<M, X, Y, A, Eff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Eff<RT, A> SwapEff <RT, X, Y> (X x, Y y, Func<M, X, Y, A, Eff<RT, A>> f) Source #

where RT : struct

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Eff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method ValueTask<Option<A>> SwapAsync <X, Y> (X x, Y y, Func<M, X, Y, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Option in a Some state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. None otherwise

method Aff<A> SwapAff <X, Y> (X x, Y y, Func<M, X, Y, A, Aff<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<A> SwapAff <X, Y> (X x, Y y, Func<M, X, Y, A, ValueTask<A>> f) Source #

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method Aff<RT, A> SwapAff <RT, X, Y> (X x, Y y, Func<M, X, Y, A, Aff<RT, A>> f) Source #

where RT : struct, HasCancel<RT>

Atomically updates the value by passing the old value to f and updating the atom with the result. Note: f may be called multiple times, so it should be free of side-effects.

Parameters

param	x	Additional value to pass to `f`
param	y	Additional value to pass to `f`
param	f	Function to update the atom
returns	Aff in a Succ state, with the result of the invocation of `f`, if the swap succeeded and its validation passed. Failure state otherwise

method string ToString () Source #

delegate AtomChangedEvent <in A> Source #

Announces Atom change events

See the concurrency section of the wiki for more info.