Skip to content

S24.04: Migrate Linux BDD off Example/SingleTask; remove the SingleTask binary #332

Description

@DavidCozens

Parent epic: #254 (E24: Code Hygiene)

Overview

Example/SingleTask/ (Linux, NullBuffer, direct UDP/TCP send) and
Example/Threaded/ (Linux, PosixMessageQueueBuffer + service thread,
SwitchingSender over UDP/TCP/TLS/mTLS, BlockStore option) are two
binaries doing overlapping jobs. The Threaded binary is a strict
superset since S15 introduced SwitchingSender. The BDD harness uses
both — most scenarios run against the SingleTask binary via
run_example; the @buffered-tagged scenarios route to the Threaded
binary via run_buffered_example. Windows already collapsed to one
binary in S13.20; FreeRTOS only has one (the buffered SingleTask after
S08.04 slice 2). Linux is the only platform left carrying two.

Why

  • Two binaries per platform was historical (S03 era); SwitchingSender
    (S15) made the second one redundant for BDD coverage.
  • The Linux SingleTask binary is BDD test infrastructure dressed as a
    pedagogical example. Pre-launch (v0.0.0) there are no external
    readers to consider; the duplication is pure carrying cost.
  • Future SL1 / SL2 / SL3 pedagogical examples (separate epic, not
    scheduled here) want a clean Example/ directory to live in.

In scope

  • Point BDD_TARGET=linux's context.example_binary default at the
    Threaded binary (build/debug/Example/SolidSyslogThreadedExample).
  • Audit every run_example caller on Linux (currently ~25 scenarios
    via the the example program sends ... step family) to confirm none
    rely on NullBuffer's synchronous-send timing semantics. The
    Threaded binary's service-thread drain takes a few hundred ms in the
    worst case; any scenario asserting "oracle received within N ms of
    the send command returning" without already waiting for receipt is a
    surface we need to fix.
  • Collapse run_example / run_buffered_example if the dispatch no
    longer needs to branch — they now both route to the Threaded binary
    on Linux.
  • Delete Example/SingleTask/ (directory + add_subdirectory in the
    parent Example/CMakeLists.txt).
  • Delete Tests/Example/SolidSyslogExampleTest.cpp and its
    add_subdirectory registration.
  • Update Example/CMakeLists.txt and the top-level CMakeLists.

Acceptance criteria

  • All Linux BDD scenarios that pass today continue to pass after
    the cut. Specifically bdd-linux-syslog-ng is green on CI.
  • Example/SingleTask/ no longer exists.
  • Tests/Example/SolidSyslogExampleTest.cpp no longer exists.
  • analyze-format, analyze-tidy, analyze-cppcheck,
    coverage-linux-gcc all green (coverage stays ≥ 90%).
  • No references to SolidSyslogExample (the SingleTask binary
    name) remain in the repo apart from blog-history mentions.

Out of scope

  • Renaming or moving the Threaded binary out of Example/ — that's
    S24.05.
  • Windows / FreeRTOS BDD wiring — they already use a single binary
    each.
  • New SL1 / SL2 / SL3 pedagogical examples — separate future epic.
  • Documentation rewrite — David is rewriting the docs separately;
    light touch only where needed to keep references valid.

Risks

  • Some BDD steps may have implicit synchronous-send assumptions. The
    audit upfront is the gate.
  • The THREADED_BINARY constant in Bdd/features/steps/syslog_steps.py
    becomes the only binary; the routing logic in run_buffered_example
    / _run_with_prompt_protocol simplifies accordingly.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions