Method ReleasePayloadBuffer
ReleasePayloadBuffer(PayloadHandle, out PayloadReleaseResult, bool)
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. |
| bool | force | Forces release of the Payload buffer even if it can't be performed "cleanly". |
Returns
| Type | Description |
|---|---|
| bool | 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.