mcs/class/System.Threading.Tasks.Dataflow/CoreFxSources/Internal/IProducerConsumerCollection.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 // IProducerConsumerCollection.cs
   7 //
   8 //
   9 // A common interface for all concurrent collections.
  10 //
  11 // =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  12
  13 using System.Collections;
  14 using System.Collections.Generic;
  15 using System.Diagnostics;
  16
  17 namespace System.Threading.Tasks.Dataflow.Internal.Collections
  18 {
  19     /// <summary>
  20     /// Defines methods to manipulate thread-safe collections intended for producer/consumer usage.
  21     /// </summary>
  22     /// <typeparam name="T">Specifies the type of elements in the collection.</typeparam>
  23     /// <remarks>
  24     /// All implementations of this interface must enable all members of this interface
  25     /// to be used concurrently from multiple threads.
  26     /// </remarks>
  27     internal interface IProducerConsumerCollection<T> : IEnumerable<T>, ICollection
  28     {
  29         /// <summary>
  30         /// Copies the elements of the <see cref="IProducerConsumerCollection{T}"/> to
  31         /// an
  32         /// <see cref="T:System.Array"/>, starting at a specified index.
  33         /// </summary>
  34         /// <param name="array">The one-dimensional <see cref="T:System.Array"/> that is the destination of
  35         /// the elements copied from the <see cref="IProducerConsumerCollection{T}"/>.
  36         /// The array must have zero-based indexing.</param>
  37         /// <param name="index">The zero-based index in <paramref name="array"/> at which copying
  38         /// begins.</param>
  39         /// <exception cref="ArgumentNullException"><paramref name="array"/> is a null reference (Nothing in
  40         /// Visual Basic).</exception>
  41         /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is less than
  42         /// zero.</exception>
  43         /// <exception cref="ArgumentException"><paramref name="index"/> is equal to or greater than the
  44         /// length of the <paramref name="array"/>
  45         /// -or- The number of elements in the source <see cref="ConcurrentQueue{T}"/> is greater than the
  46         /// available space from <paramref name="index"/> to the end of the destination <paramref
  47         /// name="array"/>.
  48         /// </exception>
  49         void CopyTo(T[] array, int index);
  50
  51         /// <summary>
  52         /// Attempts to add an object to the <see
  53         /// cref="IProducerConsumerCollection{T}"/>.
  54         /// </summary>
  55         /// <param name="item">The object to add to the <see
  56         /// cref="IProducerConsumerCollection{T}"/>.</param>
  57         /// <returns>true if the object was added successfully; otherwise, false.</returns>
  58         /// <exception cref="T:System.ArgumentException">The <paramref name="item"/> was invalid for this collection.</exception>
  59         bool TryAdd(T item);
  60
  61         /// <summary>
  62         /// Attempts to remove and return an object from the <see cref="IProducerConsumerCollection{T}"/>.
  63         /// </summary>
  64         /// <param name="item">
  65         /// When this method returns, if the object was removed and returned successfully, <paramref
  66         /// name="item"/> contains the removed object. If no object was available to be removed, the value is
  67         /// unspecified.
  68         /// </param>
  69         /// <returns>true if an object was removed and returned successfully; otherwise, false.</returns>
  70         bool TryTake(out T item);
  71
  72         /// <summary>
  73         /// Copies the elements contained in the <see cref="IProducerConsumerCollection{T}"/> to a new array.
  74         /// </summary>
  75         /// <returns>A new array containing the elements copied from the <see cref="IProducerConsumerCollection{T}"/>.</returns>
  76         T[] ToArray();
  77     }
  78
  79
  80     /// <summary>
  81     /// A debugger view of the IProducerConsumerCollection that makes it simple to browse the
  82     /// collection's contents at a point in time.
  83     /// </summary>
  84     /// <typeparam name="T">The type of elements stored within.</typeparam>
  85     internal sealed class SystemCollectionsConcurrent_ProducerConsumerCollectionDebugView<T>
  86     {
  87         private IProducerConsumerCollection<T> _collection; // The collection being viewed.
  88
  89         /// <summary>
  90         /// Constructs a new debugger view object for the provided collection object.
  91         /// </summary>
  92         /// <param name="collection">A collection to browse in the debugger.</param>
  93         public SystemCollectionsConcurrent_ProducerConsumerCollectionDebugView(IProducerConsumerCollection<T> collection)
  94         {
  95             if (collection == null)
  96             {
  97                 throw new ArgumentNullException("collection");
  98             }
  99
 100             _collection = collection;
 101         }
 102
 103         /// <summary>
 104         /// Returns a snapshot of the underlying collection's elements.
 105         /// </summary>
 106         [DebuggerBrowsable(DebuggerBrowsableState.RootHidden)]
 107         public T[] Items
 108         {
 109             get { return _collection.ToArray(); }
 110         }
 111     }
 112 }