|
| 1 | +--- |
| 2 | +title: MemoryOwner<T> |
| 3 | +author: Sergio0694 |
| 4 | +description: A buffer type implementing `IMemoryOwner<T>` that rents memory from a shared pool |
| 5 | +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, parallel, high performance, net core, net standard |
| 6 | +dev_langs: |
| 7 | + - csharp |
| 8 | +--- |
| 9 | + |
| 10 | +# MemoryOwner<T> |
| 11 | + |
| 12 | +The [MemoryOwner<T>](https://docs.microsoft.com/dotnet/api/microsoft.toolkit.highperformance.buffers.memoryowner-1) is a buffer type implementing [`IMemoryOwner<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.buffers.imemoryowner-1), an embedded length property and a series of performance oriented APIs. It is essentially a lightweight wrapper around the [`ArrayPool<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.buffers.arraypool-1) type, with some additional helper utilities. |
| 13 | + |
| 14 | +## How it works |
| 15 | + |
| 16 | +`MemoryOwner<T>` has the following main features: |
| 17 | + |
| 18 | +- One of the main issues of arrays returned by the `ArrayPool<T>` APIs and of the `IMemoryOwner<T>` instances returned by the `MemoryPool<T>` APIs is that the size specified by the user is only being used as a _minum_ size: the actual size of the returned buffers might actually be greater. `MemoryOwner<T>` solves this by also storing the original requested size, so that [`Memory<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.memory-1) and [`Span<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.span-1) instances retrieved from it will never need to be manually sliced. |
| 19 | +- When using `IMemoryOwner<T>`, getting a `Span<T>` for the underlying buffer requires first to get a `Memory<T>` instance, and then a `Span<T>`. This is fairly expensive, and often unnecessary, as the intermediate `Memory<T>` might actually not be needed at all. `MemoryOwner<T>` instead has an additional `Span` property which is extremely lightweight, as it directly wraps the internal `T[]` array being rented from the pool. |
| 20 | +- Buffers rented from the pool are not cleared by default, which means that if they were not cleared when being previous returned to the pool, they might contain garbage data. Normally, users are required to clear these rented buffers manually, which can be verbose especially when done frequently. `MemoryOwner<T>` has a more flexible approach to this, through the `Allocate(int, AllocationMode)` API. This method not only allocates a new instance of exactly the requested size, but can also be used to specify which allocation mode to use: either the same one as `ArrayPool<T>`, or one that automatically clears the rented buffer. |
| 21 | +- There are cases where a buffer might be rented with a greater size than what is actually needed, and then resized afterwards. This would normally require users to rent a new buffer and copy the region of interest from the old buffer. Instead, `MemoryOwner<T>` exposes a `Slice(int, int)` API that simply return a new instance wrapping the specified area of interest. This allows to skip renting a new buffer and copying the items entirely. |
| 22 | + |
| 23 | +## Syntax |
| 24 | + |
| 25 | +Here is an example of how to rent a buffer and retrieve a `Memory<T>` instance: |
| 26 | + |
| 27 | +```csharp |
| 28 | +// Be sure to include this using at the top of the file: |
| 29 | +using Microsoft.Toolkit.HighPerformance.Buffers; |
| 30 | + |
| 31 | +using (MemoryOwner<int> buffer = MemoryOwner<int>.Allocate(42)) |
| 32 | +{ |
| 33 | + // Both memory and span have exactly 42 items |
| 34 | + Memory<int> memory = buffer.Memory; |
| 35 | + Span<int> span = buffer.Span; |
| 36 | + |
| 37 | + // Writing to the span modifies the underlying buffer |
| 38 | + span[0] = 42; |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +In this example, we used a `using` block to declare the `MemoryOwner<T>` buffer: this is particularly useful as the underlying array will automatically be returned to the pool at the end of the block. If instead we don't have direct control over the lifetime of a `MemoryOwner<T>` instance, the buffer will simply be returned to the pool when the object is finalized by the garbage collector. In both cases, rented buffers will always be correctly returned to the shared pool. |
| 43 | + |
| 44 | +## When should this be used? |
| 45 | + |
| 46 | +`MemoryOwner<T>` can be used as a general purpose buffer type, which has the advantage of minimizing the number of allocations done over time, as it internally reuses the same arrays from a shared pool. A common use case is to replace `new T[]` array allocations, especially when doing repeated operations that either require a temporary buffer to work on, or that produce a buffer as a result. |
| 47 | + |
| 48 | +Suppose we have a dataset consisting of a series of binary files, and that we need to read all these files and process them in some way. To properly separate our code, we might end up writing a method that simply reads one binary file, which might look like this: |
| 49 | + |
| 50 | +```csharp |
| 51 | +public static byte[] GetBytesFromFile(string path) |
| 52 | +{ |
| 53 | + using Stream stream = File.OpenRead(path); |
| 54 | + |
| 55 | + byte[] buffer = new byte[(int)stream.Length]; |
| 56 | + |
| 57 | + stream.Read(buffer, 0, buffer.Length); |
| 58 | + |
| 59 | + return buffer; |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +Note that `new byte[]` expression. If we read a large number of files, we'll end up allocating a lot of new arrays, which will put a lot of pressure over the garbage collector. We might want to refactor this code using buffers rented from a pool, like so: |
| 64 | + |
| 65 | +```csharp |
| 66 | +public static (byte[] Buffer, int Length) GetBytesFromFile(string path) |
| 67 | +{ |
| 68 | + using Stream stream = File.OpenRead(path); |
| 69 | + |
| 70 | + byte[] buffer = ArrayPool<T>.Shared.Rent((int)stream.Length); |
| 71 | + |
| 72 | + stream.Read(buffer, 0, (int)stream.Length); |
| 73 | + |
| 74 | + return (buffer, (int)stream.Length); |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +Using this approach, buffers are now rented from a pool, which means that in most cases we're able to skip an allocation. Additionally, since rented buffers are not cleared by default, we can also save the time needed to fill them with zeros, which gives us another small performance improvement. In the example above, loading 1000 files would bring the total allocation size from around 1MB down to just 1024 bytes - just a single buffer would effectively be allocated, and then reused automatically. |
| 79 | + |
| 80 | +There are two main issues with the code above: |
| 81 | +- `ArrayPool<T>` might return buffers that have a size greater than the requested one. To work around this issue, we need to return a tuple which also indicates the actual used size into our rented buffer. |
| 82 | +- By simply returning an array, we need to be extra careful to properly track its lifetime and to return it to the appropriate pool. We might work around this issue by using [`MemoryPool<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.buffers.memorypool-1) instead and by returning an `IMemoryOwner<T>` instance, but we still have the problem of rented buffers having a greater size than what we need. Additionally, `IMemoryOwner<T>` has some overhead when retrieving a `Span<T>` to work on, due to it being an interface, and the fact that we always need to get a `Memory<T>` instance first, and then a `Span<T>`. |
| 83 | + |
| 84 | +To solve both these issues, we can refactor this code again by using `MemoryOwner<T>`: |
| 85 | + |
| 86 | +```csharp |
| 87 | +public static MemoryOwner<byte> GetBytesFromFile(string path) |
| 88 | +{ |
| 89 | + using Stream stream = File.OpenRead(path); |
| 90 | + |
| 91 | + MemoryOwner<byte> buffer = MemoryOwner<byte>.Allocate((int)stream.Length); |
| 92 | + |
| 93 | + stream.Read(buffer.Span); |
| 94 | + |
| 95 | + return buffer; |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +The returned `IMemoryOwner<byte>` instance will take care of disposing the underlying buffer and returning it to the pool when its [`IDisposable.Dispose`](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable.dispose) method is invoked. We can use it to get a `Memory<T>` or `Span<T>` instance to interact with the loaded data, and then dispose the instance when we no longer need it. Additionally, all the `MemoryOwner<T>` properties (like `MemoryOwner<T>.Span`) respect the initial requested size we used, so we no longer need to manually keep track of the effective size within the rented buffer. |
| 100 | + |
| 101 | +## Properties |
| 102 | + |
| 103 | +| Property | Return Type | Description | |
| 104 | +| -- | -- | -- | |
| 105 | +| Length | int | Gets the number of items in the current instance | |
| 106 | +| Memory | System.Memory<T> | Gets the memory belonging to this owner | |
| 107 | +| Span | System.Span<T> | Gets a span wrapping the memory belonging to the current instance | |
| 108 | +| Empty | MemoryOwner<T> | Gets an empty `MemoryOwner<T>` instance | |
| 109 | + |
| 110 | +## Methods |
| 111 | + |
| 112 | +| Method | Return Type | Description | |
| 113 | +| -- | -- | -- | |
| 114 | +| Allocate(int) | Memory<T> | Creates a new `MemoryOwner<T>` instance with the specified parameters | |
| 115 | +| Allocate(int, AllocationMode) | Memory<T> | Creates a new `MemoryOwner<T>` instance with the specified parameters | |
| 116 | +| DangerousGetReference() | ref T | Returns a reference to the first element within the current instance, with no bounds check | |
| 117 | +| Slice(int, int) | MemoryOwner<T> | Slices the buffer currently in use and returns a new `MemoryOwner<T>` instance | |
| 118 | + |
| 119 | +## Sample Code |
| 120 | + |
| 121 | +You can find more examples in our [unit tests](https://github.com/Microsoft/WindowsCommunityToolkit//blob/master/UnitTests/UnitTests.HighPerformance.Shared/Buffers) |
| 122 | + |
| 123 | +## Requirements |
| 124 | + |
| 125 | +| Device family | Universal, 10.0.16299.0 or higher | |
| 126 | +| --- | --- | |
| 127 | +| Namespace | Microsoft.Toolkit.HighPerformance | |
| 128 | +| NuGet package | [Microsoft.Toolkit.HighPerformance](https://www.nuget.org/packages/Microsoft.Toolkit.HighPerformance/) | |
| 129 | + |
| 130 | +## API |
| 131 | + |
| 132 | +* [MemoryOwner<T> source code](https://github.com/Microsoft/WindowsCommunityToolkit//blob/master/Microsoft.Toolkit.HighPerformance/Buffers) |
0 commit comments