Tracking Issue for ExitCodeExt on Windows

[AronParker]

Feature gate: #![feature(windows_process_exit_code_from)]

This is a tracking issue for implementing additional ExitCodes for Windows.

Motivation

On Windows it is common for applications to return HRESULT (i32) or DWORD (u32) values. These stem from COM based components (HRESULTS), Win32 errors (GetLastError), GUI applications (WM_QUIT) and more. The newly stabilized ExitCode provides an excellent fit for propagating these values, because std::process::exit does not run deconstructors which can result in errors. However, ExitCode currently only implements From<u8> for ExitCode, which disallows the full range of i32/u32 values. This pull requests attempts to address that shortcoming by providing windows specific extensions that accept a u32 value (which covers all possible HRESULTS and Win32 errors) analog to ExitStatusExt::from_raw.

This was also intended by the original Stabilization #93840 (comment) as pointed out by @eggyal in #97914 (comment):

Issues around platform specific representations: We resolved this issue by changing the return type of report from i32 to the opaque type ExitCode. That way we can change the underlying representation without affecting the API, letting us offer full support for platform specific exit code APIs in the future.

[Emphasis added]

Public API

/// Windows-specific extensions to [`process::ExitCode`].
///
/// This trait is sealed: it cannot be implemented outside the standard library.
/// This is so that future additional methods are not breaking changes.
#[stable(feature = "windows_process_exit_code_from", since = "1.63.0")]
pub trait ExitCodeExt: Sealed {
    /// Creates a new `ExitCode` from the raw underlying `u32` return value of
    /// a process.
    #[stable(feature = "windows_process_exit_code_from", since = "1.63.0")]
    fn from_raw(raw: u32) -> Self;
}

#[stable(feature = "windows_process_exit_code_from", since = "1.63.0")]
impl ExitCodeExt for process::ExitCode {
    fn from_raw(raw: u32) -> Self {
        process::ExitCode::from_inner(From::from(raw))
    }
}

Steps / History

• ACP: Implement ExitCodeExt for Windows libs-team#48
• Implementation: Implement ExitCodeExt for Windows #97917
• Fix tracking issue of Windows ExitCodeExt #118218
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Additional Links

• Add From<u8> for ExitCode #93445 (comment)

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[eggyal]

Kind of you to credit me for quoting that comment, but really it would make more sense to attribute it to the original author @yaahc (both to provide better context and also to draw their attention to this issue).

[AronParker]

Right sorry, I updated the link. It's just what I had in mind at the time that's why I made the link, but of course crediting @yaahc makes a lot more sense.

[ChrisDenton]

I would like to move toward stabilising this. If we're happy with the type being u32 rather than i32. On the one hand, u32 is the type taken by ExitProcess and is consistent with ExitStatusExt::from_raw. On the other hand, HRESULT and NTSTATUS are i32 and std::process::exit also takes an i32.

[ChrisDenton]

@rust-lang/libs-api I'd like to propose stabilising this as-is. I'm convinced that consistency with the underlying API (i.e. ExitProcess takes a u32) is the most appropriate approach.

Other than that there are no outstanding issues and this is genuinely useful for returning Windows error codes from main.

[dtolnay]

@rfcbot merge libs-api

[rust-rfcbot]

Team member @dtolnay 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.