Class CollectionHelper

Provides helper methods for collections.

Inheritance

object

CollectionHelper

Namespace: Unity.Collections

Assembly: Unity.Collections.dll

Syntax

public static class CollectionHelper

Fields

CacheLineSize

The size in bytes of the current platform's L1 cache lines.

Declaration

public const int CacheLineSize = 64

Field Value

Type	Description
int	The size in bytes of the current platform's L1 cache lines.

Methods

Align(int, int)

Returns an allocation size in bytes that factors in alignment.

Declaration

public static int Align(int size, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
int	size	The size to align.
int	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
int	The smallest integer that is greater than or equal to size and is a multiple of alignmentPowerOfTwo.

Examples

  // 55 aligned to 16 is 64.
             int size = CollectionHelper.Align(55, 16);

Exceptions

Type	Condition
ArgumentException	Thrown if alignmentPowerOfTwo is not a non-zero, positive power of two.

Align(ulong, ulong)

Returns an allocation size in bytes that factors in alignment.

Declaration

public static ulong Align(ulong size, ulong alignmentPowerOfTwo)

Parameters

Type	Name	Description
ulong	size	The size to align.
ulong	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
ulong	The smallest integer that is greater than or equal to size and is a multiple of alignmentPowerOfTwo.

Examples

  // 55 aligned to 16 is 64.
             ulong size = CollectionHelper.Align(55, 16);

Exceptions

Type	Condition
ArgumentException	Thrown if alignmentPowerOfTwo is not a non-zero, positive power of two.

CheckReflectionDataCorrect<T>(IntPtr)

Checks that reflection data was properly registered for a job.

Declaration

[Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")]
[Conditional("UNITY_DOTS_DEBUG")]
public static void CheckReflectionDataCorrect<T>(IntPtr reflectionData)

Parameters

Type	Name	Description
IntPtr	reflectionData	The reflection data pointer.

Type Parameters

Name	Description
T	Job type

Remarks

This should be called before instantiating JobsUtility.JobScheduleParameters in order to report to the user if they need to take action.

ConvertExistingDataToNativeArray<T>(void*, int, AllocatorHandle, bool)

Convert existing data into a NativeArray.

Declaration

public static NativeArray<T> ConvertExistingDataToNativeArray<T>(void* dataPointer, int length, AllocatorManager.AllocatorHandle allocator, bool setTempMemoryHandle = false) where T : unmanaged

Parameters

Type	Name	Description
void*	dataPointer	Pointer to the data to be converted.
int	length	The count of elements.
AllocatorManager.AllocatorHandle	allocator	The Allocator to use.
bool	setTempMemoryHandle	Use temporary memory atomic safety handle.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

Remarks

The caller is still the owner of the data.

ConvertExistingNativeListToNativeArray<T>(ref NativeList<T>, int, AllocatorHandle)

Convert NativeList into a NativeArray.

Declaration

public static NativeArray<T> ConvertExistingNativeListToNativeArray<T>(ref NativeList<T> nativeList, int length, AllocatorManager.AllocatorHandle allocator) where T : unmanaged

Parameters

Type	Name	Description
NativeList<T>	nativeList	NativeList to be converted.
int	length	The count of elements.
AllocatorManager.AllocatorHandle	allocator	The Allocator to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

Remarks

There is a caveat if users would like to transfer memory ownership from the NativeList to the converted NativeArray. NativeList implementation includes two memory allocations, one holds its header, another holds the list data. After convertion, the converted NativeArray holds the list data and dispose the array only free the list data. Users need to manually free the list header to avoid memory leaks, for example after convertion call, AllocatorManager.Free(allocator, nativeList.m_ListData);

CreateNativeArray<T>(int, AllocatorHandle, NativeArrayOptions)

Create a NativeArray, using a provided AllocatorHandle.

Declaration

public static NativeArray<T> CreateNativeArray<T>(int length, AllocatorManager.AllocatorHandle allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory) where T : unmanaged

Parameters

Type	Name	Description
int	length	The number of elements to allocate.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.
NativeArrayOptions	options	Options for allocation, such as whether to clear the memory.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T>(NativeArray<T>, AllocatorHandle)

Create a NativeArray from another NativeArray, using a provided AllocatorHandle.

Declaration

public static NativeArray<T> CreateNativeArray<T>(NativeArray<T> array, AllocatorManager.AllocatorHandle allocator) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>	array	The NativeArray to make a copy of.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T>(T[], AllocatorHandle)

Create a NativeArray from a managed array, using a provided AllocatorHandle.

Declaration

[ExcludeFromBurstCompatTesting("Managed array")]
public static NativeArray<T> CreateNativeArray<T>(T[] array, AllocatorManager.AllocatorHandle allocator) where T : unmanaged

Parameters

Type	Name	Description
T[]	array	The managed array to make a copy of.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T, U>(int, ref U, NativeArrayOptions)

Create a NativeArray, using a provided allocator that implements IAllocator.

Declaration

public static NativeArray<T> CreateNativeArray<T, U>(int length, ref U allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory) where T : unmanaged where U : unmanaged, AllocatorManager.IAllocator

Parameters

Type	Name	Description
int	length	The number of elements to allocate.
U	allocator	The allocator to use.
NativeArrayOptions	options	Options for allocation, such as whether to clear the memory.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.
U	The type of allocator.

CreateNativeArray<T, U>(T[], ref U)

Create a NativeArray from a managed array, using a provided Allocator.

Declaration

[ExcludeFromBurstCompatTesting("Managed array")]
public static NativeArray<T> CreateNativeArray<T, U>(T[] array, ref U allocator) where T : unmanaged where U : unmanaged, AllocatorManager.IAllocator

Parameters

Type	Name	Description
T[]	array	The managed array to make a copy of.
U	allocator	The Allocator to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.
U	The type of allocator.

CreateNativeParallelMultiHashMap<TKey, TValue, U>(int, ref U)

Create a NativeParallelMultiHashMap from a managed array, using a provided Allocator.

Declaration

public static NativeParallelMultiHashMap<TKey, TValue> CreateNativeParallelMultiHashMap<TKey, TValue, U>(int length, ref U allocator) where TKey : unmanaged, IEquatable<TKey> where TValue : unmanaged where U : unmanaged, AllocatorManager.IAllocator

Parameters

Type	Name	Description
int	length	The desired capacity of the NativeParallelMultiHashMap.
U	allocator	The Allocator to use.

Returns

Type	Description
NativeParallelMultiHashMap<TKey, TValue>	Returns the NativeParallelMultiHashMap that was created.

Type Parameters

Name	Description
TKey	The type of the keys.
TValue	The type of the values.
U	The type of allocator.

CreateSafetyHandle(AllocatorHandle)

Creates a new AtomicSafetyHandle that is valid until [[CollectionHelper.DisposeSafetyHandle]] is called.

Declaration

public static AtomicSafetyHandle CreateSafetyHandle(AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.

Returns

Type	Description
AtomicSafetyHandle	Safety handle.

DisposeNativeArray<T>(NativeArray<T>, AllocatorHandle)

Dispose a NativeArray from an AllocatorHandle where it is allocated.

Declaration

public static void DisposeNativeArray<T>(NativeArray<T> nativeArray, AllocatorManager.AllocatorHandle allocator) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>	nativeArray	The NativeArray to make a copy of.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle used to allocate the NativeArray.

Type Parameters

Name	Description
T	The type of the elements.

DisposeSafetyHandle(ref AtomicSafetyHandle)

Disposes a previously created AtomicSafetyHandle.

Declaration

public static void DisposeSafetyHandle(ref AtomicSafetyHandle handle)

Parameters

Type	Name	Description
AtomicSafetyHandle	handle	Safety handle.

Dispose<T>(NativeArray<T>)

Dispose a NativeArray from an AllocatorHandle where it is allocated.

Declaration

public static void Dispose<T>(NativeArray<T> nativeArray) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>	nativeArray	The NativeArray to be disposed.

Type Parameters

Name	Description
T	The type of the elements.

Hash(void*, int)

Returns a (non-cryptographic) hash of a memory block.

Declaration

public static uint Hash(void* ptr, int bytes)

Parameters

Type	Name	Description
void*	ptr	A buffer.
int	bytes	The number of bytes to hash.

Returns

Type	Description
uint	A hash of the bytes.

Remarks

The hash function used is djb2.

IsAligned(ulong, int)

Returns true if an offset has a given alignment.

Declaration

public static bool IsAligned(ulong offset, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
ulong	offset	An offset
int	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
bool	True if the offset is a multiple of alignmentPowerOfTwo.

Exceptions

Type	Condition
ArgumentException	Thrown if alignmentPowerOfTwo is not a non-zero, positive power of two.

IsAligned(void*, int)

Returns true if the address represented by the pointer has a given alignment.

Declaration

public static bool IsAligned(void* p, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
void*	p	The pointer.
int	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
bool	True if the address is a multiple of alignmentPowerOfTwo.

Exceptions

Type	Condition
ArgumentException	Thrown if alignmentPowerOfTwo is not a non-zero, positive power of two.

IsPowerOfTwo(int)

Returns true if a positive value is a non-zero power of two.

Declaration

public static bool IsPowerOfTwo(int value)

Parameters

Type	Name	Description
int	value	A positive value.

Returns

Type	Description
bool	True if the value is a non-zero, positive power of two.

Remarks

Result is invalid if value < 0.

Log2Ceil(int)

Returns the binary logarithm of the value, but the result is rounded up to the nearest integer.

Declaration

public static int Log2Ceil(int value)

Parameters

Type	Name	Description
int	value	The value.

Returns

Type	Description
int	The binary logarithm of the value, but the result is rounded up to the nearest integer.

Log2Floor(int)

Returns the binary logarithm of the value, but the result is rounded down to the nearest integer.

Declaration

public static int Log2Floor(int value)

Parameters

Type	Name	Description
int	value	The value.

Returns

Type	Description
int	The binary logarithm of the value, but the result is rounded down to the nearest integer.

SetStaticSafetyId(ref AtomicSafetyHandle, ref int, FixedString512Bytes)

Assigns the provided static safety ID to an [[AtomicSafetyHandle]]. The ID's owner type name and any custom error messages are used by the job debugger when reporting errors involving the target handle.

Declaration

public static void SetStaticSafetyId(ref AtomicSafetyHandle handle, ref int sharedStaticId, FixedString512Bytes name)

Parameters

Type	Name	Description
AtomicSafetyHandle	handle	Safety handle.
int	sharedStaticId	The static safety ID to associate with the provided handle. This ID must have been allocated with ::ref::NewStaticSafetyId.
FixedString512Bytes	name	The name of the resource type.

Remarks

This is preferable to AtomicSafetyHandle.NewStaticSafetyId as it is compatible with burst.

SetStaticSafetyId<T>(ref AtomicSafetyHandle, ref int)

Assigns the provided static safety ID to an [[AtomicSafetyHandle]]. The ID's owner type name and any custom error messages are used by the job debugger when reporting errors involving the target handle.

Declaration

public static void SetStaticSafetyId<T>(ref AtomicSafetyHandle handle, ref int sharedStaticId)

Parameters

Type	Name	Description
AtomicSafetyHandle	handle	Safety handle.
int	sharedStaticId	The static safety ID to associate with the provided handle. This ID must have been allocated with ::ref::NewStaticSafetyId.

Type Parameters

Name	Description
T	Type of container safety handle refers to.

Remarks

This is preferable to AtomicSafetyHandle.NewStaticSafetyId as it is compatible with burst.