mcs/class/referencesource/mscorlib/system/collections/Concurrent/IProducerConsumerCollection.cs

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