我的CCR之旅（4）：倾听CCR的心跳声--Dispatcher（基础篇）

    PS：前段时间稍微有些累，故暂停了本系列文章，今天状态开始恢复，继续旅程。

    之前几章已经整体把CCR介绍了一下，为了更好地了解和使用CCR，接下来几章我将逐一介绍CCR内重要的几个类，本章要介绍的是CCR的心脏Dispatcher。

    在我们使用Dispatcher的时候，最常用到的就是他的构造函数和资源释放函数了，因此本节，先介绍这2类函数，其他的函数因为涉及到DispatcherQueue等内部的运作机制，属于CCR内部的运作调度机制，留待前面这些基础知识交代完毕后再另起一篇细说。

Dispatcher内含的方法、属性预览

public sealed class Dispatcher : IDisposable
{
    // 1、构造函数
    public Dispatcher();
    public Dispatcher(int threadCount, string threadPoolName);
    public Dispatcher(int threadCount, ThreadPriority priority,
            bool useBackgroundThreads, string threadPoolName);
    public Dispatcher(int threadCount, ThreadPriority priority,
            DispatcherOptions options, string threadPoolName);
    public Dispatcher(int threadCount, ThreadPriority priority,
            DispatcherOptions options,
            ApartmentState threadApartmentState,
            string threadPoolName);

    // 2、资源释放函数
    public void Dispose();

    // 3、属性
    public static ICollection<Causality> ActiveCausalities { get; }
    public List<DispatcherQueue> DispatcherQueues { get; }
    public string Name { get; set; }
    public DispatcherOptions Options { get; set; }
    public int PendingTaskCount { get; set; }
    public long ProcessedTaskCount { get; set; }
    public static int ThreadsPerCpu { get; set; }
    public int WorkerThreadCount { get; set; }

    // 4、因果关系函数
    public static void AddCausality(Causality causality);
    public static void AddCausalityBreak();
    public static void ClearCausalities();
    public static bool RemoveCausality(Causality causality);
    public static bool RemoveCausality(string name);
}

一、构造函数
     Dispatcher给我们提供了5个构造函数，其实是为了方便大家使用而对一个构造函数做的封装，我们看看具体的实现代码（我在关键的地方都加上了中文的注释）：

  1/**//// <summary>
  2/// Constructs a Dispatcher instance using the default number of threads and no friendly tag
  3/// 使用默认线程数和空名作为参数构造一个Dispatcher实例
  4/// </summary>
  5public Dispatcher()
  6    : this(0, null)
  7{
  8}
  9
 10/**//// <summary>
 11/// Constructs a Dispatcher instance. 
 12/// The instance is usable only after AddPort is called at least once
 13/// 该实例仅在调用AddPort之后才生效
 14/// </summary>
 15/// <param name="threadCount">
 16/// Number of OS threads to use for processing CCR Tasks
 17/// 处理CCR任务的操作系统线程数
 18/// </param>
 19/// <param name="threadPoolName">
 20/// Friendly name to use for the OS Threads and this dispatcher instance
 21/// Dispatcher实例和系统线程的名称
 22/// </param>
 23public Dispatcher(int threadCount, string threadPoolName)
 24    : this(threadCount, ThreadPriority.Normal, DispatcherOptions.None, threadPoolName)
 25{
 26}
 27
 28/**//// <summary>
 29/// Constructs a Dispatcher instance. 
 30/// The instance is usable only after AddPort is called at least once
 31/// </summary>
 32/// <param name="threadCount">
 33/// Number of OS threads to use for processing CCR Tasks
 34/// </param>
 35/// <param name="priority">
 36/// OS Thread priority to use for threads exexuting CCR tasks
 37/// 系统线程执行CCR任务所使用的优先级
 38/// </param>
 39/// <param name="options">
 40/// Dispatcher scheduling options
 41/// 调度选项
 42/// </param>
 43/// <param name="threadPoolName">
 44/// Friendly name to use for the OS Threads and this dispatcher instance
 45/// </param>
 46public Dispatcher(int threadCount, ThreadPriority priority, DispatcherOptions options, string threadPoolName)
 47    : this(threadCount, priority, options, ApartmentState.Unknown, threadPoolName)
 48{
 49}
 50
 51/**//// <summary>
 52/// Constructs a Dispatcher instance. 
 53/// The instance is usable only after AddPort is called at least once
 54/// </summary>
 55/// <param name="threadCount">
 56/// Number of OS threads to use for processing CCR Tasks
 57/// </param>
 58/// <param name="priority">
 59/// OS Thread priority to use for threads exexuting CCR tasks
 60/// </param>
 61/// <param name="useBackgroundThreads">
 62/// If true, background threads are used, which do not prevent application exit
 63/// 是否使用后台线程，若是用，则应用程序可以自由的退出，而不用担心
 64/// </param>
 65/// <param name="threadPoolName">
 66/// Friendly name to use for the OS Threads and this dispatcher instance
 67/// </param>
 68public Dispatcher(int threadCount, ThreadPriority priority, bool useBackgroundThreads, string threadPoolName)
 69    : this(threadCount,
 70            priority,
 71            useBackgroundThreads ? DispatcherOptions.UseBackgroundThreads : DispatcherOptions.None,
 72            threadPoolName)
 73{
 74}
 75
 76/**//// <summary>
 77/// Constructs a Dispatcher instance. 
 78/// The instance is usable only after AddPort is called at least once
 79/// </summary>
 80/// <param name="threadCount">
 81/// Number of OS threads to use for processing CCR Tasks
 82/// </param>
 83/// <param name="priority">
 84/// OS Thread priority to use for threads exexuting CCR tasks
 85/// </param>
 86/// <param name="options">
 87/// Dispatcher scheduling options
 88/// </param>
 89/// <param name="threadApartmentState">
 90/// Thread apartment state. Use ApartmentState.Unknown when STA/MTA is not required for interop
 91/// 线程单元状态，当COM interop不需要STA/MTA的时候可以使用ApartmentState.Unknown
 92/// </param>
 93/// <param name="threadPoolName">
 94/// Friendly name to use for the OS Threads and this dispatcher instance
 95/// </param>
 96public Dispatcher(int threadCount, ThreadPriority priority, DispatcherOptions options,
 97                    ApartmentState threadApartmentState, string threadPoolName)
 98{
 99    this._startupCompleteEvent = new ManualResetEvent(false);
    this._dispatcherQueues = new List<DispatcherQueue>();
    this._taskExecutionWorkers = new List<TaskExecutionWorker>();
    this._nameToQueueTable = new Dictionary<string, DispatcherQueue>();

    // 线程数
    if (threadCount == 0)
    {// 默认情况下
        threadCount = Math.Max(NumberOfProcessorsInternal, 2) * ThreadsPerCpu;
    }
    else if (threadCount < 0)
    {
        throw new ArgumentException("Cannot create a negative number of threads. Pass 0 to use default.", "threadCount");
    }

    if (threadPoolName == null)
    {
        this._name = string.Empty;
    }
    else
    {
        this._name = threadPoolName;
    }

    this._options = options;

    for (int i = 0; i < threadCount; i++)
    {
        this.AddWorker(priority, threadApartmentState);
    }

    this.StartWorkers();
}

/**//// <summary>
/// Creates one TaskExecutionWorker instance associated with one OS thread
/// 创建一个与线程想关联的TaskExecutionWorker实例
/// </summary>
/// <remarks>
/// This routine should only be called once per dispatcher instance
/// 每个Dispatcher实例只能调用该函数一次
/// </remarks>
private void AddWorker(ThreadPriority priority, ApartmentState apartmentState)
{
    TaskExecutionWorker item = new TaskExecutionWorker(this);

    Thread thread = new Thread(new ThreadStart(item.ExecutionLoop));
    thread.SetApartmentState(apartmentState);
    thread.Name = this._name;
    thread.Priority = priority;
    thread.IsBackground = DispatcherOptions.None < (this._options & DispatcherOptions.UseBackgroundThreads);

    item._thread = thread;

    this._taskExecutionWorkers.Add(item);
    this._cachedWorkerListCount++;
}

二、Dispose函数
    使用该函数才能够释放Dispatcher内创建的线程池等资源，记得在退出程序之前，调用它，内部的实现细节很简单，详细请参考代码。

 1 /// <summary>
 2 /// Stops all scheduling and disposes this dispatcher instance
 3 /// 停止所有的调度并释放当前Dispatcher实例
 4 /// </summary>
 5 public void Dispose()
 6 {
 7     if (this._cachedWorkerListCount != 0)
 8     {
 9         lock (this._taskExecutionWorkers)
         {
             foreach (TaskExecutionWorker worker in this._taskExecutionWorkers)
             {
                 worker.Shutdown();
             }
             this._cachedWorkerListCount = 0;
         }
 
         if (this._startupCompleteEvent != null)
         {
             this._startupCompleteEvent.Close();
         }
 
         this.Shutdown(true);
     }
 }
 
 /// <summary>
 /// Stops all dispatcher worker threads and cleans up the dispatcher
 /// 停止所有的工作线程并清理资源
 /// </summary>
 private void Shutdown(bool wait)
 {
     //this.Dispose();
 
     lock (this._taskExecutionWorkers)
     {
         this._hasShutdown = true;
         Monitor.PulseAll(this._taskExecutionWorkers);
         if (wait)
         {
             while (!this._hasShutdown)
             {
                 Monitor.Wait(this._taskExecutionWorkers);
             }
         }
     }
 }

三、几个重要的枚举
1、 ThreadPriority:  指定Thread 的调度优先级。

public enum ThreadPriority
{
    // 可以将 System.Threading.Thread 安排在具有任何其他优先级的线程之后。
    Lowest = 0,
    // 可以将 System.Threading.Thread 安排在具有 Normal 优先级的线程之后，
    // 在具有 Lowest 优先级的线程之前。
    BelowNormal = 1,
    // 可以将 System.Threading.Thread 安排在具有 AboveNormal 优先级的线程之后，
    // 在具有 BelowNormal 优先级的线程之前。默认情况下，线程具有
    // Normal 优先级。
    Normal = 2,
    // 可以将 System.Threading.Thread 安排在具有 Highest 优先级的线程之后，
    // 在具有 Normal 优先级的线程之前。
    AboveNormal = 3,
    // 可以将 System.Threading.Thread 安排在具有任何其他优先级的线程之前。
    Highest = 4,
}

2、DispatcherOptions: 线程池运行选项

public enum DispatcherOptions
{
    None,
    /// <summary>
    /// 时候后台线程
    /// </summary>
    UseBackgroundThreads,
    /// <summary>
    /// 按照CPU来分配线程
    /// </summary>
    UseProcessorAffinity
}

3、ApartmentState: 指定 System.Threading.Thread 的单元状态

public enum ApartmentState
{
    // System.Threading.Thread 将创建并进入一个单线程单元。
    STA = 0,
    // System.Threading.Thread 将创建并进入一个多线程单元。
    MTA = 1,
    // 尚未设置 System.Threading.Thread.ApartmentState 属性。
    Unknown = 2,
}

四、附录：
1、相关参考链接：
MSDN杂志上的一个CCR专栏文章：http://msdn.microsoft.com/zh-cn/magazine/cc163556(en-us).aspx

2、本系列其他文章：
我的CCR之旅（1）：来自微软机器人技术工作室的新并发、异步解决方案
我的CCR之旅（2）：打开CCR的大门，编写一个不用创建线程，不用考虑资源互斥的多线程程序
我的CCR之旅（3）：CCR任务调度的原理和策略