Clarify what values BorrowedHandle, OwnedHandle etc. can hold.
#96932
Conversation
Clarify that when `BorrowedHandle`, `OwnedHandle`, or `HandleOrNull` hold the value `-1`, it always means the current process handle, and not `INVALID_HANDLE_VALUE`.
|
Hey! It looks like you've submitted a new PR for the library teams! If this PR contains changes to any Examples of
|
|
r? @kennytm (rust-highfive has picked a reviewer for you, use r? to override) |
| /// This type considers any value other than `NULL` to be valid, including `INVALID_HANDLE_VALUE`. | ||
| /// This is because APIs that use `NULL` as their sentry value don't treat `INVALID_HANDLE_VALUE` | ||
| /// as special. | ||
| /// This type may hold any handle value that [`OwnedHandle`] may hold, except `NULL`. It may |
There was a problem hiding this comment.
This sentence sounds like this type cannot hold NULL, but it's the other way around (the type can hold NULL as the sentry value).
There was a problem hiding this comment.
That's a good point. I've now reworded this.
This ports the documentation updates from rust-lang/rust#96932.
|
Seems reasonable. Are there no other circumstances in which such a handle might ever hold -1? Is there no way to end up with one yourself, if constructed that way rather than returned from a Windows API? |
The value of -1 is documented here, though it does also say that in theory the current process handle could have a different value in future OS versions. I've now added a patch to change the wording to reflect that |
This comment has been minimized.
This comment has been minimized.
|
I'd only add that all valid handle values should originally come from the Windows API in one way or another. Like pointers they shouldn't be created out of thin air. This goes for pseudo-handles too. As mentioned above, even though they may have a known value this value isn't actually guaranteed. |
|
@bors r+ rollup |
|
📌 Commit 275812a has been approved by |
…rrowed-handle, r=joshtriplett Clarify what values `BorrowedHandle`, `OwnedHandle` etc. can hold. Reword the documentation to clarify that when `BorrowedHandle`, `OwnedHandle`, or `HandleOrNull` hold the value `-1`, it always means the current process handle, and not `INVALID_HANDLE_VALUE`. `-1` should only mean `INVALID_HANDLE_VALUE` after a call to a function documented to return that to report errors, which should lead I/O functions to produce errors rather than succeeding and producing `OwnedHandle` or `BorrowedHandle` values. So if a consumer of an `OwnedHandle` or `BorrowedHandle` ever sees them holding a `-1`, it should always mean the current process handle.
…askrgr Rollup of 5 pull requests Successful merges: - rust-lang#96932 (Clarify what values `BorrowedHandle`, `OwnedHandle` etc. can hold.) - rust-lang#96948 (Add test of matches macro for trailing commas) - rust-lang#96988 (Fix platform support links.) - rust-lang#96989 (Be more precise than DefPathData::Misc.) - rust-lang#96993 (rustdoc: fix GUI crash when searching for magic JS property values) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
* Clarify what values BorrowedHandle, OwnedHandle etc. can hold. This ports the documentation updates from rust-lang/rust#96932. * Relax the wording about the meaning of -1.
Reword the documentation to clarify that when
BorrowedHandle,OwnedHandle, orHandleOrNullhold the value-1, it always means the current process handle, and notINVALID_HANDLE_VALUE.-1should only meanINVALID_HANDLE_VALUEafter a call to a function documented to return that to report errors, which should lead I/O functions to produce errors rather than succeeding and producingOwnedHandleorBorrowedHandlevalues. So if a consumer of anOwnedHandleorBorrowedHandleever sees them holding a-1, it should always mean the current process handle.