radar_system/python_app/docs/shm_protocol_and_readers.md

SHM protocol and readers

1. Ring format

Python reader ожидает ring header:

• magic: RDRRING2
• version: 1
• fields capacity/slot_size/write_seq/read_seq.

Ring files находятся в /dev/shm/<ring_name_without_slash>.

2. Reader components

• orchestration/shm/binary_cursor.py: primitive cursor API.
• orchestration/shm/decoder.py: decode trace/result payloads.
• orchestration/shm/ring_reader.py: mmap-based ring consumption.
• orchestration/shm_reader.py: фасад для импортов.

3. Consumption semantics

• pop_payload() возвращает None, если новых payload нет.
• При sequence mismatch reader выполняет fast-forward read pointer.
• drop_all() принудительно дропает unread payloads.

4. Error cases

• missing ring file -> FileNotFoundError
• magic/version mismatch -> RuntimeError
• bad payload magic/kind -> ValueError

5. Integration

AppWindowPipelineMixin использует по одному reader на raw/preprocessed/results ring.