OS-level `thread::Builder` priority and affinity extensions

Proposal

Supersedes #71. This proposal is based on the discussion there and on Zulip about that proposal.

cc @AzureMarker @joshtriplett as they were involved in the earlier discussion / proposal as well.

Problem statement

Exposing OS thread scheduling options has been requested for quite a long time. Some third-party crates have been created to supplement the std functionality, but they seem to mostly work by either duplicating std APIs or only work for the current thread after spawning.

This proposal aims to enable std::os extension traits that can modify thread::Builder to set some of these properties before a thread is spawned, without committing to a higher-level cross-platform API (but ideally leaving room for one to be designed and implemented in the future).

Motivation, use-cases

Setting thread affinity and priority has a variety of motivations. For platforms that use a cooperative thread scheduler, setting CPU affinity and priority may be necessary to ensure that threads are not starved or cause deadlocks. High-performance / realtime applications may need fine grained control over their threads to meet performance requirements.

In principle, I believe this proposal should enable implementation of the necessary APIs to exert low-level OS-specific control over threads, which should pave the way for a more general-purpose cross-platform solution for these use cases.

Solution sketches

I have taken some of the changes from previous attempts and implemented them in a fork here, trying to show the minimum viable API surface:

• std::os::linux allows for setting affinity with libc::cpu_set_t (OS-specific structure).
• std::os::horizon allows for setting priority with libc::c_int (OS-specific meaning).
• Other platforms are unaffected. It should be possible to expand the extension traits as needed.

The new public API surface area is fairly small but can be expanded on a per-platform basis as support is added / desired:

std::os::horizon::thread

/// Horizon-specific extension trait for [`thread::Builder`](crate::thread::Builder).
pub trait BuilderExt {
    /// Set the priority of the thread to be spawned.
    ///
    /// See <https://www.3dbrew.org/wiki/Multi-threading#Threads> for details
    /// about the meaning / valid values of the `priority` parameter.
    fn priority(self, priority: libc::c_int) -> Self;
}

impl BuilderExt for crate::thread::Builder {}

std::os::linux::thread

/// Linux-specific extensions for [`thread::Builder`](crate::thread::Builder).
pub trait BuilderExt {
    /// Set the CPU affinity (which cores to run on) for the thread to be spawned.
    ///
    /// See <https://man7.org/linux/man-pages/man3/CPU_SET.3.html> for more details
    /// about how to construct the `cpu_set` parameter.
    fn affinity(self, cpu_set: libc::cpu_set_t) -> Self;
}

impl BuilderExt for crate::thread::Builder {}

Draft of an implementation here:

https://github.com/rust-lang/rust/compare/master...ian-h-chamberlain:rust:feature/thread-schedule-os-ext

Links and related work

• Long-standing RFC https://github.com/rust-lang/rfcs/issues/819
• thread-priority crate (duplicates std::thread::Builder API to allow setting before spawn)
• core_affinity crate (only allows set/get of current thread's affinity)
• Initial PR for armv6k-nintendo-3ds extension traits: https://github.com/rust-lang/rust/pull/98514
• Previous proposal motivated by discussion of the above: #71
• First attempt implementing the above proposal: https://github.com/rust-lang/rust/pull/101222
• Zulip discussion of the above proposal https://rust-lang.zulipchat.com/#narrow/stream/327149-t-libs-api.2Fapi-changes/topic/Reviews.20.2F.20feedback.20on.20thread.20priority.20proposal.3F

Start by reviewing superseded issue #71, the linked Zulip discussion, and the draft implementation comparing master with feature/thread-schedule-os-ext. The proposal centers on std::os::linux:🧵:BuilderExt and std::os::horizon:🧵:BuilderExt; done would require an agreed API design and platform-specific extensions consistent with the accepted scope.