WaitLens
Follow QNX IPC waits from a thread to its destination process.
WaitLens is a local host tool for developers of QNX 8.0 software. Compare two
non-verbose pidin observations, see a client's SEND-to-REPLY transition, inspect
its destination process and follow source lines back to the input. Reports are
self-contained HTML and JSON. There is no service, account, telemetry or log upload.
Verified scope: Windows / Python 3.12.5 host execution, 30 automated tests and local report interaction checks. Supplied practice captures are synthetic. Actual QNX SDP compilation, target capture and VM/debugger integration are not verified. The optional native experiment is source and instructions, not a successful run.
Try it in two minutes
Python 3.10+; extract this source, open a terminal here and run without installing:
python -m waitlens compare fixtures/send.txt fixtures/reply.txt --provenance synthetic --out build/comparison
python -m waitlens analyze fixtures/cycle.txt --provenance synthetic --out build/cycle
python -m unittest discover -s tests -v
Open build/comparison.html. Expect one change for client 101:1: SEND / 100 →
REPLY / 100, with source line 3 in both inputs. Expand All parsed threads and
use the before/after navigation. In the cycle example, PIDs 200 and 300 form a
process cycle candidate; PID 400's RECEIVE value 200 creates no process edge.
All these numbers are teaching fixtures, not measurements of a target.
No runtime dependencies or internet are needed. Windows py -3 can replace
python. Source execution avoids downloading packaging tools. An optional local
wheel is a convenience; installation is not required to test the application.
What the result means
SEND/REPLY values identify destination processes, never a particular receiving
thread. RECEIVE values identify local channels. A cycle candidate is a reason to
inspect evidence, not proof of deadlock. pidin visits processes sequentially;
sampling, missing coverage, process exits and PID/TID reuse limit conclusions.
Two observations cannot establish a continuous wait, elapsed duration or latency.
Inputs must be individual UTF-8 non-verbose snapshots, at most 16 MiB, with columns
%a %b %60n %p %J %B. Malformed, duplicated, mixed and unsupported input is rejected.
Exit 0 means report generated; exit 2 means an input/I/O error. Cycle candidates
do not change the exit code. Provenance labels are supplied by the caller and do
not authenticate target execution. Reports preserve source lines, input hashes,
coverage warnings and these limits.
Judge and tutorial entry points
- Five-minute judge quickstart
- Completed host tutorial for QNX 8.0
- Verification scope
- Optional owner-licensed native workflow
- Fixture provenance
- Openable comparison example
The completed host tutorial has no pending target-output slots. The separate
docs/tutorial-draft.md is deliberately unfinished: it is a template for a later
native build/capture experiment and is not the tutorial bonus article.
QNX version, target and toolchain
The host parser supports the documented QNX OS 8.0 pidin layout. The optional
native source uses ChannelCreate, ConnectAttach, MsgSend, MsgReceive, MsgReply and
TimerTimeout. Its intended target is QNX OS 8.0 x86-64 in a private development VM,
built using QNX SDP 8.0 qcc -Vgcc_ntox86_64. The real installed SDP update, compiler
and VM version are not yet recorded because that path has not run. AArch64 source
build support is scripted but untested. No proprietary compiler, header, target
binary, runtime image or licence is included.
The QNX-specific semantics are implemented in waitlens/core.py; source-linked
presentation is in waitlens/report.py. The intended entry category is Developer
Tooling & Host Tools. Host functionality supporting QNX is the demonstrated
path; no native runtime claim follows from the synthetic pipeline tests.
Licence
Original code and documentation are MIT licensed. The minimal attributed
documentation excerpt in fixtures/public-doc.txt is excluded from that grant;
see its provenance. QNX is a trademark of its owner. This is an independent tool.
No third-party logos or music are bundled. The public source and media must remain
accessible free of charge through the judging period; see the judge quickstart.
Source files
- .gitignore
- LICENSE
- README.md
- docs/HOST_TUTORIAL.md
- docs/JUDGE_QUICKSTART.md
- docs/VERIFICATION.md
- docs/human-steps.md
- docs/tutorial-draft.md
- evidence/status.json
- examples/synthetic-comparison.html
- examples/synthetic-comparison.json
- examples/synthetic-cycle.html
- examples/synthetic-cycle.json
- fixtures/README.md
- fixtures/cycle.txt
- fixtures/public-doc.txt
- fixtures/reply.txt
- fixtures/send.txt
- media/00-thumbnail-1200x800.png
- media/01-comparison.png
- media/02-source-rows.png
- media/03-cycle-limits.png
- media/04-mobile.png
- pyproject.toml
- scripts/__init__.py
- scripts/build_qnx.py
- scripts/check_evidence.py
- scripts/fake_sdp.py
- scripts/post_sdp.py
- target/capture.sh
- target/waitlens_probe.c
- tests/test_post_sdp.py
- tests/test_waitlens.py
- waitlens/__init__.py
- waitlens/__main__.py
- waitlens/cli.py
- waitlens/core.py
- waitlens/report.py