// 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.
// =+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
//
//
//
//
//
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
using System;
using System.Collections.Generic;
using System.Security.Permissions;
using System.Threading;
namespace System.Collections.Concurrent
{
///
/// Represents a particular manner of splitting an orderable data source into multiple partitions.
///
/// Type of the elements in the collection.
///
///
/// Each element in each partition has an integer index associated with it, which determines the relative
/// order of that element against elements in other partitions.
///
///
/// Inheritors of must adhere to the following rules:
///
/// - All indices must be unique, such that there may not be duplicate indices. If all indices are not
/// unique, the output ordering may be scrambled.
/// - All indices must be non-negative. If any indices are negative, consumers of the implementation
/// may throw exceptions.
/// - and should throw a
/// if the requested partition count is less than or
/// equal to zero.
/// - and 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 .
/// - , ,
/// , and
/// should never return null. If null is returned, a consumer of the implementation may throw a
/// .
/// - , ,
/// , and
/// 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.
/// - If returns true, each partition must return elements
/// with increasing key indices.
/// - If returns true, all the keys in partition numbered N
/// must be larger than all the keys in partition numbered N-1.
/// - If returns true, all indices must be monotonically increasing from
/// 0, though not necessarily within a single partition.
///
///
///
public abstract class OrderablePartitioner : Partitioner
{
///
/// Initializes a new instance of the class with the
/// specified constraints on the index keys.
///
///
/// Indicates whether the elements in each partition are yielded in the order of
/// increasing keys.
///
///
/// Indicates whether elements in an earlier partition always come before
/// elements in a later partition. If true, each element in partition 0 has a smaller order key than
/// any element in partition 1, each element in partition 1 has a smaller order key than any element
/// in partition 2, and so on.
///
///
/// Indicates whether keys are normalized. If true, all order keys are distinct
/// integers in the range [0 .. numberOfElements-1]. If false, order keys must still be dictinct, but
/// only their relative order is considered, not their absolute values.
///
protected OrderablePartitioner(bool keysOrderedInEachPartition, bool keysOrderedAcrossPartitions, bool keysNormalized)
{
KeysOrderedInEachPartition = keysOrderedInEachPartition;
KeysOrderedAcrossPartitions = keysOrderedAcrossPartitions;
KeysNormalized = keysNormalized;
}
///
/// Partitions the underlying collection into the specified number of orderable partitions.
///
///
/// Each partition is represented as an enumerator over key-value pairs.
/// The value of the pair is the element itself, and the key is an integer which determines
/// the relative ordering of this element against other elements in the data source.
///
/// The number of partitions to create.
/// A list containing enumerators.
public abstract IList>> GetOrderablePartitions(int partitionCount);
///
/// Creates an object that can partition the underlying collection into a variable number of
/// partitions.
///
///
///
/// The returned object implements the interface. Calling GetEnumerator on the
/// object creates another partition over the sequence.
///
///
/// Each partition is represented as an enumerator over key-value pairs. The value in the pair is the element
/// itself, and the key is an integer which determines the relative ordering of this element against
/// other elements.
///
///
/// The method is only supported if the SupportsDynamicPartitions
/// property returns true.
///
///
/// An object that can create partitions over the underlying data source.
/// Dynamic partitioning is not supported by this
/// partitioner.
public virtual IEnumerable> GetOrderableDynamicPartitions()
{
throw new NotSupportedException(Environment.GetResourceString("Partitioner_DynamicPartitionsNotSupported"));
}
///
/// Gets whether elements in each partition are yielded in the order of increasing keys.
///
public bool KeysOrderedInEachPartition { get; private set; }
///
/// Gets whether elements in an earlier partition always come before elements in a later partition.
///
///
/// If returns true, each element in partition 0 has a
/// smaller order key than any element in partition 1, each element in partition 1 has a smaller
/// order key than any element in partition 2, and so on.
///
public bool KeysOrderedAcrossPartitions { get; private set; }
///
/// Gets whether order keys are normalized.
///
///
/// If returns true, all order keys are distinct integers in the range
/// [0 .. numberOfElements-1]. If the property returns false, order keys must still be dictinct, but
/// only their relative order is considered, not their absolute values.
///
public bool KeysNormalized { get; private set; }
///
/// Partitions the underlying collection into the given number of ordered partitions.
///
///
/// The default implementation provides the same behavior as except
/// that the returned set of partitions does not provide the keys for the elements.
///
/// The number of partitions to create.
/// A list containing enumerators.
public override IList> GetPartitions(int partitionCount)
{
IList>> orderablePartitions = GetOrderablePartitions(partitionCount);
if (orderablePartitions.Count != partitionCount)
{
throw new InvalidOperationException("OrderablePartitioner_GetPartitions_WrongNumberOfPartitions");
}
IEnumerator[] partitions = new IEnumerator[partitionCount];
for (int i = 0; i < partitionCount; i++)
{
partitions[i] = new EnumeratorDropIndices(orderablePartitions[i]);
}
return partitions;
}
///
/// Creates an object that can partition the underlying collection into a variable number of
/// partitions.
///
///
///
/// The returned object implements the interface. Calling GetEnumerator on the
/// object creates another partition over the sequence.
///
///
/// The default implementation provides the same behavior as except
/// that the returned set of partitions does not provide the keys for the elements.
///
///
/// The method is only supported if the
/// property returns true.
///
///
/// An object that can create partitions over the underlying data source.
/// Dynamic partitioning is not supported by this
/// partitioner.
public override IEnumerable GetDynamicPartitions()
{
IEnumerable> orderablePartitions = GetOrderableDynamicPartitions();
return new EnumerableDropIndices(orderablePartitions);
}
///
/// Converts an enumerable over key-value pairs to an enumerable over values.
///
private class EnumerableDropIndices : IEnumerable, IDisposable
{
private readonly IEnumerable> m_source;
public EnumerableDropIndices(IEnumerable> source)
{
m_source = source;
}
public IEnumerator GetEnumerator()
{
return new EnumeratorDropIndices(m_source.GetEnumerator());
}
IEnumerator IEnumerable.GetEnumerator()
{
return ((EnumerableDropIndices)this).GetEnumerator();
}
public void Dispose()
{
IDisposable d = m_source as IDisposable;
if (d != null)
{
d.Dispose();
}
}
}
private class EnumeratorDropIndices : IEnumerator
{
private readonly IEnumerator> m_source;
public EnumeratorDropIndices(IEnumerator> source)
{
m_source = source;
}
public bool MoveNext()
{
return m_source.MoveNext();
}
public TSource Current
{
get
{
return m_source.Current.Value;
}
}
Object IEnumerator.Current
{
get
{
return ((EnumeratorDropIndices)this).Current;
}
}
public void Dispose()
{
m_source.Dispose();
}
public void Reset()
{
m_source.Reset();
}
}
}
}