A low-allocation collection library using pooled arrays
Basic Usage
// By using the `using` statement, it will be automatically returned to the pool.
using var dict = new ArrayPoolDictionary<int, string>();
// Can be used in the same way as a Dictionary
dict.Add(123, "Alice");
Console.WriteLine(dict[123]); // "Alice"
Install
ArrayPoolCollection can be installed from NuGet AndanteSoft.ArrayPoolCollection.
They use ArrayPool<T> for their internal arrays, and by calling Dispose() when destroyed, they do not generate GC garbage.
These implement almost all APIs available as of .NET 9.
Therefore, it can also be used to utilize PriorityQueue, which was not available in the current Unity environment.
Example of Dictionary usage:
using var dict = new ArrayPoolDictionary<string, string>(new Utf8BytesComparer())
{
{ "Alice", "Supernova" }
};
// You can use GetAlternateLookup in Unity.
// Unfortunately, it is not a `allows ref struct` constraint, so
// `ReadOnlySpan<byte>` cannot be taken as an argument.
Debug.Log(dict["Alice"]); // "Supernova"
Debug.Log(dict.GetAlternateLookup<byte[]>()[Encoding.UTF8.GetBytes("Alice")]); // "Supernova"
private class Utf8BytesComparer : IEqualityComparer<string>, IAlternateEqualityComparer<byte[], string>
{
public string Create(byte[] alternate)
{
return Encoding.UTF8.GetString(alternate);
}
public bool Equals(byte[] alternate, string other)
{
return Encoding.UTF8.GetBytes(other).SequenceEqual(alternate);
}
public bool Equals(string x, string y)
{
return x.Equals(y);
}
public int GetHashCode(byte[] alternate)
{
return Encoding.UTF8.GetString(alternate).GetHashCode();
}
public int GetHashCode(string obj)
{
return obj.GetHashCode();
}
}
In addition, it implements the following alternative collections, although they have some differences in specifications:
Reason: It's an old collection and the design is old.
For example, And and Xor returns void to indicate that they are mutable.
Also, BitArray only implements ICollection (non-generic!), while ArrayPoolBits implements IList<bool>.
Also implement an object pool:
ObjectPool
By utilizing this and reusing instances of ArrayPool***, GC garbage can be completely eliminated.
This is also available in the pool of GameObjects in Unity.
// Get a dictionary from the pool
var dict = ObjectPool<ArrayPoolDictionary<int, string>>.Shared.Rent();
// The contents of the rented dictionary are undefined, so clear it.
dict.Clear();
// Then use it just like a normal Dictionary.
dict.Add(123, "Alice");
dict.Add(456, "Barbara");
dict.Add(789, "Charlotte");
Debug.Log($"{dict[123]}"); // "Alice"
// Return it when you're done using it
ObjectPool<ArrayPoolDictionary<int, string>>.Shared.Return(dict);
Example of pooling GameObject in Unity:
var root = new GameObject("root");
// Create GameObjectPool
using var gameObjectPool = new ObjectPool<GameObject>(PooledObjectCallback<GameObject>.Create(
// OnInstantiate - create prefab
() =>
{
var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
go.transform.SetParent(root.transform, false);
return go;
},
// OnRent - set active
go => go.SetActive(true),
// OnReturn - set inactive
go => go.SetActive(false),
// OnDestroy - destroy
go => Destroy(go)
));
// Generate a specified number of pieces in advance
gameObjectPool.Prewarm(16);
for (int i = 0; i < 64; i++)
{
// Rent & Return
var go = gameObjectPool.Rent();
go.transform.position = UnityEngine.Random.insideUnitSphere * 10;
UniTask.Delay(1000).ContinueWith(() => gameObjectPool.Return(go)).Forget();
await UniTask.Delay(50);
}
await UniTask.Delay(1000);
It also includes an efficient implementation of IBufferWriter<T> that utilizes a pool.
ArrayPoolBufferWriter<T> : Suitable for small or fixed size buffers.
ArrayPoolSegmentedBufferWriter<T> : Suitable for objects of variable length and larger than megabytes.
// Call this once at the beginning
ArrayPoolCollectionRegisterer.Register();
using var list = new ArrayPoolList<string>()
{
"Alice", "Barbara", "Charlotte",
};
// Create IBufferWriter<byte>
using var writer = new ArrayPoolBufferWriter<byte>();
// Serialize the list
MemoryPackSerializer.Serialize(writer, list);
// Deserialize the list
var deserialized = MemoryPackSerializer.Deserialize<ArrayPoolList<string>>(writer.WrittenSpan);
// "Alice, Barbara, Charlotte"
Debug.Log(string.Join(", ", deserialized));
Notes:
ArrayPoolPriorityQueue do not implement IEnumerable<T>, so serialization requires the [MemoryPackAllowSerialize] attribute.
Comparer of Dictionary/HashSet is not usually serializable, so it is not saved. If you want to save it, you need to overwrite it when serializing.
using var ignoreCase = new ArrayPoolDictionary<string, int>(StringComparer.OrdinalIgnoreCase)
{
{ "Alice", 16 },
};
byte[] bytes = MemoryPackSerializer.Serialize(ignoreCase);
// ---
var deserialized = new ArrayPoolDictionary<string, int>(StringComparer.OrdinalIgnoreCase);
MemoryPackSerializer.Deserialize(bytes, ref deserialized);
Debug.Log($"{deserialized["alice"]}"); // 16
Fork
Build
dotnet build
Run tests
dotnet test
Run benchmarks
dotnet run -c Release --project ArrayPoolCollection.Benchmarks
