Skip to main content

Crate qos_threads

Crate qos_threads 

Source
Expand description

§qos-threads

Crates.io Documentation CI/CD License: MIT OR Apache-2.0 Downloads

Cross-platform Quality-of-Service controls for native threads and processes.

§Platform support

TargetBehavior
macOSNative per-thread QoS and process disk-I/O controls
Linux and AndroidNative per-thread nice-level controls; process I/O is delegated to the service manager
Windows and other targetsCompiles with successful no-op scheduling controls

The crate is therefore useful on every target as a stable API, but it only changes operating-system scheduling natively on macOS, Linux, and Android.

This crate provides a small platform abstraction for workloads that share a machine but have different scheduling needs:

  • Qos::High — latency-sensitive work that should remain responsive under load. On macOS this maps to QOS_CLASS_USER_INITIATED; on Linux it maps to the normal nice level.
  • Qos::Low — background or CPU-bound work that should yield to interactive workloads. On macOS this maps to QOS_CLASS_UTILITY; on Linux it maps to a positive nice level.

§Thread controls

Use set_current_thread from a thread-pool startup hook when a thread keeps the same scheduling class for its lifetime:

use qos_threads::{Qos, set_current_thread};

set_current_thread(Qos::Low)?;

Use with_qos when a reused thread needs a temporary class. The previous class is restored even when the closure unwinds:

use qos_threads::{Qos, with_qos};

let answer = with_qos(Qos::Low, || 20 + 22);
assert_eq!(answer, 42);

§Process I/O

boost_process_io raises the process’s disk-I/O policy where the operating system provides such a control. This is useful when durable I/O should not be treated as background housekeeping. On platforms where the process-level policy is managed by the service manager, the function is a successful no-op.

§Platform behavior

The API is intentionally small and platform-neutral. Unsupported platforms return success without changing scheduling, while an operating-system rejection is returned as QosError. Callers can decide whether a scheduling policy is advisory or mandatory for their workload.

The crate currently implements native controls for Apple platforms and Linux or Android. Other platforms compile with the documented no-op behavior.

§License

Licensed under either of:

at your option.

Structs§

QosError
An operating-system scheduling call was rejected. Carries the raw errno.

Enums§

Qos
Thread scheduling priority class for a workload’s QoS policy.

Functions§

boost_process_io
Raise this process’s disk-I/O priority so durable reads and writes win contention against low-priority OS housekeeping. Process-scoped, so it also covers threads that do not use a per-thread Qos hook. Call once during process startup when durable I/O should remain responsive.
set_current_thread
Set the calling thread’s scheduling class for the rest of its life. This is intended for a runtime on_thread_start hook that assigns a stable class to each worker thread.
with_qos
Run f with the calling thread temporarily set to qos, restoring the thread’s previous class when f returns or unwinds.