feat(gst): give pipeline threads a macOS QoS class so they run on P cores

[wagenet]

Stacked on #722. The base branch for that PR does not exist on this repo, so this PR targets main and therefore shows four commits — the first three (feat(monitor), docs(monitor) and fix(monitor)) are #722's and are already under review there. Only the last commit, feat(gst): give pipeline threads a macOS QoS class, is new here. Please merge #722 first; this collapses to a single commit once it lands. Depends on #735 — without it App Nap erases the QoS class in headless mode about thirty seconds in.

What

On Apple Silicon it is the QoS class, not the pthread priority, that decides whether a thread is eligible for a performance core. Nothing in the tree called pthread_set_qos_class_self_np, so a streaming thread could be scheduled onto an efficiency core with nothing to signal it had happened. This sets a QoS class on the pipeline's streaming threads.

Why it replaces the priority path on macOS rather than adding to it

The two settings are mutually exclusive, in both orders (verified on macOS 15 / M2):

• pthread_setschedparam first makes a later pthread_set_qos_class_self_np return EPERM.
• Setting a class first is silently reset to UNSPECIFIED by a later pthread_setschedparam.

So macOS no longer calls the priority API at all. Linux and Windows keep their existing priority paths untouched.

This also retires a macOS priority path that never worked: the crossplatform value 80 is outside the 15..=47 range macOS accepts, so every "High" flow logged a warning and reported achieved=false on every thread.

Mapping

High maps to USER_INITIATED, not USER_INTERACTIVE. Both are performance-core classes — only BACKGROUND is confined to the efficiency cluster — but USER_INTERACTIVE is the band Apple reserves for main-thread UI work, which is where Strom's own native GUI runs. Encoder threads saturate every core they are given, so sharing that band makes the GUI compete with them at equal priority. Realtime is an explicit request for the maximum, so it does take USER_INTERACTIVE, falling back to USER_INITIATED when the task runs under a QoS clamp and the kernel refuses it with EPERM. Normal leaves the class alone.

Where the call goes

On the streaming thread itself — the bus StreamStatus::Enter handler and the session pad probe — because a thread that sets no class of its own gets QOS_CLASS_DEFAULT rather than inheriting anything meaningful. Placing it there also reaches element-internal workers that never post a StreamStatus of their own (libx264's frame threads): those are created from the streaming thread during caps negotiation, after Enter, and a thread created by a thread with an explicit class inherits it.

Setting the class is followed by a read-back, so a class that does not stick is reported as an error instead of leaving a silently unplaced thread.

Measured effect: 4.3% overall, ~7% under CPU contention

Supersedes the earlier no-effect result, which was taken before #735 existed and could not observe the setting: App Nap had clamped both arms to the efficiency cores, so every thread sat at scheduling priority 4 regardless of its class.

Re-measured on an M2 (4P+4E), every arm carrying #735, one binary with a runtime switch so the arms differ only in whether the class is set. Paired runs, fresh backend each, within-pair order counterbalanced:

experiment	n pairs	effect	95% CI
A/A control, both arms QoS on	40	+0.54%	[-1.25, +2.33]	null, as it must be (Wilcoxon p = 0.97)
A/B, host load median 5.7	40	-4.32%	[-7.03, -1.61]	significant, Wilcoxon p = 0.0011, 29/40 pairs
A/B, idle host	13	+0.75%	[-1.04, +2.55]	ns

Negative means QoS-on is faster. The A/A control is what licenses reading the -4.32% as real rather than as harness bias.

The benefit scales with contention. Splitting the 40-pair run by host load: -1.55% in the low-load half (mean load 5.0), -7.09% in the high-load half (mean load 9.1), corr(load, effect) = -0.425, t = -2.89. That is the expected shape — with P cores idle the scheduler lands streaming threads there anyway, so the class changes nothing; it earns its keep when it has to win a P core against competition. The idle-host row is consistent with the low-load half rather than contradicting it.

Mechanism: the QoS arm logs thread QoS class set to UserInitiated per streaming thread with readback confirmed, and ps -M shows those threads at priority 37; the other arm leaves them Default at 31.

Caveats: the idle-host arm is 13 pairs rather than 40, the load split is post-hoc, and the benchmark sets x264 threads=1, so it does not exercise the frame-thread inheritance path described above.

Tests

7 unit tests in thread_priority.rs, including read-back assertions that High lands in USER_INITIATED, that Realtime lands in one of the two performance-core classes, and that Normal leaves the class untouched.

Rebased onto #722's fix(monitor) commit with no conflict: this commit changes what happens inside the two StreamStatus arms, that one changes how the thread id is captured around them. Re-verified after the rebase on macOS (Apple Silicon, macOS 26.5): cargo test --features efp — 558 lib tests and every integration test pass, cargo clippy --all-targets --features efp -- -D warnings and cargo fmt --check clean.

One unrelated flake, once in eight full runs: config::tests::test_from_figment_cli_args_override panicked on Invalid argument (os error 22). It is the only config test without #[serial], and its serialized neighbours set_current_dir() into a TempDir and drop it while this one reads the process cwd. Pre-existing and untouched here — the added tests only shift the scheduling that exposes it.