Stabilize windows_process_extensions_main_thread_handle

[ChayimFriedman2]

I propose we stabilize the library feature windows_process_extensions_main_thread_handle (tracking issue #96723).

Stabilization Report

Implementation History

This feature was added in #96725, and not changed since.

API Summary

// std::os::windows::process

pub trait ChildExt: Sealed {
    fn main_thread_handle(&self) -> BorrowedHandle<'_>;
}

This method gives access to the handle to the main thread of a spawned child process on Windows. It is not possible to get after spawning using documented APIs, and it's useful for example for resuming a process that started as suspended (while it's possible to enumerate all threads and resume them all, that's slower and more complicated).

Experience Report

My personal reason for this is wanting to use it for this case exactly (resuming a suspended process) in rust-analyzer, see rust-lang/rust-analyzer#22763 (comment). Other people seem to want this for the same reason as well (for example in the tracking issue). Searching GitHub for .main_thread_handle() gives 269 results. Some are for resuming processes, but there are also others - for example, injecting a DLL. I even found a project that gates using this method behind a feature, and if it's not set, uses an undocumented Windows API instead.

Unresolved Questions

There are two unresolved questions:

• The naming - should it be the "main thread" or the "primary thread". Microsoft's documentation refers to it as the "primary thread", but our own docs mention "main thread" (https://doc.rust-lang.org/std/thread/index.html), as stated in Tracking Issue for windows_process_extensions_main_thread_handle #96723 (comment). I left it as "main thread".
• Should it return Option<BorrowedHandle<'_>>? This will enable conversion from a handle to std::process::Child (such conversion is not supported currently). Such conversion is not supported for any OS currently though, and making this function returning Option will complicate code using it, so I chose to not do that.

r? libs-api

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[rust-log-analyzer]

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

fmt: checked 7059 files
tidy check
tidy [rustdoc_json (src)]: `rustdoc-json-types` modified, checking format version
tidy: Skipping binary file check, read-only filesystem
tidy [features]: /checkout/library/std/src/os/windows/process.rs:438: malformed stability attribute: missing the `since` key
tidy [features]: /checkout/library/std/src/os/windows/process.rs:444: malformed stability attribute: missing the `since` key
tidy [features]: /checkout/library/std/src/os/windows/process.rs:451: malformed stability attribute: missing the `since` key
tidy [features]: FAIL
removing old virtual environment
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (26.1.2)
linting python files
---
typechecking javascript files
tidy: The following check failed: features
Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck`
Currently active steps:
test::Tidy {  } at src/bootstrap/src/core/build_steps/test.rs:1604
Command `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools-bin/rust-tidy --root-path=/checkout --cargo-path=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo --output-dir=/checkout/obj/build --concurrency=4 --npm-path=/node/bin/yarn --ci=true --extra-checks=py,cpp,js,spellcheck` failed with exit code 1
Created at: src/bootstrap/src/core/build_steps/tool.rs:1627:23
Executed at: src/bootstrap/src/core/build_steps/test.rs:1682:29

Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:02:01
  local time: Wed Jul 29 07:05:56 UTC 2026
  network time: Wed, 29 Jul 2026 07:05:57 GMT
##[error]Process completed with exit code 1.
##[group]Run echo "disk usage:"

[ChrisDenton]

I've nominated for libs-api to start an FCP.

• The naming - should it be the "main thread" or the "primary thread".

Rust's terminology pretty consistently uses "main thread" so I do think it's better to be consistent with that then Microsoft's docs.

[the8472]

@rfcbot fcp merge libs-api

[rust-rfcbot]

@the8472 has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @the8472

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.