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.