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)
Swap (Func<A, Option<A>> f)
SwapIO (Func<A, A> f)
SwapIO (Func<A, Option<A>> f)
ValueIO
Value
ToString ()

Atom <M, A>

Swap (Func<M, A, A> f)
Swap (Func<M, A, Option<A>> f)
SwapIO (Func<M, A, A> f)
SwapIO (Func<M, A, Option<A>> f)
ValueIO
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 IO<A> ValueIO Source #

Value accessor (read and write)

Gets will return a freshly constructed IO monad that can be repeatedly evaluated to get the latest state of the Atom.
Sets pass an IO monad that will be mapped to an operation that will set the value of the Atom each time it's evaluated.

property A Value Source #

Current state

Methods

method 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	If the swap operation succeeded then a snapshot of the value that was set is returned. If the swap operation fails (which can only happen due to its validator returning false), then a snapshot of the current value within the Atom is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method A Swap (Func<A, Option<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	If `f` returns `None` then no update occurs and the result of the call to `Swap` will be the latest (unchanged) value of `A`. If the swap operation fails, due to its validator returning false, then a snapshot of the current value within the Atom is returned. If the swap operation succeeded then a snapshot of the value that was set is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method IO<A> SwapIO (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	If the swap operation succeeded then a snapshot of the value that was set is returned. If the swap operation fails (which can only happen due to its validator returning false), then a snapshot of the current value within the Atom is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method IO<A> SwapIO (Func<A, Option<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	If `f` returns `None` then no update occurs and the result of the call to `Swap` will be the latest (unchanged) value of `A`. If the swap operation fails, due to its validator returning false, then a snapshot of the current value within the Atom is returned. If the swap operation succeeded then a snapshot of the value that was set is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

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 IO<A> ValueIO Source #

Value accessor (read and write)

Gets will return a freshly constructed IO monad that can be repeatedly evaluated to get the latest state of the Atom.
Sets pass an IO monad that will be mapped to an operation that will set the value of the Atom each time it's evaluated.

property A Value Source #

Current state

Methods

method 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	If the swap operation succeeded then a snapshot of the value that was set is returned. If the swap operation fails (which can only happen due to its validator returning false), then a snapshot of the current value within the Atom is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method A Swap (Func<M, A, Option<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	If `f` returns `None` then no update occurs and the result of the call to `Swap` will be the latest (unchanged) value of `A`. If the swap operation fails, due to its validator returning false, then a snapshot of the current value within the Atom is returned. If the swap operation succeeded then a snapshot of the value that was set is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method IO<A> SwapIO (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	x	Additional value to pass to `f`
param	f	Function to update the atom
returns	If the swap operation succeeded then a snapshot of the value that was set is returned. If the swap operation fails (which can only happen due to its validator returning false), then a snapshot of the current value within the Atom is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method IO<A> SwapIO (Func<M, A, Option<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	If `f` returns `None` then no update occurs and the result of the call to `Swap` will be the latest (unchanged) value of `A`. If the swap operation fails, due to its validator returning false, then a snapshot of the current value within the Atom is returned. If the swap operation succeeded then a snapshot of the value that was set is returned. If there is no validator for the Atom then the return value is always the snapshot of the successful `f` function.

method string ToString () Source #

delegate AtomChangedEvent <in A> Source #

Announces Atom change events

See the concurrency section of the wiki for more info.