Struct UnsafePayloadRingBuffer

Logging system's primary container for allocating Payload buffers.

Inherited Members

ValueType.Equals(Object)

ValueType.GetHashCode()

ValueType.ToString()

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetType()

Namespace: Unity.Logging

Syntax

[BurstCompile]
public struct UnsafePayloadRingBuffer : IDisposable

Remarks

This container provides the backing memory for message buffers referenced by LogMessage. It allows fast, thread-safe allocations from a pre-allocated array of native memory, which can be safely accessed by a PayloadHandle value.

This container is utilized internally by LogMemoryManager, and in general it's unnecessary to directly call into it. However, it may be used directly in advanced memory scenarios.

Constructors

UnsafePayloadRingBuffer(UInt32, Byte, Allocator)

Initializes a new instance of the container.

Declaration

public UnsafePayloadRingBuffer(uint capacity, byte bufferId, Allocator allocator = Allocator.Persistent)

Parameters

Type	Name	Description
UInt32	capacity	Size of the container in bytes, must be in the range of MinimumCapacity and MaximumCapacity.
Byte	bufferId	User specified value that identifies this instance.
Allocator	allocator	Memory pool to allocate the containers from.

Fields

AlignTo

Power of 2 align value used in RoundToNextAlign(UInt32)

Declaration

public const uint AlignTo = 8U

Field Value

Type	Description
UInt32

BufferId

Unique ID value assigned by the user which identifies PayloadHandle as referencing allocations from this instance.

Declaration

public readonly byte BufferId

Field Value

Type	Description
Byte

MaximumCapacity

Maximum capacity of the container.

Declaration

public const uint MaximumCapacity = 134217728U

Field Value

Type	Description
UInt32

Remarks

Limit capacity to max 2^27 bytes == 134 mb because RingBuffer's arithmetic (Distance) uses signed 32-bit int and we don't want to crash in 32 bit platforms, also too much will crash with OOM

MaximumPayloadSize

Maximum size for a single Payload block (excludes header) that can be allocated.

Declaration

public const uint MaximumPayloadSize = 32768U

Field Value

Type	Description
UInt32

MinimumCapacity

Minimum capacity of the container.

Declaration

public const uint MinimumCapacity = 1024U

Field Value

Type	Description
UInt32

Remarks

In order to function properly the RingBuffer requires minimum capacity of 1K.

MinimumPayloadSize

Minimum size for a single Payload block (excludes header) that can be allocated.

Declaration

public const uint MinimumPayloadSize = 4U

Field Value

Type	Description
UInt32

Properties

BytesAllocated

Total number of bytes currently allocated from the RingBuffer, including payload headers.

Declaration

public readonly uint BytesAllocated { get; }

Property Value

Type	Description
UInt32

BytesAllocatedMax

Max value of BytesAllocated that was registered.

Declaration

public readonly uint BytesAllocatedMax { get; }

Property Value

Type	Description
UInt32

Capacity

Capacity of the RingBuffer, which cannot change after RingBuffer has been initialized

Declaration

public readonly uint Capacity { get; }

Property Value

Type	Description
UInt32

IsCreated

Returns true if RingBuffer is initialized and not Disposed.

Declaration

public readonly bool IsCreated { get; }

Property Value

Type	Description
Boolean

MaximumDisjointedPayloadCount

Returns the maximum number of Payloads that can be referenced within a single DisjointedBuffer.

Declaration

public static readonly uint MaximumDisjointedPayloadCount { get; }

Property Value

Type	Description
UInt32

Remarks

The MaximumPayloadSize determines how may PayloadHandle values can fit into the "head" buffer and therefore the maximum number of payloads that can be referenced.

Methods

AllocatePayload(UInt32, out PayloadHandle, out NativeArray<Byte>, Boolean)

Allocate a block of memory from the container.

Declaration

public bool AllocatePayload(uint requestedSize, out PayloadHandle payloadHandle, out NativeArray<byte> payloadArray, bool disjointedBuffer = false)

Parameters

Type	Name	Description
UInt32	requestedSize	Size of memory block in bytes to allocate.
PayloadHandle	payloadHandle	Handle to the memory block, if allocation was successful.
NativeArray<Byte>	payloadArray	NativeArray allowing read/write access into the memory block.
Boolean	disjointedBuffer	True to specify allocation is the "head" of a Disjointed Payload.

Returns

Type	Description
Boolean	True if allocation was successful and false if not

Remarks

Actual size of the allocation is slightly larger than requestedSize, as additional bytes are needed for the memory block's header.

DebugDetailsOfPayloadHandle(PayloadHandle)

Debug function that returns details about a particular PayloadHandle.

Declaration

public FixedString4096Bytes DebugDetailsOfPayloadHandle(PayloadHandle blockHandle)

Parameters

Type	Name	Description
PayloadHandle	blockHandle	PayloadHandle to analyze

Returns

Type	Description
FixedString4096Bytes	FixedString4096Bytes with the details

Dispose()

Frees the container's memory and returns this instance to an uninitialized state.

Declaration

public void Dispose()

Implements

IDisposable.Dispose()

Remarks

This must be called from the main thread.

IsPayloadHandleValid(PayloadHandle)

Checks if the specified handle currently references a valid memory block.

Declaration

public bool IsPayloadHandleValid(PayloadHandle blockHandle)

Parameters

Type	Name	Description
PayloadHandle	blockHandle	A PayloadHandle value to check.

Returns

Type	Description
Boolean	True if the handle references a valid memory block and false if not.

Remarks

Use this method to quickly check the validity of a handle value without the overhead of creating a NativeArray. A valid handle means it references an allocated memory block and that block hasn't yet been released.

ReclaimReleasedPayloadBlocks()

Reclaims any and all freed memory blocks from the "tail" of the RingBuffer.

Declaration

public void ReclaimReleasedPayloadBlocks()

Remarks

Released memory doesn't actually become available for new allocations until this is called. It must be called from the main thread, typically once per frame.

ReleasePayload(PayloadHandle)

Releases the memory block referenced by the specified handle.

Declaration

public bool ReleasePayload(PayloadHandle payloadHandle)

Parameters

Type	Name	Description
PayloadHandle	payloadHandle	Handle value that references the memory block to be released.

Returns

Type	Description
Boolean	True if successful and false if not.

Remarks

This method doesn't actually release the memory but instead marks the block as being "freed". The memory is actually released by ReclaimReleasedPayloadBlocks(), which must be called from a system Update.

RetrievePayloadFromHandle(PayloadHandle, Boolean, out NativeArray<Byte>)

Retrieves a NativeArray for the allocated memory block referenced by the specified handle.

Declaration

public bool RetrievePayloadFromHandle(PayloadHandle blockHandle, bool readWriteAccess, out NativeArray<byte> blockArray)

Parameters

Type	Name	Description
PayloadHandle	blockHandle	Valid handle to the memory block to retrieve.
Boolean	readWriteAccess	True to give read-write access to the NativeArray and false for read-only access.
NativeArray<Byte>	blockArray	If successful, NativeArray as a view into the memory block.

Returns

Type	Description
Boolean	True if successfully retrieved memory block and false if not.

Remarks

The returned NativeArray is a view into the allocated memory block and not a copy, allows for safe access to them memory block. Access to the NativeArray can be specified as either read-only or read-write.

NOTE: Since the NativeArray is a view into a segment of native memory, a buffer overrun will corrupt the container causing undefined behavior.

RetrievePayloadFromHandle(PayloadHandle, out NativeArray<Byte>)

Retrieves a NativeArray for the allocated memory block referenced by the specified handle.

Declaration

public bool RetrievePayloadFromHandle(PayloadHandle blockHandle, out NativeArray<byte> blockArray)

Parameters

Type	Name	Description
PayloadHandle	blockHandle	Valid handle to the memory block to retrieve.
NativeArray<Byte>	blockArray	If successful, NativeArray as a view into the memory block.

Returns

Type	Description
Boolean	True if successfully retrieved memory block and false if not.

Remarks

NativeArray is read-only. See RetrievePayloadFromHandle(PayloadHandle, Boolean, out NativeArray<Byte>).

RoundToNextAlign(UInt32)

Changes the input size to the size that is aligned to AlignTo bytes

Declaration

public static uint RoundToNextAlign(uint requestedSize)

Parameters

Type	Name	Description
UInt32	requestedSize	Input size to align

Returns

Type	Description
UInt32	Aligned size