Outdated documentation of shared memory API usage #372

Description

score/datarouter/doc/design/shm_apis.md contains several statements that do not match the current codebase:

Incorrect statements:

• Lines 22-24 describe a POSIX mutex in shared memory protecting read/write pointer consistency. The implementation uses lock-free atomics with no mutex anywhere in the shared memory structures or the wait_free_producer_queue directory.
• Line 22 states the writer advances the reader pointer when the buffer is full. In practice, the writer drops the message.
• Line 20 states "the reader can (and does) modify the shared memory." The reader maps with PROT_READ only (reader_factory_impl.cpp) and holds const SharedData&. All shared memory mutations are performed by the writer process.

Inaccurate or incomplete statements:

• Line 20 only mentions open() for shared memory creation. In dynamic mode, mkstemps() creates the file.
• Line 20 omits the O_EXCL and O_CLOEXEC flags used alongside O_RDWR.
• Line 45 states reconnection is handled transparently, without noting that prolonged failure triggers permanent client shutdown.
• Line 56 states DataRouter "waits for the reconnect." There is no explicit wait — the session is destroyed and the server continues listening; a reconnecting client creates a new session.

The documentation appears to describe a predecessor design (mutex-based circular buffer) that has since been replaced by the current lock-free alternating double-buffer design.

Problem notifications

No functional impact.

Analysis results

Documentation will be updated in subsequent PR.

Solution

See linked PR.

Error Occurrence Rate

None

How to reproduce

No response

Supporting Information

No response

Classification

Minor

First Affected Release

not released (main)

Last Affected Release

not released (main)

Expected Fixed Release

before release (main)

Category

• Safety Relevant
• Security Relevant