Read QNX 8.0 IPC wait observations locally with WaitLens
Authored and executed on 2026-11-17 during the hackathon submission period. Allow 15–20 minutes. Audience: developers who can run Python and read a thread list.
This completed codelab teaches a host analysis task for QNX 8.0. You will compare two labelled practice snapshots, inspect a process cycle and decide what the observations support. All practice data below is synthetic. No QNX installation, licence or target execution is required, and this article contains no claimed native build/run result.
1. Prepare the host
Use Python 3.10+ and a desktop browser. Extract the project source and open a
terminal in the directory containing pyproject.toml. Windows with Python 3.12.5
was used for the recorded run. The host application uses only the standard library;
you do not need pip, a server, a cloud account or a network connection.
python --version
python -m waitlens --help
If Windows uses the Python launcher, substitute py -3 for python throughout.
If the module is not found, check your current directory before installing anything.
2. Read the practice inputs
fixtures/send.txt:
pid tid name prio STATE Blocked
100 1 ./waitlens_probe 10r NANOSLEEP
101 1 ./waitlens_probe 10r SEND 100
fixtures/reply.txt:
pid tid name prio STATE Blocked
100 1 ./waitlens_probe 10r NANOSLEEP
101 1 ./waitlens_probe 10r REPLY 100
These original rows model a client, PID:TID 101:1, waiting on destination PID 100. They were written as teaching data and were not collected from a QNX target. The column order follows the QNX 8.0 pidin reference.
3. Generate a comparison
python -m waitlens compare fixtures/send.txt fixtures/reply.txt --provenance synthetic --out build/practice
The checked local run exits with code 0 and reports:
WaitLens: 2 threads, 1 IPC waits, 0 coverage warnings, 1 observed changes
It writes build/practice.html and build/practice.json; the command also prints
their locations. Open the HTML locally. Read the observation banner first, then
the row under Observed changes. You should see SEND / 100 → REPLY / 100, client
101:1, and source line 3 in both files. Click the before/after navigation and expand
All parsed threads to check those lines against the original inputs.
The narrow interpretation is: if identity is stable, the client was awaiting receipt in the first observation and awaiting a reply in the second. QNX's MsgSend description explains these distinct blocking phases. A process destination does not identify which server worker accepted the request.
The JSON includes before.provenance and after.provenance set to synthetic,
input SHA-256 values, parsed source lines and one entry in changes. Provenance is
a caller label, not an authentication mechanism. A hash helps compare inputs; it
does not prove where they came from.
4. Inspect a cycle without over-diagnosing it
python -m waitlens analyze fixtures/cycle.txt --provenance synthetic --out build/cycle
Open build/cycle.html. Expected results from the actual host run:
| Item | Result |
|---|---|
| Processes / threads | 3 / 4 |
| IPC process edges | 200:1 → PID 300 in SEND; 300:1 → PID 200 in REPLY |
| Cycle candidate | PIDs 200 and 300 |
| PID 300 thread 2 | RECEIVE on channel 1; no process edge |
| PID 400 thread 1 | RECEIVE on channel 200; no process edge |
The RECEIVE value 200 is a local channel ID. It must not become an edge to PID 200.
Another worker of PID 300 is waiting to receive, so a process cycle does not tell
you that every thread is unable to progress. A real pidin collection also visits
processes sequentially rather than recording one atomic instant.
5. Practice missing coverage
Create an original text file build/missing.txt with these two lines:
pid tid name prio STATE Blocked
9 1 practice_client 10r SEND 888
python -m waitlens analyze build/missing.txt --provenance synthetic --out build/missing
Expect a warning naming absent destination PID 888. This means destination coverage is missing; it does not prove a crashed server. Filtering, permissions or process exit can all explain an absent destination in real capture data.
6. Run the checks and recover from errors
python -m unittest discover -s tests -v
The checked Windows run reports 30 tests, zero failures. The tests include a three-node graph oracle, a long graph chain, malformed input, escaping and native evidence refusal using test doubles. These are host development checks.
| Problem | Recovery |
|---|---|
| Module not found | Run from the extracted directory containing waitlens/ |
| Expected UTF-8 text | Preserve the original, then deliberately export a UTF-8 copy |
| Unsupported row / duplicate thread | Use one non-verbose six-column snapshot per file |
| Unknown state / permission text | Read the named line; do not silently remove contradictory evidence |
| Output collision | Choose a new --out prefix distinct from input paths |
| Browser appears blank | Open the generated .html, not the .json, in a desktop browser |
Success returns 0. Invalid input or I/O returns 2. A cycle candidate alone is not a failed test of the system. Inputs are bounded to 16 MiB.
7. Optional: use your own authorized QNX 8.0 capture
Only if you already have an appropriately licensed and authorized target session, run the following on that target, not on Windows:
pidin -F "%a %b %60n %p %J %B" > snapshot.txt
Use your own approved transfer method to bring just the intended snapshot to the host, then run:
python -m waitlens analyze snapshot.txt --provenance target-capture --out build/target-observation
This optional command is a documented workflow, not an executed step of this
codelab. The tool's real QNX compatibility remains unvalidated in the current
record. Do not relabel the practice fixtures as target captures. Native compilation
uses the separately prepared QNX OS 8.0 x86-64 / SDP 8.0 qcc path; see the explicitly
unfinished docs/tutorial-draft.md for that larger experiment.
8. Check your understanding
- Which process should you inspect next? In the two practice samples, PID 100 is the destination; no particular destination thread is identified.
- Does RECEIVE 200 mean waiting on process 200? No. It identifies a local channel.
- Does the cycle prove deadlock? No. Worker concurrency and sequential collection limit that conclusion.
- Can two samples measure wait duration? No. Use appropriate event tracing for timing and persistent-progress questions; PID/TID reuse also limits comparison.
You now have a reproducible host comparison and an explicit next inspection point. Keep original inputs and provenance with the report. No adoption, speedup, target execution or real-time performance result follows from this practice exercise.