mcs/class/System.Threading.Tasks.Dataflow/CoreFxSources/Base/DataflowLinkOptions.cs

   1 // Copyright (c) Microsoft. All rights reserved.
   2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
   3
   4 // =+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
   5 //
   6 // DataflowLinkOptions.cs
   7 //
   8 //
   9 // DataflowLinkOptions type for configuring links between dataflow blocks
  10 //
  11 // =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  12
  13 using System;
  14 using System.Diagnostics;
  15 using System.Threading.Tasks;
  16
  17 namespace System.Threading.Tasks.Dataflow
  18 {
  19     /// <summary>
  20     /// Provides options used to configure a link between dataflow blocks.
  21     /// </summary>
  22     /// <remarks>
  23     /// <see cref="DataflowLinkOptions"/> is mutable and can be configured through its properties.
  24     /// When specific configuration options are not set, the following defaults are used:
  25     /// <list type="table">
  26     ///     <listheader>
  27     ///         <term>Options</term>
  28     ///         <description>Default</description>
  29     ///     </listheader>
  30     ///     <item>
  31     ///         <term>PropagateCompletion</term>
  32     ///         <description>False</description>
  33     ///     </item>
  34     ///     <item>
  35     ///         <term>MaxMessages</term>
  36     ///         <description>DataflowBlockOptions.Unbounded (-1)</description>
  37     ///     </item>
  38     ///     <item>
  39     ///         <term>Append</term>
  40     ///         <description>True</description>
  41     ///     </item>
  42     /// </list>
  43     /// Dataflow blocks capture the state of the options at linking. Subsequent changes to the provided
  44     /// <see cref="DataflowLinkOptions"/> instance should not affect the behavior of a link.
  45     /// </remarks>
  46     [DebuggerDisplay("PropagateCompletion = {PropagateCompletion}, MaxMessages = {MaxMessages}, Append = {Append}")]
  47     public class DataflowLinkOptions
  48     {
  49         /// <summary>
  50         /// A constant used to specify an unlimited quantity for <see cref="DataflowLinkOptions"/> members
  51         /// that provide an upper bound. This field is a constant tied to <see cref="DataflowLinkOptions.Unbounded"/>.
  52         /// </summary>
  53         internal const Int32 Unbounded = DataflowBlockOptions.Unbounded;
  54
  55         /// <summary>Whether the linked target will have completion and faulting notification propagated to it automatically.</summary>
  56         private Boolean _propagateCompletion = false;
  57         /// <summary>The maximum number of messages that may be consumed across the link.</summary>
  58         private Int32 _maxNumberOfMessages = Unbounded;
  59         /// <summary>Whether the link should be appended to the source’s list of links, or whether it should be prepended.</summary>
  60         private Boolean _append = true;
  61
  62         /// <summary>A default instance of <see cref="DataflowLinkOptions"/>.</summary>
  63         /// <remarks>
  64         /// Do not change the values of this instance.  It is shared by all of our blocks when no options are provided by the user.
  65         /// </remarks>
  66         internal static readonly DataflowLinkOptions Default = new DataflowLinkOptions();
  67
  68         /// <summary>A cached instance of <see cref="DataflowLinkOptions"/>.</summary>
  69         /// <remarks>
  70         /// Do not change the values of this instance.  It is shared by all of our blocks that need to unlink after one message has been consumed.
  71         /// </remarks>
  72         internal static readonly DataflowLinkOptions UnlinkAfterOneAndPropagateCompletion = new DataflowLinkOptions() { MaxMessages = 1, PropagateCompletion = true };
  73
  74         /// <summary>Initializes the <see cref="DataflowLinkOptions"/>.</summary>
  75         public DataflowLinkOptions()
  76         {
  77         }
  78
  79         /// <summary>Gets or sets whether the linked target will have completion and faulting notification propagated to it automatically.</summary>
  80         public Boolean PropagateCompletion
  81         {
  82             get { return _propagateCompletion; }
  83             set
  84             {
  85                 Debug.Assert(this != Default && this != UnlinkAfterOneAndPropagateCompletion, "Default and UnlinkAfterOneAndPropagateCompletion instances are supposed to be immutable.");
  86                 _propagateCompletion = value;
  87             }
  88         }
  89
  90         /// <summary>Gets or sets the maximum number of messages that may be consumed across the link.</summary>
  91         public Int32 MaxMessages
  92         {
  93             get { return _maxNumberOfMessages; }
  94             set
  95             {
  96                 Debug.Assert(this != Default && this != UnlinkAfterOneAndPropagateCompletion, "Default and UnlinkAfterOneAndPropagateCompletion instances are supposed to be immutable.");
  97                 if (value < 1 && value != Unbounded) throw new ArgumentOutOfRangeException("value");
  98                 _maxNumberOfMessages = value;
  99             }
 100         }
 101
 102         /// <summary>Gets or sets whether the link should be appended to the source’s list of links, or whether it should be prepended.</summary>
 103         public Boolean Append
 104         {
 105             get { return _append; }
 106             set
 107             {
 108                 Debug.Assert(this != Default && this != UnlinkAfterOneAndPropagateCompletion, "Default and UnlinkAfterOneAndPropagateCompletion instances are supposed to be immutable.");
 109                 _append = value;
 110             }
 111         }
 112     }
 113 }