docs: S23.22 hold the Posix page to what the adapters do - #741
Conversation
Adds the three things the page was silent on — writes are not fsynced, the dead-peer window is 30 to 85 seconds, and the message queue is capped by fs/mqueue rather than by the caller — and corrects the host-identity wording. The link guidance said the build links rt for you. Nothing in the CMake tree does; glibc 2.34 moved the message-queue functions into libc, so the promise has never been tested by a container new enough to run CI. Also carries the FreeRTOS uptime unit correction deferred from #739's review. Part of #708. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Note Reviews pausedUse the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThe PR updates FreeRTOS uptime semantics and POSIX documentation. It clarifies glibc linking requirements, host identity sources, filesystem durability, TCP failure detection, and POSIX message-queue limits. ChangesPlatform documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/platforms/posix/setup.md`:
- Around line 16-19: Update the POSIX message-queue linking guidance to
distinguish CMake consumers, which receive the PUBLIC rt dependency
automatically when SOLIDSYSLOG_POSIX is enabled, from direct libSolidSyslog.a
consumers, which must add -lrt on glibc versions before 2.34; remove the blanket
claim that no extra linking is needed.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 906c248d-1104-4211-a916-6a605977915d
📒 Files selected for processing (3)
docs/platforms/freertos/setup.mddocs/platforms/posix/index.mddocs/platforms/posix/setup.md
|
@coderabbitai pause |
✅ Action performedReviews paused. |
Core/Source/CMakeLists.txt links rt PUBLIC under SOLIDSYSLOG_POSIX, so a CMake consumer inherits it. Only a direct consumer of the archive adds -lrt, and only on glibc before 2.34. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
☀️ Quality Summary Created by Quality Monitor v4.15.0 (#82d77af). More details are shown in the GitHub Checks Result. |
1 participant
Purpose
The Posix platform triage — the fifth of eight platforms, and the same treatment
the Windows page had in #739: every claim on the page read out of the adapter,
and the things the page was silent about stated.
It also carries the FreeRTOS uptime correction that #739's review raised late.
That was deferred deliberately rather than pushed to a merging PR, because a
prose fix is not worth a review cycle of its own.
Part of #708.
Change Description
Linking guidance that was half-stated.
setup.mdsaid selecting thisplatform "links
rtpublicly … you do not have to add it yourself". That is truefor a CMake consumer —
Core/Source/CMakeLists.txtlinksrtPUBLIC underSOLIDSYSLOG_POSIX— and not true for a consumer oflibSolidSyslog.adirectly,which on glibc before 2.34 must add
-lrtitself. The page now draws thatdistinction, and
index.mddrops its contradicting parenthetical so the linkingadvice has one home.
I first read this as the linkage not existing at all, and pushed a correction
that made an accurate page wrong; review caught it and 4ed1b27 fixes it. The
cause is worth recording: three greps, each read through
head, and the linethat mattered was below the cut every time.
A limit the caller cannot see.
SolidSyslogPosixMessageQueueBuffer_Createpasses
maxMessages/maxMessageSizestraight tomq_open, and anunprivileged process cannot exceed
fs/mqueue/msg_max(10) ormsgsize_max(8192) — verified in the gcc container, where
mq_maxmsg = 11already failsEINVAL. The failure path is correct (slot released,ERRORreported,SolidSyslogNullBufferreturned) but nothing told the integrator that a100-record queue is not theirs to ask for.
Two statements the page owed the reader, both matching the shape agreed for
Windows: nothing calls
fsync, so durability belongs to the volume; and thedead-peer window is 30 to 85 seconds — keepalive at 45 s idle plus 4 × 10 s, with
TCP_USER_TIMEOUTbounding the write-in-flight case at 30 s. Records handed tothe kernel inside that window are reported delivered and lost with the
connection, which is the consequence worth stating.
Corrections. "Forwarded unmodified" named neither source; it is
gethostnameand
getpid.Checked, and deliberately unchanged: the Datagram adapter meets its contract
with no exception (
EMSGSIZE→OVERSIZE,MaxPayloadfromIP_MTU), so #736does not reach it; the store file really is created
0600; the UDP socket reallyis left blocking while the TCP one is not; and
BUFFER_BACKEND_FAILEDisdeliberately
ERRORrather thanCRITICALunderdocs/error-severity.md, sinceraising a sysctl is an operator action rather than a code change.
Test Evidence
Documentation only; no production code is touched.
mkdocs build --strictscripts/check_platform_docs.pyThe
mq_openceiling was verified by probing it in thegcccontainer ratherthan asserted from documentation:
msg_max10,msgsize_max8192, andmq_maxmsgof 11, 100 and 1000 all rejected withEINVAL.Areas Affected
docs/platforms/posix/, and one paragraph ofdocs/platforms/freertos/setup.md.No production code is touched, and no decision is left open — the
rtlinkagealready behaves correctly; only its description needed fixing.