Skip to content

Commit

Permalink
Improve documentation for InterlockedOps
Browse files Browse the repository at this point in the history
Revised descriptions of the `InterlockedOps` class and its methods (`Xor`, `ClearBits`, `SetBits`) to enhance readability and highlight differences in return values. Clarified the section on conditional update operations, emphasizing predicate delegates and race condition handling. Mentioned additional overloads for condition operations to avoid closures.
  • Loading branch information
kzdev-net committed Oct 25, 2024
1 parent ce0f6e0 commit 8756dd1
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions Source/Docs/articles/interlockedops.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Interlocked Operations

The `Interlocked` class provides atomic operations for variables that are shared between threads. These operations are guaranteed to be atomic, which means that they are thread-safe and can be used in a multithreaded environment without the need for locks.
The `Interlocked` class provides atomic operations for variables that are shared between threads. These operations are guaranteed atomic, meaning they are thread-safe and can be used in a multithreaded environment without locking.

The [`InterlockedOps`](xref:KZDev.PerfUtils.InterlockedOps) class provides a set of static helper methods that provide additional functionality that is not currently available in the `Interlocked` class.

All of the operations provided by the `InterlockedOps` class are convenience methods that can be implemented directly in code using the existing `Interlocked` class. However, the `InterlockedOps` class provides a more readable, concise, and consistent way to perform the provided operations than repeatedly copying and pasting code. This can make the code easier to understand and maintain by reducing code duplication.
All the operations provided by the `InterlockedOps` class are convenience methods that can be implemented directly in code using the existing `Interlocked` class. However, the `InterlockedOps` class offers a more readable, concise, and consistent way to perform the provided operations than repeatedly copying and pasting code. Reducing code duplication can make the code easier to understand and maintain.

## Variable Exclusive OR Operations

The `InterlockedOps` class provides the [`Xor`](xref:KZDev.PerfUtils.InterlockedOps.Xor*) method, which performs an atomic XOR operation on a variable, storing the operation result in the provided variable and returning the original value of the variable. This method is useful for toggling an integer variable bit value between `1` and `0` in a thread-safe manner.
The `InterlockedOps` class provides the [`Xor`](xref:KZDev.PerfUtils.InterlockedOps.Xor*) method, which performs an atomic XOR operation on a variable, stores the operation result in the provided variable, and returns the variable's original value. This method is useful for toggling an integer variable bit value between `1` and `0` in a thread-safe manner.

The operation can be performed on any integer type, including `int`, `long`, `uint`, and `ulong`.

Expand All @@ -27,21 +27,21 @@ public class XorExample

## Variable ClearBits Operations

The [`ClearBits`](xref:KZDev.PerfUtils.InterlockedOps.ClearBits*) methods are used to clear (set to 0) one or more bits that are currently set (set to 1) in a thread-safe atomic operation. The methods return a value tuple of the original value and new value of the variable at the instant the operation was applied.
The [`ClearBits`](xref:KZDev.PerfUtils.InterlockedOps.ClearBits*) methods are used to clear (set to 0) one or more bits that are currently set (set to 1) in a thread-safe atomic operation. The methods return a value tuple of the original value and a new value of the variable at the instant the operation was applied.

## Variable SetBits Operations

The [`SetBits`](xref:KZDev.PerfUtils.InterlockedOps.SetBits*) methods are simply semantically clearer equivalents of the `Interlocked` [`Or`](xref:System.Threading.Interlocked.Or*). The one difference is that the `SetBits` method returns a value tuple of the original value and new value of the variable at the instant the operation was applied.
The [`SetBits`](xref:KZDev.PerfUtils.InterlockedOps.SetBits*) methods are semantically clearer equivalents of the `Interlocked` [`Or`](xref:System.Threading.Interlocked.Or*). The difference is that the SetBits method returns a value tuple of the original value and a new variable value when the operation is applied.

## Conditional Update Operations

The `InterlockedOps` class provides conditional bitwise update operations for [`And`](xref:KZDev.PerfUtils.InterlockedOps.ConditionAnd*), [`Or`](xref:KZDev.PerfUtils.InterlockedOps.ConditionOr*), [`Xor`](xref:KZDev.PerfUtils.InterlockedOps.ConditionXor*), [`ClearBits`](xref:KZDev.PerfUtils.InterlockedOps.ConditionClearBits*), and [`SetBits`](xref:KZDev.PerfUtils.InterlockedOps.ConditionSetBits*) that allow you to update a variable based on a boolean condition. These methods are useful for implementing lock-free algorithms that require atomic updates to a variable that depend on a dynamic condition and guaranteeing that the operation only occurs if the condition is met in a thread-safe manner.
The `InterlockedOps` class provides conditional bitwise update operations for [`And`](xref:KZDev.PerfUtils.InterlockedOps.ConditionAnd*), [`Or`](xref:KZDev.PerfUtils.InterlockedOps.ConditionOr*), [`Xor`](xref:KZDev.PerfUtils.InterlockedOps.ConditionXor*), [`ClearBits`](xref:KZDev.PerfUtils.InterlockedOps.ConditionClearBits*), and [`SetBits`](xref:KZDev.PerfUtils.InterlockedOps.ConditionSetBits*), allowing you to update a variable based on a boolean condition. These methods help implement lock-free algorithms that require atomic updates to a variable that depends on a dynamic condition and guarantee that the operation only occurs if the condition is met in a thread-safe manner.

The conditional methods are the same as the non-conditional methods except these methods also take a predicate delegate that gets called with the current value of the variable and the predicate determines of the corresponding operation should be applied based on the value of the variable at that instant. If there is a race condition and the value of the variable is changed by another thread, the predicate delegate will be called again with the new variable value and continue until the newly computed value can be applied, or the predicate returns `false`.
The conditional methods are the same as the non-conditional methods, except these methods also take a predicate delegate that gets called with the current value of the variable. The predicate determines whether the corresponding operation should be applied based on the variable's value at that instant. When there is a race condition, and another thread changes the variable's value between the start of the condition delegate call, and applying the operation to the variable, the predicate delegate will be called again with the new variable value and continue until the newly computed value can be applied or the predicate returns `false`.

The conditional methods all return a value type that has the original variable value and the new value at the instant the operation was performed. If the condition predicate returns false, both of the value tuple values will be the same and set to the value of the variable that was passed to the condition predicate that returned false.
The conditional methods all return a value tuple with the original variable value and the new value at the instant the operation was performed. If the condition predicate returns false, both value tuple values will be the same and set to the value of the variable passed to the condition predicate that returned false.

There are also overloads of the condition operations that take a predicate argument to avoid closures when the predicate needs additional values to process the conditional logic.
Also, overloads of the condition operations take a predicate-argument to avoid closures when the predicate needs additional values to process the conditional logic.

```csharp
public class ConditionXorExample
Expand Down

0 comments on commit 8756dd1

Please sign in to comment.