18.2.7.3. IPayloadPool

class IPayloadPool

An interface for classes responsible of serialized payload management.

Public Functions

virtual bool get_payload(uint32_t size, CacheChange_t &cache_change) = 0

Get a serialized payload for a new sample.

This method will usually be called in one of the following situations:

  • When a writer creates a new cache change

  • When a reader receives the first fragment of a cache change

In both cases, the received size will be for the whole serialized payload.

Parameters

  • size – [in] Number of bytes required for the serialized payload.

  • cache_change – [inout] Cache change to assign the payload to

Returns

whether the operation succeeded or not

Pre

Fields writerGUID and sequenceNumber of cache_change are either:

  • Both equal to unknown (meaning a writer is creating a new change)

  • Both different from unknown (meaning a reader has received the first fragment of a cache change)

Post

  • Field cache_change.payload_owner equals this

  • Field serializedPayload.data points to a buffer of at least size bytes

  • Field serializedPayload.max_size is greater than or equal to size

virtual bool get_payload(SerializedPayload_t &data, IPayloadPool *&data_owner, CacheChange_t &cache_change) = 0

Assign a serialized payload to a new sample.

This method will usually be called when a reader receives a whole cache change.

Note

data and data_owner are received as references to accommodate the case where several readers receive the same payload. If the payload has no owner, it means it is allocated on the stack of a reception thread, and a copy should be performed. The pool may decide in that case to point data.data to the new copy and take ownership of the payload. In that case, when the reception thread is done with the payload (after all readers have been informed of the received data), method release_payload will be called to indicate that the reception thread is not using the payload anymore.

Warning

data_owner can only be changed from nullptr to this. If a value different from nullptr is received it should be left unchanged.

Warning

data fields can only be changed when data_owner is nullptr. If a value different from nullptr is received all fields in data should be left unchanged.

Parameters

  • data – [inout] Serialized payload received

  • data_owner – [inout] Payload pool owning incoming data

  • cache_change – [inout] Cache change to assign the payload to

Returns

whether the operation succeeded or not

Pre

  • Field cache_change.writerGUID is not unknown

  • Field cache_change.sequenceNumber is not unknown

Post

  • Field cache_change.payload_owner equals this

  • Field cache_change.serializedPayload.data points to a buffer of at least data.length bytes

  • Field cache_change.serializedPayload.length is equal to data.length

  • Field cache_change.serializedPayload.max_size is greater than or equal to data.length

  • Content of cache_change.serializedPayload.data is the same as data.data

virtual bool release_payload(CacheChange_t &cache_change) = 0

Release a serialized payload from a sample.

This method will be called when a cache change is removed from a history.

Parameters

cache_change – [inout] Cache change to assign the payload to

Returns

whether the operation succeeded or not

Pre

  • Field payload_owner of cache_change equals this

Post

  • Field payload_owner of cache_change is nullptr