Skip to content

E27: Reentrancy review and hardening #345

@DavidCozens

Description

@DavidCozens

Motivation

The logging path crosses task boundaries on RTOS: application tasks call SolidSyslog_Log, a service task calls SolidSyslog_Service, and integrator-supplied callbacks (string functions, clock, error handler, onSwitch) can fire from yet other tasks. Some reentrancy is handled by construction (per-call SolidSyslogFormatter on the caller's stack; SolidSyslogAtomicCounter for sequenceId; mutex-protected SolidSyslogBuffer). Some is documented contract (single global error handler slot). And some is actually broken — see the first child story.

This epic exists to:

  • Audit the current state once, end to end.
  • Document which parts of the API are reentrant by construction, which require integrator contract, and which have actual bugs.
  • Fix the bugs.
  • Tighten the contract where it's currently implicit.

Likely children (refine when we pick this up)

  • OriginSd shared scratch fix — first child, filed as a story under this epic.
  • Reentrancy audit doc — enumerate every object in the logging path, classify each.
  • SolidSyslogSwitchingSender currentIndex race — UART task writes while Service task reads; plain int, tear-free on most platforms but UB by the C standard.
  • Callback contract clarity — the integrator's reentrancy obligations for string/clock/error/onSwitch callbacks are currently implicit. Make them explicit in the public-header audience table in CLAUDE.md and in each header.

Possibly in scope, possibly its own thing

  • Whether the SD pattern itself should be restructured (base class / helper) — that decision sits on the OriginSd bug story.
  • Whether the error handler slot should grow synchronisation, or stay documented-as-not-synchronised.
  • Hot-swap config during send → currently slated for the future Reconfiguration epic; revisit the boundary.

Out of scope

Open questions

  • Audit-only first slice, then act on findings — or interleave audit with fixes as they're found?
  • Are integrator-callback contract changes API-breaking enough to warrant a feat! bump, or can they go as docs?
  • Does the SD restructure (if Option Y on the OriginSd story is chosen) live here, or under E07: Structured Data #9 (E07 Structured Data)?
  • Should the concurrent-Log test framework live here or in E25: Fuzz testing and adversarial coverage #256 (E25 Fuzz testing)? Leaning E25.

Status

Not started. Will be picked up after the memory-consumption sequence (CMake-sizing epic, static-create discussion). Exact slot TBD. Refine as we get closer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    epicEpic issue

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions