Struct Atomic<T>

Provides atomic access to non-primitive data type.

Implements

ICloneable

IResettable

IStrongBox

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: DotNext.Threading

Assembly: DotNext.dll

Syntax

public struct Atomic<T> : ICloneable, IResettable, IStrongBox where T : struct

Type Parameters

Name	Description
T	The type of the value to be accessible in atomic manner.

Remarks

Synchronized methods can be declared in classes only. If you don't need to have extra heap allocation to keep synchronization root in the form of the object, or you need to have volatile field inside of value type then Atomic<T> is the best choice. Its performance is better than synchronized methods according to benchmarks. This type provides no contention for read path.

Properties

IsWriteLockHeld

Gets a value indicating that the value of the container is writing.

Declaration

public readonly bool IsWriteLockHeld { get; }

Property Value

Type	Description
bool

Value

Gets or sets value atomically.

Declaration

public T Value { readonly get; set; }

Property Value

Type	Description
T

Remarks

To achieve the best performance it is recommended to use Read(out T) and Write(in T) methods because they don't cause extra allocation of stack memory for passing value.

Methods

AccumulateAndGet(in T, Accumulator, out T)

Atomically updates the stored value with the results of applying the given function to the current and given values, returning the original value.

Declaration

public void AccumulateAndGet(in T x, Atomic<T>.Accumulator accumulator, out T result)

Parameters

Type	Name	Description
T	x	Accumulator operand.
Atomic<T>.Accumulator	accumulator	A side-effect-free function of two arguments.
T	result	The updated value.

Remarks

The function is applied with the current value as its first argument, and the given update as the second argument.

Exceptions

Type	Condition
ArgumentNullException	accumulator is null.

Clear()

Sets the default value.

Declaration

public void Clear()

Clear(out T)

Sets the default value and returns the previous value.

Declaration

public void Clear(out T previousValue)

Parameters

Type	Name	Description
T	previousValue	The previous value.

Clone()

Clones this container atomically.

Declaration

public readonly Atomic<T> Clone()

Returns

Type	Description
Atomic<T>	The cloned container.

CompareAndSet(delegate*<in T, in T, bool>, in T, in T)

Atomically sets the stored value to the given updated value if the current value == the expected value.

Declaration

[CLSCompliant(false)]
public bool CompareAndSet(delegate*<in T, in T, bool> comparer, in T expected, in T update)

Parameters

Type	Name	Description
delegate*<in T, in T, bool>	comparer	The function representing comparison logic.
T	expected	The expected value.
T	update	The new value.

Returns

Type	Description
bool	true if successful. false return indicates that the actual value was not equal to the expected value.

CompareAndSet(Func<T, T, bool>, in T, in T)

Atomically sets the stored value to the given updated value if the current value == the expected value.

Declaration

public bool CompareAndSet(Func<T, T, bool> comparer, in T expected, in T update)

Parameters

Type	Name	Description
Func<T, T, bool>	comparer	The function representing comparison logic.
T	expected	The expected value.
T	update	The new value.

Returns

Type	Description
bool	true if successful. false return indicates that the actual value was not equal to the expected value.

CompareAndSet(in T, in T)

Atomically sets the stored value to the given updated value if the current value == the expected value.

Declaration

public bool CompareAndSet(in T expected, in T update)

Parameters

Type	Name	Description
T	expected	The expected value.
T	update	The new value.

Returns

Type	Description
bool	true if successful. false return indicates that the actual value was not equal to the expected value.

CompareExchange(delegate*<in T, in T, bool>, in T, in T, out T)

Compares two values of type T for equality and, if they are equal, replaces the stored value.

Declaration

[CLSCompliant(false)]
public bool CompareExchange(delegate*<in T, in T, bool> comparer, in T update, in T expected, out T result)

Parameters

Type	Name	Description
delegate*<in T, in T, bool>	comparer	The function representing comparison logic.
T	update	The value that replaces the stored value if the comparison results in equality.
T	expected	The value that is compared to the stored value.
T	result	The origin value stored in this container before modification.

Returns

Type	Description
bool	true if the current value is replaced by update; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	comparer is null.

CompareExchange(Func<T, T, bool>, in T, in T, out T)

Compares two values of type T for equality and, if they are equal, replaces the stored value.

Declaration

public bool CompareExchange(Func<T, T, bool> comparer, in T update, in T expected, out T result)

Parameters

Type	Name	Description
Func<T, T, bool>	comparer	The function representing comparison logic.
T	update	The value that replaces the stored value if the comparison results in equality.
T	expected	The value that is compared to the stored value.
T	result	The origin value stored in this container before modification.

Returns

Type	Description
bool	true if the current value is replaced by update; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	comparer is null.

CompareExchange(in T, in T, out T)

Compares two values of type T for bitwise equality and, if they are equal, replaces the stored value.

Declaration

public bool CompareExchange(in T update, in T expected, out T result)

Parameters

Type	Name	Description
T	update	The value that replaces the stored value if the comparison results in equality.
T	expected	The value that is compared to the stored value.
T	result	The origin value stored in this container before modification.

Returns

Type	Description
bool	true if the current value is replaced by update; otherwise, false.

EnterLock()

Enters write lock.

Declaration

[UnscopedRef]
public Atomic<T>.WriteLockScope EnterLock()

Returns

Type	Description
Atomic<T>.WriteLockScope	The scope of the write lock.

Exchange(in T, out T)

Sets a value stored in this container to a specified value and returns the original value, as an atomic operation.

Declaration

public void Exchange(in T update, out T previous)

Parameters

Type	Name	Description
T	update	The value that replaces the stored value.
T	previous	The original stored value before modification.

GetAndAccumulate(in T, Accumulator, out T)

Atomically updates the stored value with the results of applying the given function to the current and given values, returning the updated value.

Declaration

public void GetAndAccumulate(in T x, Atomic<T>.Accumulator accumulator, out T result)

Parameters

Type	Name	Description
T	x	Accumulator operand.
Atomic<T>.Accumulator	accumulator	A side-effect-free function of two arguments.
T	result	The original value.

Remarks

The function is applied with the current value as its first argument, and the given update as the second argument.

Exceptions

Type	Condition
ArgumentNullException	accumulator is null.

GetAndUpdate(Updater, out T)

Atomically updates the stored value with the results of applying the given function, returning the original value.

Declaration

public void GetAndUpdate(Atomic<T>.Updater updater, out T result)

Parameters

Type	Name	Description
Atomic<T>.Updater	updater	A side-effect-free function.
T	result	The original value.

Exceptions

Type	Condition
ArgumentNullException	updater is null.

Read(out T)

Performs atomic read.

Declaration

public readonly void Read(out T result)

Parameters

Type	Name	Description
T	result	The result of atomic read.

Remarks

The read is optimistic: it doesn't block concurrent readers or writers, but retries if a concurrent write happens during the copy of the value.

Swap(ref Atomic<T>)

Swaps the value stored in this container and the given value atomically.

Declaration

public void Swap(ref Atomic<T> other)

Parameters

Type	Name	Description
Atomic<T>	other	The container for the value.

Remarks

This operation is atomic for both containers.

Swap(ref T)

Swaps the value stored in this container and the given value atomically.

Declaration

public void Swap(ref T other)

Parameters

Type	Name	Description
T	other	The managed pointer to the value to swap.

ToString()

Declaration

public override readonly string? ToString()

Returns

Type	Description
string

Overrides

ValueType.ToString()

TryUpdate(delegate*<in T, in T, bool>, in T, in T)

Tries to switch the current value with the supplied one.

Declaration

[CLSCompliant(false)]
public bool TryUpdate(delegate*<in T, in T, bool> comparer, in T comparisonValue, in T newValue)

Parameters

Type	Name	Description
delegate*<in T, in T, bool>	comparer	The function representing comparison logic.
T	comparisonValue	The value to be compared with the currently stored value.
T	newValue	A new value to be placed to the container.

Returns

Type	Description
bool	true if newValue is placed to this container successfully; false if this container is concurrently writing the value, or the current value is to equal to comparisonValue.

Remarks

This method doesn't introduce contention in contrast to CompareAndSet(Func<T, T, bool>, in T, in T) method, which means that it can fail if the current contain is in writing state concurrently with the caller thread. In this case, comparer is not called.

Exceptions

Type	Condition
ArgumentNullException	comparer is null.

TryUpdate(Func<T, T, bool>, in T, in T)

Tries to switch the current value with the supplied one.

Declaration

public bool TryUpdate(Func<T, T, bool> comparer, in T comparisonValue, in T newValue)

Parameters

Type	Name	Description
Func<T, T, bool>	comparer	The function representing comparison logic.
T	comparisonValue	The value to be compared with the currently stored value.
T	newValue	A new value to be placed to the container.

Returns

Type	Description
bool	true if newValue is placed to this container successfully; false if this container is concurrently writing the value, or the current value is to equal to comparisonValue.

Remarks

This method doesn't introduce contention in contrast to CompareAndSet(Func<T, T, bool>, in T, in T) method, which means that it can fail if the current contain is in writing state concurrently with the caller thread. In this case, comparer is not called.

Exceptions

Type	Condition
ArgumentNullException	comparer is null.

TryUpdate(in T, in T)

Tries to switch the current value with the supplied one.

Declaration

public bool TryUpdate(in T comparisonValue, in T newValue)

Parameters

Type	Name	Description
T	comparisonValue	The value to be compared with the currently stored value.
T	newValue	A new value to be placed to the container.

Returns

Type	Description
bool	true if newValue is placed to this container successfully; false if this container is concurrently writing the value, or the current value is to equal to comparisonValue.

Remarks

This method doesn't introduce contention in contrast to CompareAndSet(in T, in T) method, which means that it can fail if the current contain is in writing state concurrently with the caller thread.

UpdateAndGet(Updater, out T)

Atomically updates the stored value with the results of applying the given function, returning the updated value.

Declaration

public void UpdateAndGet(Atomic<T>.Updater updater, out T result)

Parameters

Type	Name	Description
Atomic<T>.Updater	updater	A side-effect-free function.
T	result	The updated value.

Exceptions

Type	Condition
ArgumentNullException	updater is null.

Write(in T)

Performs atomic write.

Declaration

public void Write(in T newValue)

Parameters

Type	Name	Description
T	newValue	The value to be stored into this container.

Implements

ICloneable

IResettable

IStrongBox

Extension Methods

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, params ReadOnlySpan<T>)

Enumerator.Skip<TEnumerator, T>(ref TEnumerator, int)