From 0c0cdd396de1fa672896ae6906c296c94b1dd27d Mon Sep 17 00:00:00 2001 From: Tymoteusz Date: Sun, 5 Mar 2023 17:00:09 +0100 Subject: [PATCH 1/2] tokio: make all windows docs visible --- tokio/src/doc/os.rs | 23 +++++++++++++- tokio/src/fs/file.rs | 20 ++++++------ tokio/src/fs/mod.rs | 4 +-- tokio/src/fs/open_options.rs | 13 ++++---- tokio/src/fs/symlink_dir.rs | 2 +- tokio/src/fs/symlink_file.rs | 2 +- tokio/src/io/stderr.rs | 11 ++++--- tokio/src/io/stdin.rs | 11 ++++--- tokio/src/io/stdout.rs | 11 ++++--- tokio/src/macros/cfg.rs | 12 +++++++ tokio/src/net/tcp/listener.rs | 6 ++-- tokio/src/net/tcp/socket.rs | 47 ++++++++++++++-------------- tokio/src/net/tcp/stream.rs | 6 ++-- tokio/src/net/udp.rs | 8 ++--- tokio/src/process/mod.rs | 59 +++++++++++++++++------------------ 15 files changed, 135 insertions(+), 100 deletions(-) diff --git a/tokio/src/doc/os.rs b/tokio/src/doc/os.rs index 0ddf86959b8..bf427f12645 100644 --- a/tokio/src/doc/os.rs +++ b/tokio/src/doc/os.rs @@ -13,7 +13,7 @@ pub mod windows { /// See [std::os::windows::io::AsRawHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html) pub trait AsRawHandle { - /// See [std::os::windows::io::FromRawHandle::from_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle) + /// See [std::os::windows::io::AsRawHandle::as_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle) fn as_raw_handle(&self) -> RawHandle; } @@ -22,5 +22,26 @@ pub mod windows { /// See [std::os::windows::io::FromRawHandle::from_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html#tymethod.from_raw_handle) unsafe fn from_raw_handle(handle: RawHandle) -> Self; } + + /// See [std::os::windows::io::RawSocket](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html) + pub type RawSocket = crate::doc::NotDefinedHere; + + /// See [std::os::windows::io::AsRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html) + pub trait AsRawSocket { + /// See [std::os::windows::io::AsRawSocket::as_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket) + fn as_raw_socket(&self) -> RawSocket; + } + + /// See [std::os::windows::io::FromRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html) + pub trait FromRawSocket { + /// See [std::os::windows::io::FromRawSocket::from_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket) + unsafe fn from_raw_socket(sock: RawSocket) -> Self; + } + + /// See [std::os::windows::io::IntoRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html) + pub trait IntoRawSocket { + /// See [std::os::windows::io::IntoRawSocket::into_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket) + fn into_raw_socket(self) -> RawSocket; + } } } diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs index d513beb05a4..f48d4091550 100644 --- a/tokio/src/fs/file.rs +++ b/tokio/src/fs/file.rs @@ -732,17 +732,19 @@ impl std::os::unix::io::FromRawFd for File { } } -#[cfg(windows)] -impl std::os::windows::io::AsRawHandle for File { - fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { - self.std.as_raw_handle() +cfg_windows! { + use crate::os::windows::io::{AsRawHandle, FromRawHandle, RawHandle}; + + impl AsRawHandle for File { + fn as_raw_handle(&self) -> RawHandle { + self.std.as_raw_handle() + } } -} -#[cfg(windows)] -impl std::os::windows::io::FromRawHandle for File { - unsafe fn from_raw_handle(handle: std::os::windows::io::RawHandle) -> Self { - StdFile::from_raw_handle(handle).into() + impl FromRawHandle for File { + unsafe fn from_raw_handle(handle: RawHandle) -> Self { + StdFile::from_raw_handle(handle).into() + } } } diff --git a/tokio/src/fs/mod.rs b/tokio/src/fs/mod.rs index 30ce6a91a35..f6d9605fe94 100644 --- a/tokio/src/fs/mod.rs +++ b/tokio/src/fs/mod.rs @@ -115,9 +115,7 @@ feature! { pub use self::symlink::symlink; } -feature! { - #![windows] - +cfg_windows! { mod symlink_dir; pub use self::symlink_dir::symlink_dir; diff --git a/tokio/src/fs/open_options.rs b/tokio/src/fs/open_options.rs index c600ef5acc8..103510250b6 100644 --- a/tokio/src/fs/open_options.rs +++ b/tokio/src/fs/open_options.rs @@ -10,6 +10,11 @@ use mock_open_options::MockOpenOptions as StdOpenOptions; #[cfg(not(test))] use std::fs::OpenOptions as StdOpenOptions; +#[cfg(unix)] +use std::os::unix::fs::OpenOptionsExt; +#[cfg(windows)] +use std::os::windows::fs::OpenOptionsExt; + /// Options and flags which can be used to configure how a file is opened. /// /// This builder exposes the ability to configure how a [`File`] is opened and @@ -399,8 +404,6 @@ impl OpenOptions { feature! { #![unix] - use std::os::unix::fs::OpenOptionsExt; - impl OpenOptions { /// Sets the mode bits that a new file will be created with. /// @@ -464,11 +467,7 @@ feature! { } } -feature! { - #![windows] - - use std::os::windows::fs::OpenOptionsExt; - +cfg_windows! { impl OpenOptions { /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`] /// with the specified value. diff --git a/tokio/src/fs/symlink_dir.rs b/tokio/src/fs/symlink_dir.rs index 736e762b48d..6753c25eb7b 100644 --- a/tokio/src/fs/symlink_dir.rs +++ b/tokio/src/fs/symlink_dir.rs @@ -10,7 +10,7 @@ use std::path::Path; /// /// This is an async version of [`std::os::windows::fs::symlink_dir`][std] /// -/// [std]: std::os::windows::fs::symlink_dir +/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html pub async fn symlink_dir(src: impl AsRef, dst: impl AsRef) -> io::Result<()> { let src = src.as_ref().to_owned(); let dst = dst.as_ref().to_owned(); diff --git a/tokio/src/fs/symlink_file.rs b/tokio/src/fs/symlink_file.rs index 07d8e604192..623352a1bda 100644 --- a/tokio/src/fs/symlink_file.rs +++ b/tokio/src/fs/symlink_file.rs @@ -10,7 +10,7 @@ use std::path::Path; /// /// This is an async version of [`std::os::windows::fs::symlink_file`][std] /// -/// [std]: std::os::windows::fs::symlink_file +/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html pub async fn symlink_file(src: impl AsRef, dst: impl AsRef) -> io::Result<()> { let src = src.as_ref().to_owned(); let dst = dst.as_ref().to_owned(); diff --git a/tokio/src/io/stderr.rs b/tokio/src/io/stderr.rs index 2f624fba9d6..c62fc986685 100644 --- a/tokio/src/io/stderr.rs +++ b/tokio/src/io/stderr.rs @@ -80,10 +80,13 @@ impl std::os::unix::io::AsRawFd for Stderr { } } -#[cfg(windows)] -impl std::os::windows::io::AsRawHandle for Stderr { - fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { - std::io::stderr().as_raw_handle() +cfg_windows! { + use crate::os::windows::io::{AsRawHandle, RawHandle}; + + impl AsRawHandle for Stderr { + fn as_raw_handle(&self) -> RawHandle { + std::io::stderr().as_raw_handle() + } } } diff --git a/tokio/src/io/stdin.rs b/tokio/src/io/stdin.rs index c9578f17b64..2345f13726e 100644 --- a/tokio/src/io/stdin.rs +++ b/tokio/src/io/stdin.rs @@ -55,10 +55,13 @@ impl std::os::unix::io::AsRawFd for Stdin { } } -#[cfg(windows)] -impl std::os::windows::io::AsRawHandle for Stdin { - fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { - std::io::stdin().as_raw_handle() +cfg_windows! { + use crate::os::windows::io::{AsRawHandle, RawHandle}; + + impl AsRawHandle for Stdin { + fn as_raw_handle(&self) -> RawHandle { + std::io::stdin().as_raw_handle() + } } } diff --git a/tokio/src/io/stdout.rs b/tokio/src/io/stdout.rs index a08ed01eede..22e5e4b3300 100644 --- a/tokio/src/io/stdout.rs +++ b/tokio/src/io/stdout.rs @@ -79,10 +79,13 @@ impl std::os::unix::io::AsRawFd for Stdout { } } -#[cfg(windows)] -impl std::os::windows::io::AsRawHandle for Stdout { - fn as_raw_handle(&self) -> std::os::windows::io::RawHandle { - std::io::stdout().as_raw_handle() +cfg_windows! { + use crate::os::windows::io::{AsRawHandle, RawHandle}; + + impl AsRawHandle for Stdout { + fn as_raw_handle(&self) -> RawHandle { + std::io::stdout().as_raw_handle() + } } } diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 1c66d24147a..5c1c5c69b2d 100644 --- a/tokio/src/macros/cfg.rs +++ b/tokio/src/macros/cfg.rs @@ -13,6 +13,18 @@ macro_rules! feature { } } +/// Enables Windows-specific code. +/// Use this macro instead of `cfg(windows)` to generate docs properly. +macro_rules! cfg_windows { + ($($item:item)*) => { + $( + #[cfg(any(all(doc, docsrs), windows))] + #[cfg_attr(docsrs, doc(cfg(windows)))] + $item + )* + } +} + /// Enables enter::block_on. macro_rules! cfg_block_on { ($($item:item)*) => { diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 4441313703e..b5db2c586a4 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -423,10 +423,8 @@ cfg_unstable! { } } -#[cfg(windows)] -mod sys { - use super::TcpListener; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; impl AsRawSocket for TcpListener { fn as_raw_socket(&self) -> RawSocket { diff --git a/tokio/src/net/tcp/socket.rs b/tokio/src/net/tcp/socket.rs index 09349fe53eb..64286ce26fe 100644 --- a/tokio/src/net/tcp/socket.rs +++ b/tokio/src/net/tcp/socket.rs @@ -6,10 +6,12 @@ use std::net::SocketAddr; #[cfg(unix)] use std::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; -#[cfg(windows)] -use std::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket}; use std::time::Duration; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket}; +} + cfg_net! { /// A TCP socket that has not yet been converted to a `TcpStream` or /// `TcpListener`. @@ -758,30 +760,29 @@ impl IntoRawFd for TcpSocket { } } -#[cfg(windows)] -impl IntoRawSocket for TcpSocket { - fn into_raw_socket(self) -> RawSocket { - self.inner.into_raw_socket() +cfg_windows! { + impl IntoRawSocket for TcpSocket { + fn into_raw_socket(self) -> RawSocket { + self.inner.into_raw_socket() + } } -} -#[cfg(windows)] -impl AsRawSocket for TcpSocket { - fn as_raw_socket(&self) -> RawSocket { - self.inner.as_raw_socket() + impl AsRawSocket for TcpSocket { + fn as_raw_socket(&self) -> RawSocket { + self.inner.as_raw_socket() + } } -} -#[cfg(windows)] -impl FromRawSocket for TcpSocket { - /// Converts a `RawSocket` to a `TcpStream`. - /// - /// # Notes - /// - /// The caller is responsible for ensuring that the socket is in - /// non-blocking mode. - unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket { - let inner = socket2::Socket::from_raw_socket(socket); - TcpSocket { inner } + impl FromRawSocket for TcpSocket { + /// Converts a `RawSocket` to a `TcpStream`. + /// + /// # Notes + /// + /// The caller is responsible for ensuring that the socket is in + /// non-blocking mode. + unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket { + let inner = socket2::Socket::from_raw_socket(socket); + TcpSocket { inner } + } } } diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index b17d33feaea..636b83ea5e7 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -1344,10 +1344,8 @@ mod sys { } } -#[cfg(windows)] -mod sys { - use super::TcpStream; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; impl AsRawSocket for TcpStream { fn as_raw_socket(&self) -> RawSocket { diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 213d9149dad..3ab685e1e62 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -1691,7 +1691,7 @@ impl fmt::Debug for UdpSocket { } } -#[cfg(all(unix))] +#[cfg(unix)] mod sys { use super::UdpSocket; use std::os::unix::prelude::*; @@ -1703,10 +1703,8 @@ mod sys { } } -#[cfg(windows)] -mod sys { - use super::UdpSocket; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; impl AsRawSocket for UdpSocket { fn as_raw_socket(&self) -> RawSocket { diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index a6fac69a55b..759f0a69a9d 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -249,18 +249,21 @@ use std::convert::TryInto; use std::ffi::OsStr; use std::future::Future; use std::io; -#[cfg(unix)] -use std::os::unix::process::CommandExt; -#[cfg(windows)] -use std::os::windows::io::{AsRawHandle, RawHandle}; -#[cfg(windows)] -use std::os::windows::process::CommandExt; use std::path::Path; use std::pin::Pin; use std::process::{Command as StdCommand, ExitStatus, Output, Stdio}; use std::task::Context; use std::task::Poll; +#[cfg(unix)] +use std::os::unix::process::CommandExt; +#[cfg(windows)] +use std::os::windows::process::CommandExt; + +cfg_windows! { + use crate::os::windows::io::{AsRawHandle, RawHandle}; +} + /// This structure mimics the API of [`std::process::Command`] found in the standard library, but /// replaces functions that create a process with an asynchronous variant. The main provided /// asynchronous functions are [spawn](Command::spawn), [status](Command::status), and @@ -642,16 +645,16 @@ impl Command { self } - /// Sets the [process creation flags][1] to be passed to `CreateProcess`. - /// - /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`. - /// - /// [1]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx - #[cfg(windows)] - #[cfg_attr(docsrs, doc(cfg(windows)))] - pub fn creation_flags(&mut self, flags: u32) -> &mut Command { - self.std.creation_flags(flags); - self + cfg_windows! { + /// Sets the [process creation flags][1] to be passed to `CreateProcess`. + /// + /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`. + /// + /// [1]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx + pub fn creation_flags(&mut self, flags: u32) -> &mut Command { + self.std.creation_flags(flags); + self + } } /// Sets the child process's user ID. This translates to a @@ -1082,13 +1085,14 @@ impl Child { } } - /// Extracts the raw handle of the process associated with this child while - /// it is still running. Returns `None` if the child has exited. - #[cfg(windows)] - pub fn raw_handle(&self) -> Option { - match &self.child { - FusedChild::Child(c) => Some(c.inner.as_raw_handle()), - FusedChild::Done(_) => None, + cfg_windows! { + /// Extracts the raw handle of the process associated with this child while + /// it is still running. Returns `None` if the child has exited. + pub fn raw_handle(&self) -> Option { + match &self.child { + FusedChild::Child(c) => Some(c.inner.as_raw_handle()), + FusedChild::Done(_) => None, + } } } @@ -1323,7 +1327,7 @@ impl ChildStdin { } impl ChildStdout { - /// Creates an asynchronous `ChildStderr` from a synchronous one. + /// Creates an asynchronous `ChildStdout` from a synchronous one. /// /// # Errors /// @@ -1451,12 +1455,7 @@ mod sys { } } -#[cfg(windows)] -mod sys { - use std::os::windows::io::{AsRawHandle, RawHandle}; - - use super::{ChildStderr, ChildStdin, ChildStdout}; - +cfg_windows! { impl AsRawHandle for ChildStdin { fn as_raw_handle(&self) -> RawHandle { self.inner.as_raw_handle() From c4b7b620439d7b451c658398645bc377a8b892a1 Mon Sep 17 00:00:00 2001 From: Tymoteusz Date: Mon, 13 Mar 2023 12:13:17 +0100 Subject: [PATCH 2/2] doc: fix links to std docs --- tokio/src/doc/os.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tokio/src/doc/os.rs b/tokio/src/doc/os.rs index f63f774ca3d..9404d4491f2 100644 --- a/tokio/src/doc/os.rs +++ b/tokio/src/doc/os.rs @@ -44,21 +44,21 @@ pub mod windows { fn into_raw_socket(self) -> RawSocket; } - /// See [std::os::windows::io::BorrowedHandle](https://doc.rust-lang.org/stable/std/os/windows/io/struct.BorrowedHandle.html) + /// See [std::os::windows::io::BorrowedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html) pub type BorrowedHandle<'handle> = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsHandle](https://doc.rust-lang.org/stable/std/os/windows/io/trait.AsHandle.html) + /// See [std::os::windows::io::AsHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html) pub trait AsHandle { - /// See [std::os::windows::io::AsHandle::as_handle](https://doc.rust-lang.org/stable/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle) + /// See [std::os::windows::io::AsHandle::as_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle) fn as_handle(&self) -> BorrowedHandle<'_>; } - /// See [std::os::windows::io::BorrowedSocket](https://doc.rust-lang.org/stable/std/os/windows/io/struct.BorrowedSocket.html) + /// See [std::os::windows::io::BorrowedSocket](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html) pub type BorrowedSocket<'socket> = crate::doc::NotDefinedHere; - /// See [std::os::windows::io::AsSocket](https://doc.rust-lang.org/stable/std/os/windows/io/trait.AsSocket.html) + /// See [std::os::windows::io::AsSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html) pub trait AsSocket { - /// See [std::os::windows::io::AsSocket::as_socket](https://doc.rust-lang.org/stable/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket) + /// See [std::os::windows::io::AsSocket::as_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket) fn as_socket(&self) -> BorrowedSocket<'_>; } }