Master | Latest |
---|---|
This library is based on classes from System.Collections.Generic
that have been altered
to take advantage of the new System.Span<T>
and System.Buffers.ArrayPool<T>
libraries
to minimize memory allocations, improve performance, and/or allow greater interoperablity
with modern API's.
Collections.Pooled supports both .NET Standard 2.0 (.NET Framework 4.6.1+) as well as an optimized build for .NET Core 2.1+. An extensive set of unit tests and benchmarks have been ported from corefx.
Total tests: 27501. Passed: 27501. Failed: 0. Skipped: 0.
Test Run Successful.
Test execution time: 9.9019 Seconds
Install-Package Collections.Pooled
dotnet add package Collections.Pooled
paket add Collections.Pooled
PooledList<T>
PooledList<T>
is based on the corefx source code for System.Collections.Generic.List<T>
,
modified to use ArrayPool for internal array-storage allocation, and to support Span<T>
.
There are some API changes worth noting:
Find
and FindLast
have become TryFind
and TryFindLast
, following the standard
.NET "try" pattern.PooledList<T>.Span
property returns a Span<T>
over the portion of the internal
array store that is populated. This span can be further sliced, or passed into other methods
that can read from or write to a span.
GetRange
now returns a Span<T>
. For example, foo.GetRange(5, 100)
is equivalent to foo.Span.Slice(5, 100)
.CopyTo
now takes a Span<T>
and doesn't offer any start-index or count parameters. Use the Span
property and slicing instead.AddRange
and InsertRange
can now accept a ReadOnlySpan<T>
.AddSpan
and InsertSpan
methods ensure the internal storage has the capacity
to add the requested number of items, and return a Span<T>
that can be used to write
directly to that section of the internal storage. Caveats about "collection modified during enumeration"
checks apply here as well.Predicate<T>
and Converter<T1, T2>
have been replaced with standard Func<>
equivalents.List<T>
(you will still benefit from pooling of intermediate arrays as the PooledList is resized).ToPooledList()
extension methods are provided.ArrayPool<T>
to the constructor, to be used instead of the
default ArrayPool<T>.Shared
pool.clearMode
constructor parameter gives you control over whether data is cleared before returning
arrays to the ArrayPool.sizeToCapacity
constructor parameter causes the list to start out with Count == Capacity
.
All entries in the list will have the default value for the type, or if clearMode
is set to ClearMode.Never
then entries in the list may have a previously-used value from the array pool. This feature is primarily useful
when working with value types and avoiding unnecessary allocations.Adding items to a list is one area where ArrayPool helps us quite a bit:
PooledDictionary<TKey, TValue>
PooledDictionary<TKey, TValue>
is based on the corefx source code for System.Collections.Generic.Dictionary<TKey, TValue>
,
modified to use ArrayPool for internal storage allocation, and to support Span<T>
.
There are some API changes worth noting:
AddRange
, GetOrAdd
, AddOrUpdate
KeyValuePair<TKey, TValue>
objects, or a sequence of
ValueTuple<TKey, TValue>
objects.Dictionary<TKey, TValue>
(you will still benefit from pooling of intermediate arrays as the PooledDictionary is resized).ToPooledDictionary()
extension methods are provided.ClearMode
constructor parameter gives you control over whether data is cleared before returning
arrays to the ArrayPool.Adding to dictionaries is where using ArrayPool really has an impact:
PooledSet<T>
PooledSet<T>
is based on the corefx source code for System.Generic.Collections.HashSet<T>
,
modified to use ArrayPool for internal storage allocation, and to support ReadOnlySpan<T>
for all set functions.
ReadOnlySpan<T>
.HashSet<T>
(you will still benefit from pooling of intermediate arrays as the PooledSet is resized).ToPooledSet()
extension methods are provided.ClearMode
constructor parameter gives you control over whether data is cleared before returning
arrays to the ArrayPool.Here's what pooling does for us when adding to a PooledSet.
PooledStack<T>
PooledStack<T>
is based on the corefx source code for System.Generic.Collections.Stack<T>
,
modified to use ArrayPool for internal storage allocation.
Stack<T>
is the addition of the RemoveWhere method: because sometimes you just need to remove
something from a stack.Stack<T>
(you will still benefit from pooling of intermediate arrays as the PooledStack is resized).ToPooledStack()
extension methods are provided.ArrayPool<T>
to the constructor, to be used instead of the
default ArrayPool<T>.Shared
pool.ClearMode
constructor parameter gives you control over whether data is cleared before returning
arrays to the ArrayPool.Once again, pushing to a stack shows off some of the advantages of using ArrayPool:
PooledQueue<T>
PooledQueue<T>
is based on the corefx source code for System.Generic.Collections.Queue<T>
,
modified to use ArrayPool for internal storage allocation.
Queue<T>
is the addition of the RemoveWhere method: because sometimes you just need to remove
something from a queue.Queue<T>
(you will still benefit from pooling of intermediate arrays as the PooledQueue is resized).ToPooledQueue()
extension methods are provided.ArrayPool<T>
to the constructor, to be used instead of the
default ArrayPool<T>.Shared
pool.ClearMode
constructor parameter gives you control over whether data is cleared before returning
arrays to the ArrayPool.