Method AllocateDisjointedBuffer

AllocateDisjointedBuffer(ref FixedList64Bytes<ushort>, NativeList<PayloadHandle>)

Allocates a new Disjointed buffer, which includes allocating the individual Payloads that make up the entire buffer.

Declaration

public PayloadHandle AllocateDisjointedBuffer(ref FixedList64Bytes<ushort> payloadSizes, NativeList<PayloadHandle> payloadHandles = default)

Parameters

Type	Name	Description
FixedList64Bytes<ushort>	payloadSizes	Set of buffer sizes to allocate for each Payload that comprises the DisjointedBuffer.
NativeList<PayloadHandle>	payloadHandles	Optional list that receives the PayloadHandle values for each Payload allocated by this method.

Returns

Type	Description
PayloadHandle	If successful, a valid PayloadHandle to the DisjointedBuffer's head.

Remarks

A 'Disjointed' buffer is a set of individual Payload buffers that are collectively treated as a single buffer; it's similar to a Jagged Array or can be thought of as an "array of arrays". Internally, the Disjointed buffer is implemented by a "head" buffer that holds PayloadHandle values referencing one or more Payloads, which hold the actual data. A single handle to the head buffer, referencing all the individual payloads, which can be passed within a single LogMessage component. As the name Disjointed suggests, the memory for the Payloads themselves is not contiguous (similar to a Jagged Array) and therefore each Payload buffer must be retrieved and accessed separately.

Disjointed buffers can either be allocated up front via this Method or created from existing Payloads via CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle>). Regardless, as with regular allocations, the buffer must be released by calling ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, bool) on the PayloadHandle returned by this method. Failure to do so will result in a "leak" of payload allocations; not just for the head buffer but all allocations that make up the DisjointedBuffer.

When using this method, the individual Payload buffers are automatically allocated using the passed in size values. All Payload allocations sizes (including the head buffer) must fall within the MinimumPayloadSize and MaximumPayloadSize range. This means the total size of a Disjointed buffer is limited to MaximumDisjointedPayloadCount, which is the number of PayloadHandle values that can fit into a single payload allocation. Payload allocations do not have to come from the same memory source, e.g. they can be allocated from the Default or Overflow RingBuffers. Payload data can be retrieved by calling RetrieveDisjointedPayloadBuffer(PayloadHandle, int, bool, out NativeArray<byte>) on the Disjointed handle or by directly calling RetrievePayloadBuffer(PayloadHandle, bool, out NativeArray<byte>) on the Payload handles stored in the head buffer.

IMPORTANT: If any of the allocations (including the head buffer) fail, the entire operation is aborted and any allocated memory is released. However that memory won't be available for new allocations until after it's been reclaimed by a call to Update(). This means, an attempt to allocate too much memory may result in a significant waste of available space causing other allocation requests to fail.

Disjointed buffers are intended for the following scenarios:

• Payload data exceeds the maximum Payload size and must be broken up into multiple pieces
• The entire Payload data size isn't known up front and must be allocated in different stages
• Additional data needs to be "appended" to an existing payload but without needing to completely reallocate a new buffer

In general, Disjointed buffers should be treated as a single allocation and the individual Payloads that make up the buffer should only be used for immediate reading/writing data. It's recommended to follow these guidelines:

• Do not store or pass the individual Payload handles; only the head handle (returned by this method) should be stored
• Do not release the individual payload allocations; all Disjointed memory is released through the head allocation
• Do not call LockPayloadBuffer(PayloadHandle) on individual payload handle; only the head buffer should be locked
• Do not use a given Payload allocation in multiple Disjointed buffers
• Do not use a Disjointed head handle within another Disjointed buffer (unsupported scenario)

NOTE: These rules are not generally not checked nor enforced, and any validation that is performed only occurs when ENABLE_UNITY_COLLECTIONS_CHECKS or UNITY_DOTS_DEBUG is enabled.

AllocateDisjointedBuffer(ref FixedList512Bytes<ushort>, NativeList<PayloadHandle>)

Allocates a new Disjointed buffer, which includes allocating the individual Payloads that make up the entire buffer.

Declaration

public PayloadHandle AllocateDisjointedBuffer(ref FixedList512Bytes<ushort> payloadSizes, NativeList<PayloadHandle> payloadHandles = default)

Parameters

Type	Name	Description
FixedList512Bytes<ushort>	payloadSizes	Set of buffer sizes to allocate for each Payload that comprises the DisjointedBuffer.
NativeList<PayloadHandle>	payloadHandles	Optional list that receives the PayloadHandle values for each Payload allocated by this method.

Returns

Type	Description
PayloadHandle	If successful, a valid PayloadHandle to the DisjointedBuffer's head.

AllocateDisjointedBuffer(ref NativeList<ushort>, NativeList<PayloadHandle>)

Allocates a new Disjointed buffer, which includes allocating the individual Payloads that make up the entire buffer.

Declaration

public PayloadHandle AllocateDisjointedBuffer(ref NativeList<ushort> payloadSizes, NativeList<PayloadHandle> payloadHandles = default)

Parameters

Type	Name	Description
NativeList<ushort>	payloadSizes	Set of buffer sizes to allocate for each Payload that comprises the DisjointedBuffer.
NativeList<PayloadHandle>	payloadHandles	Optional list that receives the PayloadHandle values for each Payload allocated by this method.

Returns

Type	Description
PayloadHandle	If successful, a valid PayloadHandle to the DisjointedBuffer's head.