blob: 0192b1942c274289ccc11376cbf075dce4c98172 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
// 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>
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"));
}
}
}
|