Interlocked.txt

----------
20191115

public static double CompareExchange (ref double location1, double value, double comparand);
/// 若 (location1 位址的值) 與 Comparand 相同, 則以 NewValue 存入該位址(提供給各執行緒使用最新值), 否則不變.
/// 回傳值為呼叫本函數前的(location1 位址的值). 
/// (location1 位址的值) 在多執行緒中, 隨時可能被其他的執行緒變更.

CompareExchange()系列函數, 翻譯為白話文為:
若 最新(location1 位址的值) 等於 (本執行緒的 comparand 值), 
則以 (本執行緒的 value 值), 更新到(位址location1),
否則不變
回傳值為原值, 即呼叫本函數前的(location1 位址的值).

public static double CompareExchange (ref double location1, double value, double comparand);
Compares two double-precision floating point numbers for equality and, if they are equal, replaces the first value.
若(location1 相等 comparand),
 則(設定 location1 = value),
 否則(不變)
回傳值為(原值於location1). 即(呼叫前的 location1 值), 除非(有其他的執行緒或本執行緒更新了 location1 的值), 否則等於原值.





Examples
The following code example demonstrates a thread-safe method that accumulates a running total of Double values. Two threads add a series of Double values using the thread-safe method and ordinary addition, and when the threads complete the totals are compared. On a dual-processor computer, there is a significant difference in the totals.
以下範例示範 thread-safe 方法計算總合. 2個執行緒分別加入數值後取得總和. 若在雙處理器電腦上計算, 將會有極大的差異.

In the thread-safe method, the initial value of the running total is saved, and then the CompareExchange method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated.
在 thread-safe 方法中, 會先將初始值保存下來, 然後經由 CompareExchange() 交換新舊的總和值.
若 (回傳值 不等於 計算中的總數), 則表示其他的執行緒已經 (更新了最新總數), 因此必須重複更新總數一次.



20191115: 

以下範例, 很好用, 可多參考用於 ThreadSafe 樣板: 
https://docs.microsoft.com/en-us/dotnet/api/system.threading.interlocked.compareexchange?view=netframework-4.8#System_Threading_Interlocked_CompareExchange_System_Int32__System_Int32_System_Int32_

// This example demonstrates a thread-safe method that adds to a
// running total.  
using System;
using System.Threading;

public class ThreadSafe
{
    // Field totalValue contains a running total that can be updated
    // by multiple threads. It must be protected from unsynchronized 
    // access.
	// 多執行緒的計算結果
    private double totalValue = 0.0;

    // The Total property returns the running total.
    public double Total { get { return totalValue; }}

    // AddToTotal safely adds a value to the running total.
    public double AddToTotal(double addend)
    {
        double initialValue, computedValue;
        do
        {
            // Save the current running total in a local variable.
			// 保存(多執行緒的計算總和 totalValue)到 (本執行緒初始值 initialValue)
            initialValue = totalValue;

            // Add the new value to the running total.
			// 本執行緒的計算總和 computedValue.
            computedValue = initialValue + addend;

            // CompareExchange compares totalValue to initialValue. If
            // they are not equal, then another thread has updated the
            // running total since this loop started. CompareExchange
            // does not update totalValue. CompareExchange returns the
            // contents of totalValue, which do not equal initialValue,
            // so the loop executes again.
			// 若(多執行緒計算總和 totalValue) 與 (本執行緒初始值 initialValue) 相等, 
			// 則表示沒有其他執行緒變動過 (多執行緒計算總和 totalValue), 
			//   因此可以(本執行緒的計算總和 computedValue) 存入 (多執行緒計算總和 totalValue).
			// 否則 不變
			// 回傳值:
			// 
        }
        while (initialValue != Interlocked.CompareExchange(ref totalValue, computedValue, initialValue));  
		// 以上迴圈
		// 若沒有其他的執行緒更新總數的話, 
		// 則 (initialValue 等於 totalValue), 
		//   因此可(以本執行緒的computedValue更新計算結果), 
		//   且回傳值為(還沒有更新前的totalValue, 也就是initialValue)
		//   且結束迴圈.
        // If no other thread updated the running total, then 
        // totalValue and initialValue are equal when CompareExchange
        // compares them, and computedValue is stored in totalValue.
        // CompareExchange returns the value that was in totalValue
        // before the update, which is equal to initialValue, so the 
        // loop ends.

        // The function returns computedValue, not totalValue, because
        // totalValue could be changed by another thread between
        // the time the loop ends and the function returns.
        return computedValue;
    }
}

public class Test
{
    // Create an instance of the ThreadSafe class to test.
    private static ThreadSafe ts = new ThreadSafe();
    private static double control;

    private static Random r = new Random();
    private static ManualResetEvent mre = new ManualResetEvent(false);

    public static void Main()
    {
        // Create two threads, name them, and start them. The
        // thread will block on mre.
        Thread t1 = new Thread(TestThread);
        t1.Name = "Thread 1";
        t1.Start();
        Thread t2 = new Thread(TestThread);
        t2.Name = "Thread 2";
        t2.Start();

        // Now let the threads begin adding random numbers to 
        // the total.
        mre.Set();
        
        // Wait until all the threads are done.
        t1.Join();
        t2.Join();

        Console.WriteLine("Thread safe: {0}  Ordinary Double: {1}", 
            ts.Total, control);
    }

    private static void TestThread()
    {
        // Wait until the signal.
        mre.WaitOne();

        for(int i = 1; i <= 1000000; i++)
        {
            // Add to the running total in the ThreadSafe instance, and
            // to an ordinary double.
            //
            double testValue = r.NextDouble();
            control += testValue;
            ts.AddToTotal(testValue);
        }
    }
}

/* On a dual-processor computer, this code example produces output 
   similar to the following:

Thread safe: 998068.049623744  Ordinary Double: 759775.417190589
 */
 
 
Remarks
If comparand and the value in location1 are equal, then value is stored in location1. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of CompareExchange is the original value in location1, whether or not the exchange takes place.

 

----------
20191112

https://docs.microsoft.com/en-us/dotnet/api/system.threading.interlocked.increment?redirectedfrom=MSDN&view=netframework-4.8#overloads

Interlocket.Increment(Int32)
Interlocket.Increment(Int64)
可 ThreadSafe 的遞增特定變數作業, 並且當溢位時, 會自動歸零(Int32.MinValue 或 Int64.MinValue), 不會 exception.

Increments a specified variable and stores the result, as an atomic operation.
遞增特定變數並將結果儲存起來，成為不可部分完成的作業。

Remarks
This method handles an overflow condition by wrapping: if location = Int32.MaxValue, location + 1 = Int32.MinValue. No exception is thrown.
這個方法會藉由包裝來處理溢位location條件location ： if = Int32.MaxValue、 Int32.MinValue+ 1 =。 不會有例外狀況擲回。



Examples
The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, midpointCount, is set equal to 0 and incremented each time the random number generator returns a midpoint value until it reaches 10,000. Because three threads generate the random numbers, the Increment(Int32) method is called to ensure that multiple threads don't update midpointCount concurrently. Note that a lock is also used to protect the random number generator, and that a CountdownEvent object is used to ensure that the Main method doesn't finish execution before the three threads.

using System;
using System.Threading;

public class Example
{
   const int LOWERBOUND = 0;
   const int UPPERBOUND = 1001;
   
   static Object lockObj = new Object();
   static Random rnd = new Random();
   static CountdownEvent cte;
   
   static int totalCount = 0;
   static int totalMidpoint = 0;
   static int midpointCount = 0;

   public static void Main()
   {
      cte = new CountdownEvent(1); // -----> 參考 CountdownEvent.txt
      // Start three threads. 
      for (int ctr = 0; ctr <= 2; ctr++) {
         cte.AddCount();
         Thread th = new Thread(GenerateNumbers);
         th.Name = "Thread" + ctr.ToString();
         th.Start();
      }
      cte.Signal();
      cte.Wait();
      Console.WriteLine();
      Console.WriteLine("Total midpoint values:  {0,10:N0} ({1:P3})",
                        totalMidpoint, totalMidpoint/((double)totalCount));
      Console.WriteLine("Total number of values: {0,10:N0}", 
                        totalCount);                  
   }

   private static void GenerateNumbers()
   {
      int midpoint = (UPPERBOUND - LOWERBOUND) / 2;
      int value = 0;
      int total = 0;
      int midpt = 0;
      
      do {
         lock (lockObj) {
            value = rnd.Next(LOWERBOUND, UPPERBOUND);
         }
         if (value == midpoint) { 
            Interlocked.Increment(ref midpointCount);
            midpt++;
         }
         total++;    
      } while (midpointCount < 10000);
      
      Interlocked.Add(ref totalCount, total);
      Interlocked.Add(ref totalMidpoint, midpt);
      
      string s = String.Format("Thread {0}:\n", Thread.CurrentThread.Name) +
                 String.Format("   Random Numbers: {0:N0}\n", total) + 
                 String.Format("   Midpoint values: {0:N0} ({1:P3})", midpt, 
                               ((double) midpt)/total);
      Console.WriteLine(s);
      cte.Signal();
   }
}
// The example displays output like the following:
//       Thread Thread2:
//          Random Numbers: 2,776,674
//          Midpoint values: 2,773 (0.100 %)
//       Thread Thread1:
//          Random Numbers: 4,876,100
//          Midpoint values: 4,873 (0.100 %)
//       Thread Thread0:
//          Random Numbers: 2,312,310
//          Midpoint values: 2,354 (0.102 %)
//       
//       Total midpoint values:      10,000 (0.100 %)
//       Total number of values:  9,965,084


The following example is similar to the previous one, except that it uses the Task class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the GenerateNumbers thread procedure, and the call to the Task.WaitAll method eliminates the need for the CountdownEvent object.
以下範例同上, 改用 Task 替代 Thread, 並利用 lambda 運算式 取代 GenerateNumbers thread 程序, 透過 Task.WaitAll 方法移除 CountdownEvent 物件.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   const int LOWERBOUND = 0;
   const int UPPERBOUND = 1001;
   
   static Object lockObj = new Object();
   static Random rnd = new Random();
   
   static int totalCount = 0;
   static int totalMidpoint = 0;
   static int midpointCount = 0;

   public static void Main()
   {
      List<Task> tasks = new List<Task>();
      // Start three tasks. 
      for (int ctr = 0; ctr <= 2; ctr++) 
         tasks.Add(Task.Run( () => { int midpoint = (UPPERBOUND - LOWERBOUND) / 2;
                                     int value = 0;
                                     int total = 0;
                                     int midpt = 0;
                                    
                                     do {
                                        lock (lockObj) {
                                           value = rnd.Next(LOWERBOUND, UPPERBOUND);
                                        }
                                        if (value == midpoint) { 
                                           Interlocked.Increment(ref midpointCount);
                                           midpt++;
                                        }
                                        total++;    
                                     } while (midpointCount < 50000);
                                    
                                     Interlocked.Add(ref totalCount, total);
                                     Interlocked.Add(ref totalMidpoint, midpt);
                                    
                                     string s = String.Format("Task {0}:\n", Task.CurrentId) +
                                                String.Format("   Random Numbers: {0:N0}\n", total) + 
                                                String.Format("   Midpoint values: {0:N0} ({1:P3})", midpt, 
                                                              ((double) midpt)/total);
                                     Console.WriteLine(s); } ));
      
      Task.WaitAll(tasks.ToArray());
      Console.WriteLine();
      Console.WriteLine("Total midpoint values:  {0,10:N0} ({1:P3})",
                        totalMidpoint, totalMidpoint/((double)totalCount));
      Console.WriteLine("Total number of values: {0,10:N0}", 
                        totalCount);                  
   }
}
// The example displays output like the following:
//       Task 3:
//          Random Numbers: 10,855,250
//          Midpoint values: 10,823 (0.100 %)
//       Task 1:
//          Random Numbers: 15,243,703
//          Midpoint values: 15,110 (0.099 %)
//       Task 2:
//          Random Numbers: 24,107,425
//          Midpoint values: 24,067 (0.100 %)
//       
//       Total midpoint values:      50,000 (0.100 %)
//       Total number of values: 50,206,378




----------
20191106

https://stackoverflow.com/questions/38722529/in-c-what-does-atomic-mean

Atomic operations are ones that cannot be interrupted partway through, such as by threading. Take for instance the statement
_value++;

If you have two threads executing this code at once with a starting value of 0, you may have the following
  Thread A reads _value, 0
  Thread A adds 1, 1
  Thread B reads _value, 0
  Thread B adds 1, 1
  Thread A assigns to _value, 1
  Thread B assigns to _value, 1

so now, even though we've called an increment twice, the final value in _value is 1, not the expected 2. This is because increment operators are not atomic.

The function Interlocked.Increment, however, is atomic, so replacing the above code with
Interlocked.Increment(ref _value);

Would solve the given race condition.

EDIT: As a point of etymology, "atomic" usually means "indivisible" - the chemistry term we're familiar with is a misnomer held over from the belief that atoms were indivisible, only for later discoveries to break them down further into subatomic, quark, and matter/energy.


----------
Increments a specified variable and stores the result, as an atomic operation

The following code example shows a thread-safe way to increment and decrement an integer value. 
SafeInstanceCount will always be zero. 
However, UnsafeInstanceCount will not necessarily be zero because a race condition occurs between incrementing and decrementing the count. 
This effect is especially marked on a multiprocessor computer.

using System;
using System.Threading;

class Test
{
    static void Main()
    {
        Thread thread1 = new Thread(new ThreadStart(ThreadMethod));
        Thread thread2 = new Thread(new ThreadStart(ThreadMethod));
        thread1.Start();
        thread2.Start();
        thread1.Join();
        thread2.Join();

        // Have the garbage collector run the finalizer for each 
        // instance of CountClass and wait for it to finish.
        GC.Collect();
        GC.WaitForPendingFinalizers();

        Console.WriteLine("UnsafeInstanceCount: {0}" +
            "\nSafeCountInstances: {1}",
            CountClass.UnsafeInstanceCount.ToString(),
            CountClass.SafeInstanceCount.ToString());
    }

    static void ThreadMethod()
    {
        CountClass cClass;

        // Create 100,000 instances of CountClass. 
        for(int i = 0; i < 100000; i++)
        {
            cClass = new CountClass();
        }
    }
}

class CountClass
{
    static int unsafeInstanceCount = 0;
    static int   safeInstanceCount = 0;

    static public int UnsafeInstanceCount
    {
        get {return unsafeInstanceCount;}
    }

    static public int SafeInstanceCount
    {
        get {return safeInstanceCount;}
    }

    public CountClass()
    {
        unsafeInstanceCount++;
        Interlocked.Increment(ref safeInstanceCount);
    }

    ~CountClass()
    {
        unsafeInstanceCount--;
        Interlocked.Decrement(ref safeInstanceCount);
    }
}