C# Reference ยท Collections
ArrayPool<T> class
Reference for C# ArrayPool<T>: rent a reusable array with Rent, give it back with Return, clearArray, size guarantees and the mistakes that corrupt shared buffers.
System.Buffers.ArrayPool<T> hands out reusable arrays so that code which needs a temporary buffer many times does not allocate (and later garbage-collect) a new one each time. You Rent an array of at least the size you need, use it, and Return it when done. The shared pool is ArrayPool<T>.Shared.
Pooling pays off for large arrays (roughly 1 KB and up) used briefly on hot paths such as parsing, I/O and serialization. For small, short-lived arrays or code that is not hot, plain new T[n], stackalloc or Span<T> is simpler and just as fast.
using System.Buffers; byte[] buffer = ArrayPool<byte>.Shared.Rent(4096); try { // use buffer[0..n] } finally { ArrayPool<byte>.Shared.Return(buffer); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public abstract class ArrayPool<T> { public static ArrayPool<T> Shared { get; } public static ArrayPool<T> Create(); public static ArrayPool<T> Create(int maxArrayLength, int maxArraysPerBucket); public abstract T[] Rent(int minimumLength); public abstract void Return(T[] array, bool clearArray = false); }
| Name | Description |
|---|---|
minimumLength |
The smallest acceptable length of the returned array. |
array |
An array previously obtained from the same pool. |
clearArray |
If true, the pool zeroes the array before storing it for reuse. |
maxArrayLength, maxArraysPerBucket |
Limits for a private pool created with Create. |
Returns: Rent returns an array whose Length is at least minimumLength, usually rounded up to the next bucket size. Its contents are unspecified.
Errors: Rent throws ArgumentOutOfRangeException for a negative length. Return throws ArgumentNullException for null.
Usage notes
- Track the real length yourself. Use
buffer.AsSpan(0, count)orMemory<T>slices, neverbuffer.Length, to represent how many valid items there are. - Rented memory is not cleared. Do not read before you write, and pass
clearArray: trueon return when it held passwords, keys or personal data. - After
Return, the array belongs to the pool. Reading or writing it afterwards, or returning it twice, corrupts other callers' data. - Always return in a
finallyblock. Forgetting is not a leak (the GC still collects it) but it defeats the pooling. - Arrays of reference types keep their referenced objects alive while sitting in the pool unless you pass
clearArray: true. ArrayPool<T>.Sharedis thread-safe and tuned for typical sizes; arrays above about a million elements are not pooled by default.MemoryPool<T>is theIMemoryOwner<T>-based alternative that fitsusingstatements andMemory<T>.- Use a
stackallocspan for small buffers (a few hundred bytes) and skip the pool completely.
Related
- Span
- stackalloc
- Array class
- Capacity and resizing
- Spans and memory in the tutorial