StringHeap API

Overview

Per-object networked string pool for efficient replication of string properties. All types live in the FusionCore namespace.

Header: StringHeap.h

NetworkedStringHeap

Manages a heap of networked strings with allocation, deallocation and dirty tracking for delta synchronization.

Constructor

C++

explicit NetworkedStringHeap(uint32_t size = 0);

Create a heap with an initial capacity of size bytes. Pre-allocates entry and free-segment storage. With the default size = 0 no data buffer is allocated yet; the heap grows on first allocation.

Public Fields

Field	Type	Description
`Entries`	`std::vector<Entry>`	Slot table for string entries.
`EntryCount`	`uint32_t`	Number of live entries.
`FreeByOffset`	`std::vector<FreeSeg>`	Free segments sorted by offset.
`FreeSegmentCount`	`uint32_t`	Number of free segments.
`FreeIds`	`std::set<uint32_t, std::greater<>>`	Recycled entry IDs (lowest index at back for fast reuse).
`StringData`	`BufferT<RealtimeCore::Common::CharType>`	The heap data buffer (current state).
`Shadow`	`BufferT<RealtimeCore::Common::CharType>`	Previous-tick shadow for dirty detection.
`Ticks`	`BufferT<Tick>`	Per-byte tick stamps for delta encoding.
`HeapSize`	`uint32_t`	Current allocated heap capacity in bytes.
`SegmentInfos`	`std::vector<SegmentInfo>`	Debug segment map. See SegmentInfo.

Public Methods

Method	Signature	Description
`Resize`	`void Resize(uint32_t size)`	Grow the heap buffers (StringData, Shadow, Ticks) to the new size.
`AllocateString`	`StringHandle AllocateString(const RealtimeCore::Common::CharType *str)`	Allocate a string in the heap and return its handle. Grows the heap if necessary.
`ResolveString`	`const RealtimeCore::Common::CharType *ResolveString(const StringHandle &h, StringMessage &outStatus)`	Look up a string by handle. Sets `outStatus` to indicate validity. Returns a pointer to the string data or `nullptr`.
`FreeHandle`	`StringHandle FreeHandle(const StringHandle &h)`	Free the string at the given handle. Returns an invalidated handle. The freed space is added to the free list.
`IsValidHandle`	`bool IsValidHandle(const StringHandle &handle)`	Returns `true` if the handle points to a live entry with a matching generation.
`GetStringLength`	`uint32_t GetStringLength(const StringHandle &h)`	Returns the byte length of the string at the given handle.
`LogStringData`	`void LogStringData(const StringHandle &h)`	Print debug information about the entry and its data to the log.

Entry

Slot descriptor for a single string in the heap.

C++

struct Entry {
    uint32_t Offset = 0;
    uint32_t Size = 0;
    uint32_t Generation = 0;
    bool Alive = false;
    bool IsDirty = false;
    Tick ChangedTick = 0;
};

Field	Type	Description
`Offset`	`uint32_t`	Byte offset into `StringData`.
`Size`	`uint32_t`	String length in bytes.
`Generation`	`uint32_t`	Generation counter (incremented on reuse).
`Alive`	`bool`	True if the entry is in use.
`IsDirty`	`bool`	True if modified since last sync.
`ChangedTick`	`Tick`	Tick when the entry was last modified.

FreeSeg

Describes a contiguous free region in the heap buffer.

C++

struct FreeSeg {
    uint32_t Offset;
    uint32_t Size;

    bool operator<(FreeSeg const &o) const;
};

Field	Type	Description
`Offset`	`uint32_t`	Start offset in `StringData`.
`Size`	`uint32_t`	Size in bytes.

Comparison operator sorts by offset for ordered storage.

SegmentInfo

Debug snapshot of one heap segment, live or free. Filled into NetworkedStringHeap::SegmentInfos for inspection and logging.

C++

struct SegmentInfo {
    bool Alive;
    uint32_t Offset;
    uint32_t Size;
};

Field	Type	Description
`Alive`	`bool`	True if the segment holds a live string, false for a free gap.
`Offset`	`uint32_t`	Start offset in `StringData`.
`Size`	`uint32_t`	Size in bytes.

StringHandle

Opaque handle referencing a string in the heap. Validated by checking the generation against the entry.

C++

struct StringHandle {
    uint32_t Id;
    uint32_t Generation;
};

Field	Type	Description
`Id`	`uint32_t`	Entry index in the `Entries` table.
`Generation`	`uint32_t`	Expected generation (must match entry to be valid).

StringMessage

Status codes returned by ResolveString via the outStatus parameter.

Value	Code	Description
`Valid`	0	Handle is valid, string data returned.
`NotALiveEntry`	1	Entry exists but is not alive.
`WrongGeneration`	2	Handle generation does not match entry.
`OutOfRange`	3	Handle ID is out of range.
`WrongSize`	4	Entry size is inconsistent.
`EmptyString`	5	String has zero length.
`InvalidHandle`	6	Handle is structurally invalid.
`EmptyHeap`	7	The string heap has not been allocated.

Constants

Constant	Value	Description
`HEAP_BUFFER_PADDING`	256	Extra padding bytes added when growing the heap buffer to reduce frequent reallocations.

Object API -- Objects that contain per-object string heaps
Buffers API -- BufferT used for heap storage

Overview
NetworkedStringHeap

Constructor
Public Fields
Public Methods

Entry
FreeSeg
SegmentInfo
StringHandle
StringMessage
Constants
Related