Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`. #93562

sunfishcode · 2022-02-01T22:11:03Z

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.

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 · 2022-02-01T22:11:06Z

r? @joshtriplett

(rust-highfive has picked a reviewer for you, use r? to override)

This function is documented in more detail in the `FromRawSocket` trait.

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`.

joshtriplett · 2022-03-02T17:44:37Z

@bors r+ rollup

bors · 2022-03-02T17:44:39Z

📌 Commit ba6050f has been approved by joshtriplett

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`.

…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 · 2022-03-02T19:53:38Z

Looks like this failed in a rollup: #94533 (comment)
@bors r-

sunfishcode · 2022-03-02T22:24:19Z

I've now added a patch which fixes the broken doc link.

r? @joshtriplett

jstarks · 2022-03-02T23:22:59Z

Was there discussion somewhere about why FILE_FLAG_OVERLAPPED is prohibited?

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.

joshtriplett · 2022-03-03T00:35:24Z

@bors r+

bors · 2022-03-03T00:35:26Z

‼️ Invalid head SHA found, retrying: 0000000000000000000000000000000000000000

bors · 2022-03-03T00:35:27Z

📌 Commit 8253cfe has been approved by joshtriplett

sunfishcode · 2022-03-03T00:36:42Z

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 FILE_FLAG_OVERLAPPED from this PR, since the other changes don't depend on it.

…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

jstarks · 2022-03-03T16:57:59Z

OK, great, thanks.

rust-highfive assigned joshtriplett Feb 1, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 1, 2022

This comment has been minimized.

Sign in to view

sunfishcode added 4 commits February 1, 2022 14:23

Add missing pub keywords.

713bb19

Fix two copy+pastos.

8516895

Fix unresolved doc links.

6ef7ee3

Fix errors.

89544e9

This comment has been minimized.

Sign in to view

Use From/Into rather than the traits they replaced.

656d2a3

This comment has been minimized.

Sign in to view

sunfishcode added 2 commits February 1, 2022 15:10

x.py fmt

f88fb2a

Remove the documentation comment for OwnedSocket::from_raw_socket.

ba6050f

This function is documented in more detail in the `FromRawSocket` trait.

sunfishcode mentioned this pull request Feb 3, 2022

Update the documentation for {As,Into,From}Raw{Fd,Handle,Socket} sunfishcode/io-lifetimes#15

Merged

sunfishcode mentioned this pull request Feb 10, 2022

Tracking Issue for RFC 3128: I/O Safety #87074

Closed

5 tasks

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 2, 2022

matthiaskrgr mentioned this pull request Mar 2, 2022

Rollup of 11 pull requests #94531

Closed

matthiaskrgr mentioned this pull request Mar 2, 2022

Rollup of 10 pull requests #94532

Closed

matthiaskrgr mentioned this pull request Mar 2, 2022

Rollup of 8 pull requests #94533

Closed

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Mar 2, 2022

Fix a broken doc link on Windows.

af642bb

sunfishcode added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 2, 2022

Remove the comment about FILE_FLAG_OVERLAPPED.

8253cfe

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 added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 3, 2022

matthiaskrgr mentioned this pull request Mar 3, 2022

Rollup of 8 pull requests #94548

Merged

bors merged commit afd6f5c into rust-lang:master Mar 3, 2022

rustbot added this to the 1.61.0 milestone Mar 3, 2022

sunfishcode deleted the sunfishcode/io-docs branch March 3, 2022 13:40

sunfishcode mentioned this pull request Mar 3, 2022

Document FromRawFd unsafety #72175

Closed

Manishearth mentioned this pull request Jul 26, 2023

Determine and document the distinction between I/O safety and regular safety on unsafe stdlib APIs rust-lang/unsafe-code-guidelines#434

Closed

Ayanekoji mentioned this pull request Oct 28, 2024

Stack overflow at runtime when using Rc<RefCell<T>> in cycle detection algorithm #132263

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`. #93562

Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`. #93562

sunfishcode commented Feb 1, 2022 •

edited

Loading

rust-highfive commented Feb 1, 2022

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

joshtriplett commented Mar 2, 2022

bors commented Mar 2, 2022

matthiaskrgr commented Mar 2, 2022

sunfishcode commented Mar 2, 2022

jstarks commented Mar 2, 2022

joshtriplett commented Mar 3, 2022

bors commented Mar 3, 2022

bors commented Mar 3, 2022

sunfishcode commented Mar 3, 2022

jstarks commented Mar 3, 2022

Update the documentation for {As,Into,From}Raw{Fd,Handle,Socket}. #93562

Update the documentation for {As,Into,From}Raw{Fd,Handle,Socket}. #93562

Conversation

sunfishcode commented Feb 1, 2022 • edited Loading

rust-highfive commented Feb 1, 2022

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

joshtriplett commented Mar 2, 2022

bors commented Mar 2, 2022

matthiaskrgr commented Mar 2, 2022

sunfishcode commented Mar 2, 2022

jstarks commented Mar 2, 2022

joshtriplett commented Mar 3, 2022

bors commented Mar 3, 2022

bors commented Mar 3, 2022

sunfishcode commented Mar 3, 2022

jstarks commented Mar 3, 2022

Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`. #93562

Update the documentation for `{As,Into,From}Raw{Fd,Handle,Socket}`. #93562

sunfishcode commented Feb 1, 2022 •

edited

Loading