summaryrefslogtreecommitdiff
path: root/src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs
diff options
context:
space:
mode:
Diffstat (limited to 'src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs')
-rw-r--r--src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs102
1 files changed, 102 insertions, 0 deletions
diff --git a/src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs b/src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs
new file mode 100644
index 0000000000..3d54c1471b
--- /dev/null
+++ b/src/mscorlib/src/System/Collections/Concurrent/Partitioner.cs
@@ -0,0 +1,102 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+// =+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
+//
+//
+//
+// Represents a particular way of splitting a collection into multiple partitions.
+//
+// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+using System;
+using System.Collections.Generic;
+using System.Security.Permissions;
+using System.Threading;
+
+namespace System.Collections.Concurrent
+{
+ /// <summary>
+ /// Represents a particular manner of splitting a data source into multiple partitions.
+ /// </summary>
+ /// <typeparam name="TSource">Type of the elements in the collection.</typeparam>
+ /// <remarks>
+ /// <para>
+ /// Inheritors of <see cref="Partitioner{TSource}"/> must adhere to the following rules:
+ /// <ol>
+ /// <li><see cref="GetPartitions"/> should throw a
+ /// <see cref="T:System.ArgumentOutOfRangeException"/> if the requested partition count is less than or
+ /// equal to zero.</li>
+ /// <li><see cref="GetPartitions"/> should always return a number of enumerables equal to the requested
+ /// partition count. If the partitioner runs out of data and cannot create as many partitions as
+ /// requested, an empty enumerator should be returned for each of the remaining partitions. If this rule
+ /// is not followed, consumers of the implementation may throw a <see
+ /// cref="T:System.InvalidOperationException"/>.</li>
+ /// <li><see cref="GetPartitions"/> and <see cref="GetDynamicPartitions"/>
+ /// should never return null. If null is returned, a consumer of the implementation may throw a
+ /// <see cref="T:System.InvalidOperationException"/>.</li>
+ /// <li><see cref="GetPartitions"/> and <see cref="GetDynamicPartitions"/> should always return
+ /// partitions that can fully and uniquely enumerate the input data source. All of the data and only the
+ /// data contained in the input source should be enumerated, with no duplication that was not already in
+ /// the input, unless specifically required by the particular partitioner's design. If this is not
+ /// followed, the output ordering may be scrambled.</li>
+ /// </ol>
+ /// </para>
+ /// </remarks>
+ [HostProtection(Synchronization = true, ExternalThreading = true)]
+ public abstract class Partitioner<TSource>
+ {
+ /// <summary>
+ /// Partitions the underlying collection into the given number of partitions.
+ /// </summary>
+ /// <param name="partitionCount">The number of partitions to create.</param>
+ /// <returns>A list containing <paramref name="partitionCount"/> enumerators.</returns>
+ public abstract IList<IEnumerator<TSource>> GetPartitions(int partitionCount);
+
+ /// <summary>
+ /// Gets whether additional partitions can be created dynamically.
+ /// </summary>
+ /// <returns>
+ /// true if the <see cref="Partitioner{TSource}"/> can create partitions dynamically as they are
+ /// requested; false if the <see cref="Partitioner{TSource}"/> can only allocate
+ /// partitions statically.
+ /// </returns>
+ /// <remarks>
+ /// <para>
+ /// If a derived class does not override and implement <see cref="GetDynamicPartitions"/>,
+ /// <see cref="SupportsDynamicPartitions"/> should return false. The value of <see
+ /// cref="SupportsDynamicPartitions"/> should not vary over the lifetime of this instance.
+ /// </para>
+ /// </remarks>
+ public virtual bool SupportsDynamicPartitions
+ {
+ get { return false; }
+ }
+
+ /// <summary>
+ /// Creates an object that can partition the underlying collection into a variable number of
+ /// partitions.
+ /// </summary>
+ /// <remarks>
+ /// <para>
+ /// The returned object implements the <see
+ /// cref="T:System.Collections.Generic.IEnumerable{TSource}"/> interface. Calling <see
+ /// cref="System.Collections.Generic.IEnumerable{TSource}.GetEnumerator">GetEnumerator</see> on the
+ /// object creates another partition over the sequence.
+ /// </para>
+ /// <para>
+ /// The <see cref="GetDynamicPartitions"/> method is only supported if the <see
+ /// cref="SupportsDynamicPartitions"/>
+ /// property returns true.
+ /// </para>
+ /// </remarks>
+ /// <returns>An object that can create partitions over the underlying data source.</returns>
+ /// <exception cref="NotSupportedException">Dynamic partitioning is not supported by this
+ /// partitioner.</exception>
+ public virtual IEnumerable<TSource> GetDynamicPartitions()
+ {
+ throw new NotSupportedException(Environment.GetResourceString("Partitioner_DynamicPartitionsNotSupported"));
+ }
+ }
+}