docs.unity3d.com
    Show / Hide Table of Contents

    Struct LogMemoryManager

    Interface for allocating and managing Payload buffers for LogMessage.

    Inherited Members
    ValueType.Equals(Object)
    ValueType.GetHashCode()
    ValueType.ToString()
    Object.Equals(Object, Object)
    Object.ReferenceEquals(Object, Object)
    Object.GetType()
    Namespace: Unity.Logging
    Syntax
    [BurstCompile]
    [GenerateTestsForBurstCompatibility]
    public struct LogMemoryManager
    Remarks

    A Payload buffer is allocated when creating a new log message, the actual message data, i.e. the "Payload", is serialized into this buffer by the log producer. A PayloadHandle references the allocated memory and is later used by a Listener to access the buffer and de-serialize the message data. After the message has been processed by a Listener, the Payload buffer must be released, typically performed automatically by LogController.

    Fields

    MaximumRingBufferGrowFactor

    Maximum value for BufferGrowFactor

    Declaration
    public const float MaximumRingBufferGrowFactor = 1000F
    Field Value
    Type Description
    Single

    MaximumRingBufferGrowThreshold

    Maximum value for BufferGrowThreshold

    Declaration
    public const float MaximumRingBufferGrowThreshold = 1F
    Field Value
    Type Description
    Single

    MaximumRingBufferSampleCount

    Maximum value for BufferSampleCount

    Declaration
    public const uint MaximumRingBufferSampleCount = 10000U
    Field Value
    Type Description
    UInt32

    MaximumRingBufferShrinkFactor

    Maximum value for BufferShrinkFactor

    Declaration
    public const float MaximumRingBufferShrinkFactor = 1F
    Field Value
    Type Description
    Single

    MaximumRingBufferShrinkThreshold

    Maximum value for BufferShrinkThreshold

    Declaration
    public const float MaximumRingBufferShrinkThreshold = 1F
    Field Value
    Type Description
    Single

    MinimumRingBufferGrowFactor

    Minimum value for BufferGrowFactor

    Declaration
    public const float MinimumRingBufferGrowFactor = 1F
    Field Value
    Type Description
    Single

    MinimumRingBufferGrowThreshold

    Minimum value for BufferGrowThreshold

    Declaration
    public const float MinimumRingBufferGrowThreshold = 0F
    Field Value
    Type Description
    Single

    MinimumRingBufferShrinkFactor

    Minimum value for BufferShrinkFactor

    Declaration
    public const float MinimumRingBufferShrinkFactor = 0.01F
    Field Value
    Type Description
    Single

    MinimumRingBufferShrinkThreshold

    Minimum value for BufferShrinkThreshold

    Declaration
    public const float MinimumRingBufferShrinkThreshold = 0F
    Field Value
    Type Description
    Single

    Properties

    IsInitialized

    Returns if this LogMemoryManager instance is currently initialized.

    Declaration
    public readonly bool IsInitialized { get; }
    Property Value
    Type Description
    Boolean

    Parameters

    Parameter values provided to Initialize(LogMemoryManagerParameters).

    Declaration
    public readonly LogMemoryManagerParameters Parameters { get; }
    Property Value
    Type Description
    LogMemoryManagerParameters

    Methods

    AllocateDisjointedBuffer(ref FixedList512Bytes<UInt16>, 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(NativeList<PayloadHandle>))
    Parameters
    Type Name Description
    FixedList512Bytes<UInt16> 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 FixedList64Bytes<UInt16>, 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(NativeList<PayloadHandle>))
    Parameters
    Type Name Description
    FixedList64Bytes<UInt16> 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, Boolean) 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, Int32, Boolean, out NativeArray<Byte>) on the Disjointed handle or by directly calling RetrievePayloadBuffer(PayloadHandle, Boolean, 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 NativeList<UInt16>, 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(NativeList<PayloadHandle>))
    Parameters
    Type Name Description
    NativeList<UInt16> 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.

    AllocatePayloadBuffer(UInt32)

    Allocates a new Payload buffer from the default Payload container.

    Declaration
    public PayloadHandle AllocatePayloadBuffer(uint payloadSize)
    Parameters
    Type Name Description
    UInt32 payloadSize

    Number of bytes to allocate; must fall within the range of MinimumPayloadSize and MaximumPayloadSize.

    Returns
    Type Description
    PayloadHandle

    A valid PayloadHandle if successful.

    AllocatePayloadBuffer(UInt32, out NativeArray<Byte>)

    Allocates a new Payload buffer from the default Payload container.

    Declaration
    public PayloadHandle AllocatePayloadBuffer(uint payloadSize, out NativeArray<byte> buffer)
    Parameters
    Type Name Description
    UInt32 payloadSize

    Number of bytes to allocate; must fall within the range of MinimumPayloadSize and MaximumPayloadSize.

    NativeArray<Byte> buffer

    NativeArray that allows safe access to the allocated Payload buffer

    Returns
    Type Description
    PayloadHandle

    A valid PayloadHandle if successful.

    Remarks

    If successful a PayloadHandle referencing the allocated memory is returned, and a NativeArray with read/write access (as a view into the buffer) is passed out. If allocation fails an invalid handle and buffer are returned.

    The PayloadHandle must be saved, as it's needed to retrieve the payload buffer again and also to release it. However, the passed out NativeArray is only intended for immediate reading/writing into the buffer; the variable must not be saved.

    IMPORTANT: The Payload buffer must eventually be released by calling ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean) Failure to do so will cause a "leak" in the Payload container.

    NOTE: Do not call Dispose on the returned NativeArray; it's only a view into the Payload buffer.

    CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList4096Bytes<PayloadHandle>)

    Creates a new Disjointed buffer that's composed of preallocated Payloads, instead of allocating new ones.

    Declaration
    public PayloadHandle CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList4096Bytes<PayloadHandle> payloadHandles)
    Parameters
    Type Name Description
    FixedList4096Bytes<PayloadHandle> payloadHandles

    Set a PayloadHandle values referencing Payload buffers that'll compose the new Disjointed buffer.

    Returns
    Type Description
    PayloadHandle

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

    Remarks

    See CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle>).

    CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle>)

    Creates a new Disjointed buffer that's composed of preallocated Payloads, instead of allocating new ones.

    Declaration
    public PayloadHandle CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle> payloadHandles)
    Parameters
    Type Name Description
    FixedList512Bytes<PayloadHandle> payloadHandles

    Set a PayloadHandle values referencing Payload buffers that'll compose the new Disjointed buffer.

    Returns
    Type Description
    PayloadHandle

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

    Remarks

    See AllocateDisjointedBuffer(ref FixedList64Bytes<UInt16>, NativeList<PayloadHandle>) for a general overview on "Disjointed" payload buffers.

    Use this method to group a set of Payload buffers that have already been allocated into a single Disjointed buffer. In this case, only the "head" payload needs to be allocated, which is then filled with the specified PayloadHandle value. A handle to the new head buffer is returned just as with AllocateDisjointedBuffer(ref FixedList64Bytes<UInt16>, NativeList<PayloadHandle>).

    Disjointed buffers created this way should be treated exactly the same as those allocated up front; the individual Payloads are now part of the whole buffer and should only be used for immediate reading/writing of data. Likewise, calling ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean) on the returned handle will now automatically release all the individual Payload buffers as well.

    NOTE: The PayloadHandle values passed into this method must reference valid Payload buffers and cannot be themselves handles to Disjointed buffers. However, the handles are only validated when ENABLE_UNITY_COLLECTIONS_CHECKS or UNITY_DOTS_DEBUG are enabled.

    CreateDisjointedPayloadBufferFromExistingPayloads(ref NativeList<PayloadHandle>)

    Creates a new Disjointed buffer that's composed of preallocated Payloads, instead of allocating new ones.

    Declaration
    public PayloadHandle CreateDisjointedPayloadBufferFromExistingPayloads(ref NativeList<PayloadHandle> payloadHandles)
    Parameters
    Type Name Description
    NativeList<PayloadHandle> payloadHandles

    Set a PayloadHandle values referencing Payload buffers that'll compose the new Disjointed buffer.

    Returns
    Type Description
    PayloadHandle

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

    Remarks

    See CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle>).

    DebugDetailsOfPayloadHandle(ref PayloadHandle)

    Debug function that returns information about PayloadHandle

    Declaration
    public FixedString4096Bytes DebugDetailsOfPayloadHandle(ref PayloadHandle handle)
    Parameters
    Type Name Description
    PayloadHandle handle

    PayloadHandle to analyze

    Returns
    Type Description
    FixedString4096Bytes

    FixedString that contains debug information

    DebugStateString(FixedString128Bytes)

    Gathers the internal statistics of this LogMemoryManager

    Declaration
    public FixedString4096Bytes DebugStateString(FixedString128Bytes name = default(FixedString128Bytes))
    Parameters
    Type Name Description
    FixedString128Bytes name

    Optional name of the log memory manager

    Returns
    Type Description
    FixedString4096Bytes

    FixedString4096Bytes that contains debug internal state of this manager

    FromPointer(IntPtr)

    Converts pointer into ref LogMemoryManager

    Declaration
    public static ref LogMemoryManager FromPointer(IntPtr memoryManager)
    Parameters
    Type Name Description
    IntPtr memoryManager

    IntPtr that should reference LogMemoryManager. Cannot be null

    Returns
    Type Description
    LogMemoryManager

    LogMemoryManager converted from a pointer

    GetCurrentDefaultBufferCapacity()

    Returns the Capacity of the current Payload container from which Payloads are allocated from.

    Declaration
    public uint GetCurrentDefaultBufferCapacity()
    Returns
    Type Description
    UInt32

    Capacity of the current Payload container from which Payloads are allocated from.

    Remarks

    During a Resize operation 2 containers are used: an "active" one which holds the new size and the "old" one which holds the previous allocations that haven't yet been released. Only the Capacity from the "active" container is returned; the Overflow buffer is never included.

    GetCurrentDefaultBufferUsage()

    Returns the Usage of the current Payload container from which Payloads are allocated from.

    Declaration
    public uint GetCurrentDefaultBufferUsage()
    Returns
    Type Description
    UInt32

    Usage of the current Payload container from which Payloads are allocated from.

    Remarks

    During a Resize operation 2 containers are used: an "active" one which holds the new size and the "old" one which holds the previous allocations that haven't yet been released. Only the Usage from the "active" container is returned; the Overflow buffer is never included.

    Initialize()

    Initializes MemoryManager using default parameters.

    Declaration
    public void Initialize()
    Remarks

    See Initialize(LogMemoryManagerParameters).

    Initialize(LogMemoryManagerParameters)

    Initializes MemoryManager with the specified set of parameters.

    Declaration
    public void Initialize(LogMemoryManagerParameters parameters)
    Parameters
    Type Name Description
    LogMemoryManagerParameters parameters

    LogMemoryManagerParameters structure that contains specified parameters

    Remarks

    Parameter values must fall within the specified minimum/maximum ranges, and invalid parameters are replaced with their corresponding default value.

    IsPayloadBufferLocked(PayloadHandle)

    Tests if the specified Payload buffer is locked and returns the number of individual locks.

    Declaration
    public bool IsPayloadBufferLocked(PayloadHandle handle)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to test.

    Returns
    Type Description
    Boolean

    True if Payload buffer has at least 1 lock and false otherwise.

    Remarks

    See IsPayloadBufferLocked(PayloadHandle, out Int32).

    IsPayloadBufferLocked(PayloadHandle, out Int32)

    Tests if the specified Payload buffer is locked and returns the number of individual locks.

    Declaration
    public bool IsPayloadBufferLocked(PayloadHandle handle, out int numLockContexts)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to test.

    Int32 numLockContexts

    Number of active locks on this Payload buffer.

    Returns
    Type Description
    Boolean

    True if Payload buffer has at least 1 lock and false otherwise.

    See Also
    LockPayloadBuffer(PayloadHandle)
    UnlockPayloadBuffer(PayloadHandle, PayloadLockContext)
    ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean)

    IsPayloadHandleValid(PayloadHandle)

    Tests if PayloadHandle references a valid Payload buffer or not.

    Declaration
    public bool IsPayloadHandleValid(PayloadHandle handle)
    Parameters
    Type Name Description
    PayloadHandle handle

    PayloadHandle value to test for validity.

    Returns
    Type Description
    Boolean

    True if handle references a valid Payload buffer and false if not.

    Remarks

    Unlike IsValid, which only tests if the handle value is valid, this verifies the handle currently references a valid Payload buffer.

    LockPayloadBuffer(PayloadHandle)

    Adds a "Lock" on the specified Payload buffer, preventing it from being released while the lock is active.

    Declaration
    public PayloadLockContext LockPayloadBuffer(PayloadHandle handle)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to lock.

    Returns
    Type Description
    PayloadLockContext

    If successful, a valid PayloadLockContext is returned.

    Remarks

    Only active Payload buffers can be locked; this method will fail if the buffer has already been released. Multiple locks can be applied to the same buffer simultaneously, (distinguished by a "context" value) but is limited to a max of 64.

    Each successful "lock" operation generates a PayloadLockContext value, which must be saved and later used to unlock the Payload buffer.

    The purpose of Payload Locks is to coordinate multiple log Listeners sharing the same payload memory, so the buffer is only released once all Listeners are finished. Upon receiving a LogMessage, a Listener immediately calls this method to lock the buffer, then processes and outputs the log data, and finally releases the lock when finished. This ensures the buffer isn't released prematurely while a Listener is still accessing the memory.

    See Also
    UnlockPayloadBuffer(PayloadHandle, PayloadLockContext)
    IsPayloadBufferLocked(PayloadHandle, out Int32)
    ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean)

    ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean)

    Releases the Payload memory allocated within the default Payload container.

    Declaration
    public bool ReleasePayloadBuffer(PayloadHandle handle, out PayloadReleaseResult result, bool force = false)
    Parameters
    Type Name Description
    PayloadHandle handle

    The PayloadHandle referencing the Payload buffer to release.

    PayloadReleaseResult result

    A detailed result code from PayloadReleaseResult.

    Boolean force

    Forces release of the Payload buffer even if it can't be performed "cleanly".

    Returns
    Type Description
    Boolean

    True if the payload buffer specifically referenced by the handle is released and false if not. For DisjointedBuffers, true is only returned if the "head" buffer is actually released. Valid Payloads referenced by a DisjointedBuffer are always released regardless of the return value.

    Remarks

    This must be called when the Payload data is no longer needed, otherwise payload blocks will "leak" within the container. Once complete the handle becomes invalid and attempts to retrieve the buffer again will fail.

    If the Payload buffer has been "locked", this operation will fail until all locks have been released. However, this behavior can be overridden using the "force" option; if set the buffer will be released irregardless of the number of locks on it.

    If the handle is for a Disjointed buffer, then all individual Payload buffers will also be released. When working with DisjointedBuffers, this is the recommended way to handle individual payloads. In general, it's not recommended to manually release payloads referenced by a DisjointedBuffer.

    Should a given Payload referenced by the DisjointedBuffer handle fail to release (for any reason) the call will fail with the result: DisjointedPayloadReleaseFailed. In this case all the other valid payloads referenced by DisjointedBuffer are released, but the "head" payload is not. To actually release the Disjointed buffer, this method must be called again with the force parameter set true; the returned result will be ForcedRelease. Note: if "force" is set when releasing a DisjointedBuffer the buffer, it will always succeed even if one or more referenced payloads fail to release.

    In general, it isn't necessary to call this directly because LogController will automatically cleanup message data and release Payload buffers.

    ReleasePayloadBufferDeferred(PayloadHandle)

    Releases the Payload memory allocated within the default Payload container after two (system is double buffered) Update()> calls

    Declaration
    public void ReleasePayloadBufferDeferred(PayloadHandle handle)
    Parameters
    Type Name Description
    PayloadHandle handle

    The PayloadHandle referencing the Payload buffer to release.

    Remarks

    This call adds payload handle to 'deferred' list, so it can be released after everything that uses this payload was processed. General use case is 'decoration' for logging messages. Some messages can be decorated with this payloads. Then Decorator is released, ReleasePayloadBufferDeferred is called and that guarantees that this decoration won't be attached to any log from this point. And then after two Update()> calls when all users of this Payload were processed - we should safely release it. For more details see ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean)

    RetrieveDisjointedPayloadBuffer(PayloadHandle, Int32, Boolean, out NativeArray<Byte>)

    Retrieves a NativeArray to safely access an individual Payload that's part of a Disjointed buffer.

    Declaration
    public bool RetrieveDisjointedPayloadBuffer(PayloadHandle handle, int payloadBufferIndex, bool readWriteAccess, out NativeArray<byte> payloadBuffer)
    Parameters
    Type Name Description
    PayloadHandle handle

    A PayloadHandle value the references a valid Disjointed buffer."

    Int32 payloadBufferIndex

    Index of the Payload, referenced by the Disjointed buffer, to retrieve.

    Boolean readWriteAccess

    True to allow write-access to the returned NativeArray, otherwise it's read-only.

    NativeArray<Byte> payloadBuffer

    NativeArray that allows safe access to the allocated Payload buffer.

    Returns
    Type Description
    Boolean

    True if successfully accessed Payload buffer.

    Remarks

    See AllocateDisjointedBuffer(ref FixedList64Bytes<UInt16>, NativeList<PayloadHandle>) for a general overview on "Disjointed" payload buffers.

    Use this method to safely retrieve one of the Payload buffers, that's referenced by a Disjointed buffer, for reading or writing payload data, similar to RetrievePayloadBuffer(PayloadHandle, Boolean, out NativeArray<Byte>).

    The Payload buffer to retrieve is specified by an index of the PayloadHandle value within the head buffer. This index value corresponds to the list index used to create the Disjointed buffer. That is, the Payload size list passed into AllocateDisjointedBuffer(ref FixedList64Bytes<UInt16>, NativeList<PayloadHandle>) or the PayloadHandle value list passed into CreateDisjointedPayloadBufferFromExistingPayloads(ref FixedList512Bytes<PayloadHandle>).

    As with RetrievePayloadBuffer(PayloadHandle, Boolean, out NativeArray<Byte>), the returned NativeArray is a "view" into the actual memory and must not be stored; it's only for immediate access to the underlying memory.

    RetrieveDisjointedPayloadBuffer(PayloadHandle, Int32, out NativeArray<Byte>)

    Retrieves a NativeArray to safely access an individual Payload that's part of a Disjointed buffer.

    Declaration
    public bool RetrieveDisjointedPayloadBuffer(PayloadHandle handle, int payloadBufferIndex, out NativeArray<byte> payloadBuffer)
    Parameters
    Type Name Description
    PayloadHandle handle

    A PayloadHandle value the references a valid Disjointed buffer."

    Int32 payloadBufferIndex

    Index of the Payload, referenced by the Disjointed buffer, to retrieve.

    NativeArray<Byte> payloadBuffer

    NativeArray that allows safe access to the allocated Payload buffer.

    Returns
    Type Description
    Boolean

    True if successfully accessed Payload buffer.

    Remarks

    See RetrieveDisjointedPayloadBuffer(PayloadHandle, Int32, Boolean, out NativeArray<Byte>).

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

    Retrieves a NativeArray to safely access Payload memory.

    Declaration
    public bool RetrievePayloadBuffer(PayloadHandle handle, bool readWriteAccess, out NativeArray<byte> payloadBuffer)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to access.

    Boolean readWriteAccess

    True to allow write-access to the returned NativeArray, otherwise it's read-only

    NativeArray<Byte> payloadBuffer

    NativeArray that allows safe access to the allocated Payload buffer.

    Returns
    Type Description
    Boolean

    True if successfully accessed Payload buffer.

    Remarks

    Listeners must call this to read the log message data when processing a LogMessage. The passed out NativeArray is only intended for immediate reading/writing into the buffer; the variable must not be saved.

    By default the return NativeArray is read-only, since typically Listeners only need to de-serialize the buffer contents and don't need to write into the buffer.

    RetrievePayloadBuffer(PayloadHandle, out NativeArray<Byte>)

    Retrieves a NativeArray to safely access Payload memory.

    Declaration
    public bool RetrievePayloadBuffer(PayloadHandle handle, out NativeArray<byte> payloadBuffer)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to access.

    NativeArray<Byte> payloadBuffer

    NativeArray that allows safe access to the allocated Payload buffer.

    Returns
    Type Description
    Boolean

    True if successfully accessed Payload buffer.

    Remarks

    See RetrievePayloadBuffer(PayloadHandle, Boolean, out NativeArray<Byte>)

    Shutdown()

    Releases all allocated memory and returns MemoryManager to an uninitialized state.

    Declaration
    public void Shutdown()
    Remarks

    Do not call this directly; shutdown is performed through Shutdown().

    UnlockPayloadBuffer(PayloadHandle, PayloadLockContext)

    Releases an existing Payload Lock on the specified buffer for a given context.

    Declaration
    public bool UnlockPayloadBuffer(PayloadHandle handle, PayloadLockContext context)
    Parameters
    Type Name Description
    PayloadHandle handle

    A valid PayloadHandle value for the Payload buffer to unlock.

    PayloadLockContext context

    Value returned by preceding call to LockPayloadBuffer(PayloadHandle).

    Returns
    Type Description
    Boolean

    True if unlock operation was successful or not.

    Remarks

    Each call to LockPayloadBuffer(PayloadHandle) generates a unique context value for a given buffer and Unlock must called for each context before the buffer can be safely released. While it's still possible to "force" release a locked Payload buffer, this isn't recommended.

    If the specified buffer wasn't locked for this specific context, the unlock operation will fail.

    See Also
    LockPayloadBuffer(PayloadHandle)
    IsPayloadBufferLocked(PayloadHandle, out Int32)
    ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, Boolean)

    Update()

    Performs maintenance work on the allocated RingBuffers and should be called once per frame.

    Enters exclusive lock, so make sure it is not called during Unity.Logging.LogMemoryManager.LockRead on the same thread. Unity.Logging.LogMemoryManager.LockRead Unity.Logging.LogMemoryManager.UnlockRead

    Declaration
    public void Update()
    Remarks

    Do not call this directly; updating is performed automatically by the LogController.

    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023