Method LockPayloadBuffer

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.