Skip to content

Migrate Trace memory ownership to Strata - #2

Merged
zekageri merged 15 commits into
mainfrom
strata-integration
Sep 3, 2026
Merged

Migrate Trace memory ownership to Strata#2
zekageri merged 15 commits into
mainfrom
strata-integration

Conversation

@zekageri

@zekageri zekageri commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

Migrate Trace from its library-specific heap/task/mutex policy to the shared ZekStack Strata model and prepare the v0.3.0 release.

Memory policy

  • Pin Strata v0.1.2.
  • Replace TraceStackType and TraceStorageMemory with Strata::MemoryPolicy, Strata::Placement, and Strata::Region.
  • Prefer external memory by default for all movable Trace-owned allocations and for the Trace task stack.
  • Keep realtimeAllocation as an optional override; std::nullopt inherits memory.allocation.
  • Keep the small Trace root/control object and RTOS control storage internal; they are intentionally outside the movable payload policy.
  • Re-home callback holders registered before init() after the requested runtime policy is applied, so callback ownership follows memory.allocation / realtimeAllocation.

Ownership

  • Replace the direct ESP heap-cap allocator with Strata::Buffer while preserving the fixed TraceRecord ring-buffer design.
  • Replace the dynamically-created recursive mutex with Strata::FreeRTOS::RecursiveMutex.
  • Replace Trace's task-support shim with Strata::FreeRTOS::Task.
  • Change task shutdown from self-deletion to an external publish/suspend/reset handoff so Strata-owned static task storage is always freed from another task context.
  • Preserve ownership after a timed end() and make the destructor perform final cleanup.
  • Repeated end() calls during shutdown no longer restart or extend the original shutdown deadline; a later call can safely reap the task after a previously reported timeout.
  • Allocate callback holders through Strata.

Public/output allocations

  • Change TraceResult::message to const char * because Trace result messages are static literals.
  • Back TraceLog strings with Strata::String.
  • Add TraceLogList = Strata::Vector<TraceLog> and use it for query results and flush batches.
  • Build formatted strings through their Strata allocator rather than temporary default-allocator strings.
  • Keep the fixed direct C-string enqueue path allocation-free after initialization.

Diagnostics

Replace Trace-specific PSRAM booleans/stack enums with requested placement and observed region diagnostics for general allocation, realtime allocation, task stack, and all three ring buffers.

Validation and docs

  • Add Strata v0.1.2 to PlatformIO/Arduino/host CI.
  • Add source audits preventing direct heap-cap allocation and direct dynamic FreeRTOS ownership from returning to Trace.
  • Keep a Strata-specific host suite covering placement propagation, required-external failures, static-task ownership, repeated init/end, timed shutdown cleanup, destructor cleanup, and the zero-allocation C-string hot path.
  • Restore the v0.2.1 behavioral regression coverage as a second host binary, including realtime behavior/overflow, all pending overflow policies, retry/backoff semantics, callback locking, truncation, shutdown outcomes, capped flush barriers, and sequence ordering.
  • Update examples/docs and add a MemoryPolicy example.
  • Document the control-state vs movable-payload ownership boundary and pre-init callback re-homing behavior.
  • Bump library metadata from v0.2.1 to v0.3.0.

v0.2.x migration

v0.2.x v0.3.0
TraceStackType::Auto Strata::Placement::PreferExternal
TraceStackType::Internal Strata::Placement::Internal
TraceStackType::Psram Strata::Placement::RequireExternal
TraceStorageMemory::Internal Strata::Placement::Internal
TraceStorageMemory::PreferPsram Strata::Placement::PreferExternal
TraceStorageMemory::RequirePsram Strata::Placement::RequireExternal
config.stackType config.memory.taskStack
config.storageMemory config.memory.allocation
config.realtimeStorageMemory config.realtimeAllocation
std::vector<TraceLog> query results TraceLogList
TraceResult::message (std::string) const char *

The v0.3.0 default is intentionally PSRAM-first: memory.allocation and memory.taskStack are both PreferExternal, and realtime allocations inherit the general policy unless explicitly overridden.

@zekageri
zekageri merged commit 7d1cffb into main Sep 3, 2026
17 of 18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant