Update the documentation for {As,Into,From}Raw{Fd,Handle,Socket}.
#93562
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This change weakens the descriptions of the
`{as,into,from}_raw_{fd,handle,socket}` descriptions from saying that
they *do* express ownership relations to say that they are *typically used*
in ways that express ownership relations. This needed needed since, for
example, std's own [`RawFd`] implements `{As,From,Into}Fd` without any of
the ownership relationships.
This adds proper `# Safety` comments to `from_raw_{fd,handle,socket}`,
adds the requirement that raw handles be not opened with the
`FILE_FLAG_OVERLAPPED` flag, and merges the `OwnedHandle::from_raw_handle`
comment into the main `FromRawHandle::from_raw_handle` comment.
And, this changes `HandleOrNull` and `HandleOrInvalid` to not implement
`FromRawHandle`, since they are intended for limited use in FFI situations,
and not for generic use, and they have constraints that are stronger than
the those of `FromRawHandle`.
[`RawFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/type.RawFd.html
|
(rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This function is documented in more detail in the `FromRawSocket` trait.
sunfishcode
added a commit
to sunfishcode/io-lifetimes
that referenced
this pull request
Feb 3, 2022
This ports the changes proposed in rust-lang/rust#93562 to io-lifetimes. Specifically, remove the redundant comments on `OwnedHandle::from_raw_handle` and `OwnedSocket::from_raw_socket`, and remove the `FromRawHandle` impls for `HandleOrInvalid` and `HandleOrNull`.
5 tasks
|
@bors r+ rollup |
|
📌 Commit ba6050f has been approved by |
bors
added
S-waiting-on-bors
sunfishcode
added a commit
to sunfishcode/io-lifetimes
that referenced
this pull request
Mar 2, 2022
This ports the changes proposed in rust-lang/rust#93562 to io-lifetimes. Specifically, remove the redundant comments on `OwnedHandle::from_raw_handle` and `OwnedSocket::from_raw_socket`, and remove the `FromRawHandle` impls for `HandleOrInvalid` and `HandleOrNull`.
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Mar 2, 2022
…joshtriplett
Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`.
This change weakens the descriptions of the
`{as,into,from}_raw_{fd,handle,socket}` descriptions from saying that
they *do* express ownership relations to say that they are *typically used*
in ways that express ownership relations. This is needed since, for
example, std's own [`RawFd`] implements `{As,From,Into}Fd` without any of
the ownership relationships.
This adds proper `# Safety` comments to `from_raw_{fd,handle,socket}`,
adds the requirement that raw handles be not opened with the
`FILE_FLAG_OVERLAPPED` flag, and merges the `OwnedHandle::from_raw_handle`
comment into the main `FromRawHandle::from_raw_handle` comment.
And, this changes `HandleOrNull` and `HandleOrInvalid` to not implement
`FromRawHandle`, since they are intended for limited use in FFI situations,
and not for generic use, and they have constraints that are stronger than
the those of `FromRawHandle`.
[`RawFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/type.RawFd.html
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Mar 2, 2022
…joshtriplett
Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`.
This change weakens the descriptions of the
`{as,into,from}_raw_{fd,handle,socket}` descriptions from saying that
they *do* express ownership relations to say that they are *typically used*
in ways that express ownership relations. This is needed since, for
example, std's own [`RawFd`] implements `{As,From,Into}Fd` without any of
the ownership relationships.
This adds proper `# Safety` comments to `from_raw_{fd,handle,socket}`,
adds the requirement that raw handles be not opened with the
`FILE_FLAG_OVERLAPPED` flag, and merges the `OwnedHandle::from_raw_handle`
comment into the main `FromRawHandle::from_raw_handle` comment.
And, this changes `HandleOrNull` and `HandleOrInvalid` to not implement
`FromRawHandle`, since they are intended for limited use in FFI situations,
and not for generic use, and they have constraints that are stronger than
the those of `FromRawHandle`.
[`RawFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/type.RawFd.html
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Mar 2, 2022
…joshtriplett
Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`.
This change weakens the descriptions of the
`{as,into,from}_raw_{fd,handle,socket}` descriptions from saying that
they *do* express ownership relations to say that they are *typically used*
in ways that express ownership relations. This is needed since, for
example, std's own [`RawFd`] implements `{As,From,Into}Fd` without any of
the ownership relationships.
This adds proper `# Safety` comments to `from_raw_{fd,handle,socket}`,
adds the requirement that raw handles be not opened with the
`FILE_FLAG_OVERLAPPED` flag, and merges the `OwnedHandle::from_raw_handle`
comment into the main `FromRawHandle::from_raw_handle` comment.
And, this changes `HandleOrNull` and `HandleOrInvalid` to not implement
`FromRawHandle`, since they are intended for limited use in FFI situations,
and not for generic use, and they have constraints that are stronger than
the those of `FromRawHandle`.
[`RawFd`]: https://doc.rust-lang.org/stable/std/os/unix/io/type.RawFd.html
|
Looks like this failed in a rollup: #94533 (comment) |
bors
added
S-waiting-on-author
|
I've now added a patch which fixes the broken doc link. |
sunfishcode
added
S-waiting-on-review
|
Was there discussion somewhere about why |
There may eventually be something to say about `FILE_FLAG_OVERLAPPED` here, however this appears to be independent of the other changes in this PR, so remove them from this PR so that it can be discussed separately.
|
@bors r+ |
|
|
|
📌 Commit 8253cfe has been approved by |
bors
added
S-waiting-on-bors
|
There was not; it came up from some private discussions and I had the impression it was a simple omission that would be nice to fix while I was making changes in this area. Looking into it more now, I've now found #81357 on this topic, with non-trivial considerations. In light of that, I've now removed the mention of |
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 3, 2022
…askrgr Rollup of 8 pull requests Successful merges: - rust-lang#93562 (Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`.) - rust-lang#94101 (rustdoc: add test cases for hidden enum variants) - rust-lang#94484 (8 - Make more use of `let_chains`) - rust-lang#94522 (Remove out-of-context line at end of E0284 message) - rust-lang#94534 (Re-export (unstable) core::ffi types from std::ffi) - rust-lang#94536 (Move transmute_undefined_repr back to nursery again) - rust-lang#94537 (Use ? operator in one instance instead of manual match) - rust-lang#94544 (Add some examples to comments in mbe code) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
|
OK, great, thanks. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change weakens the descriptions of the
{as,into,from}_raw_{fd,handle,socket}descriptions from saying thatthey do express ownership relations to say that they are typically used
in ways that express ownership relations. This is needed since, for
example, std's own
RawFdimplements{As,From,Into}Fdwithout any ofthe ownership relationships.
This adds proper
# Safetycomments tofrom_raw_{fd,handle,socket},adds the requirement that raw handles be not opened with the
FILE_FLAG_OVERLAPPEDflag, and merges theOwnedHandle::from_raw_handlecomment into the main
FromRawHandle::from_raw_handlecomment.And, this changes
HandleOrNullandHandleOrInvalidto not implementFromRawHandle, since they are intended for limited use in FFI situations,and not for generic use, and they have constraints that are stronger than
the those of
FromRawHandle.