mcs/class/referencesource/mscorlib/system/threading/asynclocal.cs

   1 // ==++==
   2 //
   3 //   Copyright (c) Microsoft Corporation.  All rights reserved.
   4 //
   5 // <OWNER>Microsoft</OWNER>
   6
   7 using System;
   8 using System.Collections.Generic;
   9 using System.Diagnostics.Contracts;
  10 using System.Security;
  11
  12 namespace System.Threading
  13 {
  14     //
  15     // AsyncLocal<T> represents "ambient" data that is local to a given asynchronous control flow, such as an
  16     // async method.  For example, say you want to associate a culture with a given async flow:
  17     //
  18     // static AsyncLocal<Culture> s_currentCulture = new AsyncLocal<Culture>();
  19     //
  20     // static async Task SomeOperationAsync(Culture culture)
  21     // {
  22     //    s_currentCulture.Value = culture;
  23     //
  24     //    await FooAsync();
  25     // }
  26     //
  27     // static async Task FooAsync()
  28     // {
  29     //    PrintStringWithCulture(s_currentCulture.Value);
  30     // }
  31     //
  32     // AsyncLocal<T> also provides optional notifications when the value associated with the current thread
  33     // changes, either because it was explicitly changed by setting the Value property, or implicitly changed
  34     // when the thread encountered an "await" or other context transition.  For example, we might want our
  35     // current culture to be communicated to the OS as well:
  36     //
  37     // static AsyncLocal<Culture> s_currentCulture = new AsyncLocal<Culture>(
  38     //   args =>
  39     //   {
  40     //      NativeMethods.SetThreadCulture(args.CurrentValue.LCID);
  41     //   });
  42     //
  43     public sealed class AsyncLocal<T> : IAsyncLocal
  44     {
  45         [SecurityCritical] // critical because this action will terminate the process if it throws.
  46         private readonly Action<AsyncLocalValueChangedArgs<T>> m_valueChangedHandler;
  47
  48         //
  49         // Constructs an AsyncLocal<T> that does not receive change notifications.
  50         //
  51         public AsyncLocal()
  52         {
  53         }
  54
  55         //
  56         // Constructs an AsyncLocal<T> with a delegate that is called whenever the current value changes
  57         // on any thread.
  58         //
  59         [SecurityCritical]
  60         public AsyncLocal(Action<AsyncLocalValueChangedArgs<T>> valueChangedHandler)
  61         {
  62             m_valueChangedHandler = valueChangedHandler;
  63         }
  64
  65         public T Value
  66         {
  67             [SecuritySafeCritical]
  68             get
  69             {
  70                 object obj = ExecutionContext.GetLocalValue(this);
  71                 return (obj == null) ? default(T) : (T)obj;
  72             }
  73             [SecuritySafeCritical]
  74             set
  75             {
  76                 ExecutionContext.SetLocalValue(this, value, m_valueChangedHandler != null);
  77             }
  78         }
  79
  80         [SecurityCritical]
  81         void IAsyncLocal.OnValueChanged(object previousValueObj, object currentValueObj, bool contextChanged)
  82         {
  83             Contract.Assert(m_valueChangedHandler != null);
  84             T previousValue = previousValueObj == null ? default(T) : (T)previousValueObj;
  85             T currentValue = currentValueObj == null ? default(T) : (T)currentValueObj;
  86             m_valueChangedHandler(new AsyncLocalValueChangedArgs<T>(previousValue, currentValue, contextChanged));
  87         }
  88     }
  89
  90     //
  91     // Interface to allow non-generic code in ExecutionContext to call into the generic AsyncLocal<T> type.
  92     //
  93     internal interface IAsyncLocal
  94     {
  95         [SecurityCritical]
  96         void OnValueChanged(object previousValue, object currentValue, bool contextChanged);
  97     }
  98
  99     public struct AsyncLocalValueChangedArgs<T>
 100     {
 101         public T PreviousValue { get; private set; }
 102         public T CurrentValue { get; private set; }
 103
 104         //
 105         // If the value changed because we changed to a different ExecutionContext, this is true.  If it changed
 106         // because someone set the Value property, this is false.
 107         //
 108         public bool ThreadContextChanged { get; private set; }
 109
 110         internal AsyncLocalValueChangedArgs(T previousValue, T currentValue, bool contextChanged)
 111             : this()
 112         {
 113             PreviousValue = previousValue;
 114             CurrentValue = currentValue;
 115             ThreadContextChanged = contextChanged;
 116         }
 117     }
 118 }