Class Payload

Class Documentation

class Payload

Manages a dynamic, contiguous block of memory, tracking used sections.

This class provides functionalities to allocate, reserve, release, and write data to a buffer. It maintains a separate tracking mechanism to mark which bytes in the buffer are considered “used” or “reserved”. It also offers methods to find empty contiguous blocks for new data.

Public Functions

Payload(int size)

Constructs a new Payload object with a specified size.

Initializes the internal data buffer and a corresponding used_bytes tracking vector, marking all bytes as free initially.

Parameters:

size – The total size in bytes for the payload buffer.

Payload(const Payload &other)

Copy constructor for the Payload class.

Creates a new Payload object by deep-copying the data, used bytes map, and used size from another Payload instance.

Parameters:

other – The Payload object to copy from.

size_t Size()

Returns the total size of the internal data buffer.

Returns:

The total size of the buffer in bytes.

std::vector<uint8_t> &GetData()

Gets a reference to the raw internal data vector.

Warning

Modifying this vector directly can lead to inconsistencies with used_bytes_.

Returns:

A reference to the underlying std::vector<uint8_t> data buffer.

std::vector<uint8_t> GetUsedData() const

Returns a copy of the data that is currently marked as “used”.

Returns:

A new std::vector<uint8_t> containing the data from the beginning of the buffer up to used_size_.

bool CheckFree(uint64_t offset, uint64_t len, bool throws = false)

Checks if a specified range of bytes is free (not marked as used).

Parameters:

  • offset – The starting offset in the buffer to check.

  • len – The length of the contiguous block to check.

  • throws – If true, an ExpKitError is thrown if the range is not free or out of bounds. If false, it simply returns false.

Throws:

ExpKitError – if throws is true and the range is out of bounds or occupied.

Returns:

true if the entire range is free and within bounds, false otherwise.

uint8_t *Reserve(uint64_t offset, uint64_t len)

Reserves a contiguous block of memory and marks it as used.

This method checks if the specified range is free. If so, it marks the bytes as used and returns a pointer to the beginning of the reserved block within the internal data buffer. It updates used_size_ if the new reservation extends beyond the previously used area.

Parameters:

  • offset – The starting offset in the buffer to reserve.

  • len – The length of the contiguous block to reserve.

Throws:

ExpKitError – if the range is not free or out of bounds.

Returns:

A uint8_t* pointer to the reserved memory location within the buffer.

void Release(uint64_t offset, uint64_t len)

Releases a previously reserved block of memory.

Marks the specified range of bytes as free. If the released block was at the end of the used_size_ area, used_size_ is adjusted downwards.

Parameters:

  • offset – The starting offset of the block to release.

  • len – The length of the block to release.

uint64_t *ReserveU64(uint64_t offset)

Reserves space for a uint64_t at a given offset.

Warning

This function assumes the underlying buffer’s memory address will not change during its lifetime, which is generally true for std::vector unless it’s resized.

Parameters:

offset – The starting offset for the uint64_t.

Throws:

ExpKitError – if the space is not free or out of bounds.

Returns:

A uint64_t* pointer to the reserved memory location.

uint32_t *ReserveU32(uint64_t offset)

Reserves space for a uint32_t at a given offset.

Warning

This function assumes the underlying buffer’s memory address will not change during its lifetime, which is generally true for std::vector unless it’s resized.

Parameters:

offset – The starting offset for the uint32_t.

Throws:

ExpKitError – if the space is not free or out of bounds.

Returns:

A uint32_t* pointer to the reserved memory location.

void Set(uint64_t offset, void *src, size_t len)

Sets a block of bytes in the payload.

Reserves the specified range and then copies data from src into it.

Parameters:

  • offset – The starting offset in the payload.

  • src – A pointer to the source data to copy.

  • len – The number of bytes to copy.

Throws:

ExpKitError – if the space is not free or out of bounds.

void Set(uint64_t offset, const std::vector<uint8_t> &bytes)

Sets a block of bytes from a std::vector in the payload.

Reserves the necessary space and then copies the bytes from the provided vector.

Parameters:

  • offset – The starting offset in the payload.

  • bytes – The std::vector containing the data to copy.

Throws:

ExpKitError – if the space is not free or out of bounds.

void SetU32(uint64_t offset, uint32_t value)

Sets a 32-bit unsigned integer value at a specific offset.

Reserves space for a uint32_t and writes the value.

Parameters:

  • offset – The starting offset in the payload.

  • value – The uint32_t value to set.

Throws:

ExpKitError – if the space is not free or out of bounds.

void SetU64(uint64_t offset, uint64_t value)

Sets a 64-bit unsigned integer value at a specific offset.

Reserves space for a uint64_t and writes the value.

Parameters:

  • offset – The starting offset in the payload.

  • value – The uint64_t value to set.

Throws:

ExpKitError – if the space is not free or out of bounds.

std::optional<uint64_t> FindEmpty(uint64_t len, uint64_t alignment = 1, uint64_t min_offset = 0)

Finds the first contiguous block of empty (unused) bytes of a given length.

Searches for a free block starting from min_offset, respecting optional alignment. The algorithm is O(n) where n is the size of the buffer.

Parameters:

  • len – The desired length of the empty block.

  • alignment – The required alignment for the found offset (default is 1).

  • min_offset – The minimum offset to start searching from (default is 0).

Returns:

An std::optional containing the found offset if a suitable block is found, or std::nullopt otherwise.

Payload Snapshot()

Creates a snapshot of the current payload state.

Returns a new Payload object that is a deep copy of the current instance’s data, used bytes, and used size. This can be used for rollback purposes.

Returns:

A new Payload object representing the current state.

void Restore(const Payload &snapshot)

Restores the payload state from a given snapshot.

Replaces the current instance’s data, used bytes map, and used size with those from the provided snapshot.

Parameters:

snapshot – The Payload object to restore from.