ZZZ Digital Lab

Back to WaitLens

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

  1. Which process should you inspect next? In the two practice samples, PID 100 is the destination; no particular destination thread is identified.
  2. Does RECEIVE 200 mean waiting on process 200? No. It identifies a local channel.
  3. Does the cycle prove deadlock? No. Worker concurrency and sequential collection limit that conclusion.
  4. 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.