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)
- 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)
- 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)
- 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)
- 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)
- 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)
- Value
- ToString ()
- AtomChangedEvent <in A>
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.
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 | |
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 |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
method Eff<RT, A> SwapEff <RT> (Func<A, Eff<RT, 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 | |
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 | |
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 |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
method Eff<RT, A> SwapEff <RT, X> (X x, Func<X, A, Eff<RT, 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 |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
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 |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
method Eff<RT, A> SwapEff <RT, X, Y> (X x, Y y, Func<X, Y, A, Eff<RT, 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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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.
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 | |
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 | |
method Eff<RT, A> SwapEff <RT> (Func<M, A, Eff<RT, 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 | |
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 | |
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 |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
method Eff<RT, A> SwapEff <RT, X> (X x, Func<M, X, A, Eff<RT, 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 |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
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 |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
method Eff<RT, A> SwapEff <RT, X, Y> (X x, Y y, Func<M, X, Y, A, Eff<RT, 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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Eff in a Succ state, with the result of the invocation of | |
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 |
| param | y | Additional value to pass to |
| param | f | Function to update the atom |
| returns | Option in a Some state, with the result of the invocation of | |
delegate AtomChangedEvent <in A> Source #
Announces Atom change events
See the concurrency section of the wiki for more info.