| | | 1 | | // Licensed to the .NET Foundation under one or more agreements. |
| | | 2 | | // The .NET Foundation licenses this file to you under the MIT license. |
| | | 3 | | |
| | | 4 | | namespace System.Buffers |
| | | 5 | | { |
| | | 6 | | /// <summary> |
| | | 7 | | /// Provides a resource pool that enables reusing instances of arrays. |
| | | 8 | | /// </summary> |
| | | 9 | | /// <remarks> |
| | | 10 | | /// <para> |
| | | 11 | | /// Renting and returning buffers with an <see cref="ArrayPool{T}"/> can increase performance |
| | | 12 | | /// in situations where arrays are created and destroyed frequently, resulting in significant |
| | | 13 | | /// memory pressure on the garbage collector. |
| | | 14 | | /// </para> |
| | | 15 | | /// <para> |
| | | 16 | | /// This class is thread-safe. All members may be used by multiple threads concurrently. |
| | | 17 | | /// </para> |
| | | 18 | | /// </remarks> |
| | | 19 | | public abstract class ArrayPool<T> |
| | | 20 | | { |
| | | 21 | | // Store the shared ArrayPool in a field of its derived sealed type so the Jit can "see" the exact type |
| | | 22 | | // when the Shared property is inlined which will allow it to devirtualize calls made on it. |
| | 0 | 23 | | private static readonly SharedArrayPool<T> s_shared = new SharedArrayPool<T>(); |
| | | 24 | | |
| | | 25 | | /// <summary> |
| | | 26 | | /// Retrieves a shared <see cref="ArrayPool{T}"/> instance. |
| | | 27 | | /// </summary> |
| | | 28 | | /// <remarks> |
| | | 29 | | /// The shared pool provides a default implementation of <see cref="ArrayPool{T}"/> |
| | | 30 | | /// that's intended for general applicability. It maintains arrays of multiple sizes, and |
| | | 31 | | /// may hand back a larger array than was actually requested, but will never hand back a smaller |
| | | 32 | | /// array than was requested. Renting a buffer from it with <see cref="Rent"/> will result in an |
| | | 33 | | /// existing buffer being taken from the pool if an appropriate buffer is available or in a new |
| | | 34 | | /// buffer being allocated if one is not available. |
| | | 35 | | /// The shared pool instance is created lazily on first access. |
| | | 36 | | /// </remarks> |
| | 0 | 37 | | public static ArrayPool<T> Shared => s_shared; |
| | | 38 | | |
| | | 39 | | /// <summary> |
| | | 40 | | /// Creates a new <see cref="ArrayPool{T}"/> instance using default configuration options. |
| | | 41 | | /// </summary> |
| | | 42 | | /// <returns>A new <see cref="ArrayPool{T}"/> instance.</returns> |
| | 0 | 43 | | public static ArrayPool<T> Create() => new ConfigurableArrayPool<T>(); |
| | | 44 | | |
| | | 45 | | /// <summary> |
| | | 46 | | /// Creates a new <see cref="ArrayPool{T}"/> instance using custom configuration options. |
| | | 47 | | /// </summary> |
| | | 48 | | /// <param name="maxArrayLength">The maximum length of array instances that may be stored in the pool.</param> |
| | | 49 | | /// <param name="maxArraysPerBucket"> |
| | | 50 | | /// The maximum number of array instances that may be stored in each bucket in the pool. The pool |
| | | 51 | | /// groups arrays of similar lengths into buckets for faster access. |
| | | 52 | | /// </param> |
| | | 53 | | /// <returns>A new <see cref="ArrayPool{T}"/> instance with the specified configuration options.</returns> |
| | | 54 | | /// <remarks> |
| | | 55 | | /// The created pool will group arrays into buckets, with no more than <paramref name="maxArraysPerBucket"/> |
| | | 56 | | /// in each bucket and with those arrays not exceeding <paramref name="maxArrayLength"/> in length. |
| | | 57 | | /// </remarks> |
| | | 58 | | public static ArrayPool<T> Create(int maxArrayLength, int maxArraysPerBucket) => |
| | 0 | 59 | | new ConfigurableArrayPool<T>(maxArrayLength, maxArraysPerBucket); |
| | | 60 | | |
| | | 61 | | /// <summary> |
| | | 62 | | /// Retrieves a buffer that is at least the requested length. |
| | | 63 | | /// </summary> |
| | | 64 | | /// <param name="minimumLength">The minimum length of the array needed.</param> |
| | | 65 | | /// <returns> |
| | | 66 | | /// An array that is at least <paramref name="minimumLength"/> in length. |
| | | 67 | | /// </returns> |
| | | 68 | | /// <remarks> |
| | | 69 | | /// This buffer is loaned to the caller and should be returned to the same pool via |
| | | 70 | | /// <see cref="Return"/> so that it may be reused in subsequent usage of <see cref="Rent"/>. |
| | | 71 | | /// It is not a fatal error to not return a rented buffer, but failure to do so may lead to |
| | | 72 | | /// decreased application performance, as the pool may need to create a new buffer to replace |
| | | 73 | | /// the one lost. |
| | | 74 | | /// </remarks> |
| | | 75 | | public abstract T[] Rent(int minimumLength); |
| | | 76 | | |
| | | 77 | | /// <summary> |
| | | 78 | | /// Returns to the pool an array that was previously obtained via <see cref="Rent"/> on the same |
| | | 79 | | /// <see cref="ArrayPool{T}"/> instance. |
| | | 80 | | /// </summary> |
| | | 81 | | /// <param name="array"> |
| | | 82 | | /// The buffer previously obtained from <see cref="Rent"/> to return to the pool. |
| | | 83 | | /// </param> |
| | | 84 | | /// <param name="clearArray"> |
| | | 85 | | /// If <c>true</c> and if the pool will store the buffer to enable subsequent reuse, <see cref="Return"/> |
| | | 86 | | /// will clear <paramref name="array"/> of its contents so that a subsequent consumer via <see cref="Rent"/> |
| | | 87 | | /// will not see the previous consumer's content. If <c>false</c> or if the pool will release the buffer, |
| | | 88 | | /// the array's contents are left unchanged. |
| | | 89 | | /// </param> |
| | | 90 | | /// <remarks> |
| | | 91 | | /// Once a buffer has been returned to the pool, the caller gives up all ownership of the buffer |
| | | 92 | | /// and must not use it. The reference returned from a given call to <see cref="Rent"/> must only be |
| | | 93 | | /// returned via <see cref="Return"/> once. The default <see cref="ArrayPool{T}"/> |
| | | 94 | | /// may hold onto the returned buffer in order to rent it again, or it may release the returned buffer |
| | | 95 | | /// if it's determined that the pool already has enough buffers stored. |
| | | 96 | | /// </remarks> |
| | | 97 | | public abstract void Return(T[] array, bool clearArray = false); |
| | | 98 | | |
| | | 99 | | internal void Return(T[] array, int lengthToClear) |
| | | 100 | | { |
| | 0 | 101 | | array.AsSpan(0, lengthToClear).Clear(); |
| | 0 | 102 | | Return(array); |
| | 0 | 103 | | } |
| | | 104 | | } |
| | | 105 | | } |
| | | 106 | | |