From 4ea632005d689f850e87a116b9e535a0015a7a0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tymoteusz=20Wi=C5=9Bniewski?= Date: Tue, 14 Mar 2023 23:33:31 +0100 Subject: [PATCH] tokio: make all windows docs visible in unix builds (#5530) --- tokio/src/doc/os.rs | 30 +++++++++++++++++ tokio/src/fs/file.rs | 38 +++++++++++---------- 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 | 9 ++--- tokio/src/io/stdin.rs | 9 ++--- tokio/src/io/stdout.rs | 9 ++--- tokio/src/macros/cfg.rs | 12 +++++++ tokio/src/net/tcp/listener.rs | 8 ++--- tokio/src/net/tcp/socket.rs | 61 ++++++++++++++++----------------- tokio/src/net/tcp/stream.rs | 8 ++--- tokio/src/net/udp.rs | 8 ++--- tokio/src/process/mod.rs | 63 +++++++++++++++++------------------ 15 files changed, 155 insertions(+), 121 deletions(-) diff --git a/tokio/src/doc/os.rs b/tokio/src/doc/os.rs index 4365150f645..9404d4491f2 100644 --- a/tokio/src/doc/os.rs +++ b/tokio/src/doc/os.rs @@ -23,6 +23,27 @@ pub mod windows { 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; + } + /// 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; @@ -31,5 +52,14 @@ pub mod windows { /// 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/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/std/os/windows/io/trait.AsSocket.html) + pub trait AsSocket { + /// 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<'_>; + } } } diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs index bd8c9c27165..795a38f7814 100644 --- a/tokio/src/fs/file.rs +++ b/tokio/src/fs/file.rs @@ -741,28 +741,32 @@ 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}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsHandle, BorrowedHandle}; + + impl AsRawHandle for File { + fn as_raw_handle(&self) -> RawHandle { + self.std.as_raw_handle() + } } -} -#[cfg(all(windows, not(tokio_no_as_fd)))] -impl std::os::windows::io::AsHandle for File { - fn as_handle(&self) -> std::os::windows::io::BorrowedHandle<'_> { - unsafe { - std::os::windows::io::BorrowedHandle::borrow_raw( - std::os::windows::io::AsRawHandle::as_raw_handle(self), - ) + #[cfg(not(tokio_no_as_fd))] + impl AsHandle for File { + fn as_handle(&self) -> BorrowedHandle<'_> { + unsafe { + BorrowedHandle::borrow_raw( + AsRawHandle::as_raw_handle(self), + ) + } } } -} -#[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 565d9b61c80..2119c6d6ce9 100644 --- a/tokio/src/io/stderr.rs +++ b/tokio/src/io/stderr.rs @@ -95,13 +95,10 @@ mod sys { } } -#[cfg(windows)] -mod sys { +cfg_windows! { #[cfg(not(tokio_no_as_fd))] - use std::os::windows::io::{AsHandle, BorrowedHandle}; - use std::os::windows::io::{AsRawHandle, RawHandle}; - - use super::Stderr; + use crate::os::windows::io::{AsHandle, BorrowedHandle}; + use crate::os::windows::io::{AsRawHandle, RawHandle}; impl AsRawHandle for Stderr { fn as_raw_handle(&self) -> RawHandle { diff --git a/tokio/src/io/stdin.rs b/tokio/src/io/stdin.rs index 2c4abb4eaab..04cced425ff 100644 --- a/tokio/src/io/stdin.rs +++ b/tokio/src/io/stdin.rs @@ -70,13 +70,10 @@ mod sys { } } -#[cfg(windows)] -mod sys { +cfg_windows! { #[cfg(not(tokio_no_as_fd))] - use std::os::windows::io::{AsHandle, BorrowedHandle}; - use std::os::windows::io::{AsRawHandle, RawHandle}; - - use super::Stdin; + use crate::os::windows::io::{AsHandle, BorrowedHandle}; + use crate::os::windows::io::{AsRawHandle, RawHandle}; impl AsRawHandle for Stdin { fn as_raw_handle(&self) -> RawHandle { diff --git a/tokio/src/io/stdout.rs b/tokio/src/io/stdout.rs index d957ddb2a11..f52bf5a4bcf 100644 --- a/tokio/src/io/stdout.rs +++ b/tokio/src/io/stdout.rs @@ -94,13 +94,10 @@ mod sys { } } -#[cfg(windows)] -mod sys { +cfg_windows! { #[cfg(not(tokio_no_as_fd))] - use std::os::windows::io::{AsHandle, BorrowedHandle}; - use std::os::windows::io::{AsRawHandle, RawHandle}; - - use super::Stdout; + use crate::os::windows::io::{AsHandle, BorrowedHandle}; + use crate::os::windows::io::{AsRawHandle, RawHandle}; impl AsRawHandle for Stdout { fn as_raw_handle(&self) -> RawHandle { 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 825e960e6d9..0e429761d25 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -437,10 +437,10 @@ cfg_unstable! { } } -#[cfg(windows)] -mod sys { - use super::TcpListener; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsSocket, BorrowedSocket}; 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 9c76e040857..1c36d3a88df 100644 --- a/tokio/src/net/tcp/socket.rs +++ b/tokio/src/net/tcp/socket.rs @@ -8,12 +8,14 @@ use std::net::SocketAddr; use std::os::unix::io::{AsFd, BorrowedFd}; #[cfg(unix)] use std::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; -#[cfg(windows)] -use std::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket}; -#[cfg(all(windows, not(tokio_no_as_fd)))] -use std::os::windows::io::{AsSocket, BorrowedSocket}; use std::time::Duration; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsSocket, BorrowedSocket}; +} + cfg_net! { /// A TCP socket that has not yet been converted to a `TcpStream` or /// `TcpListener`. @@ -769,37 +771,36 @@ 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(all(windows, not(tokio_no_as_fd)))] -impl AsSocket for TcpSocket { - fn as_socket(&self) -> BorrowedSocket<'_> { - unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) } + #[cfg(not(tokio_no_as_fd))] + impl AsSocket for TcpSocket { + fn as_socket(&self) -> BorrowedSocket<'_> { + unsafe { BorrowedSocket::borrow_raw(self.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 30f4cff75d4..2ea6da2de74 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -1387,10 +1387,10 @@ mod sys { } } -#[cfg(windows)] -mod sys { - use super::TcpStream; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsSocket, BorrowedSocket}; 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 4b561110342..e7a65f1b29d 100644 --- a/tokio/src/net/udp.rs +++ b/tokio/src/net/udp.rs @@ -1746,10 +1746,10 @@ mod sys { } } -#[cfg(windows)] -mod sys { - use super::UdpSocket; - use std::os::windows::prelude::*; +cfg_windows! { + use crate::os::windows::io::{AsRawSocket, RawSocket}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsSocket, BorrowedSocket}; 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 8f32b2d4776..d4ba1bacc9d 100644 --- a/tokio/src/process/mod.rs +++ b/tokio/src/process/mod.rs @@ -249,18 +249,23 @@ 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}; + #[cfg(not(tokio_no_as_fd))] + use crate::os::windows::io::{AsHandle, BorrowedHandle}; +} + /// 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 +647,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 +1087,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 +1329,7 @@ impl ChildStdin { } impl ChildStdout { - /// Creates an asynchronous `ChildStderr` from a synchronous one. + /// Creates an asynchronous `ChildStdout` from a synchronous one. /// /// # Errors /// @@ -1474,14 +1480,7 @@ mod sys { } } -#[cfg(windows)] -mod sys { - #[cfg(not(tokio_no_as_fd))] - use std::os::windows::io::{AsHandle, BorrowedHandle}; - 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()