diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs index 5a68d307665..ed3a9b85682 100644 --- a/tokio/src/io/async_fd.rs +++ b/tokio/src/io/async_fd.rs @@ -3,7 +3,7 @@ use crate::io::driver::{Handle, Interest, ReadyEvent, Registration}; use mio::unix::SourceFd; use std::io; use std::os::unix::io::{AsRawFd, RawFd}; -use std::{task::Context, task::Poll}; +use std::task::{Context, Poll}; /// Associates an IO object backed by a Unix file descriptor with the tokio /// reactor, allowing for readiness to be polled. The file descriptor must be of diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 3442612938b..bc61214d24e 100644 --- a/tokio/src/macros/cfg.rs +++ b/tokio/src/macros/cfg.rs @@ -1,5 +1,44 @@ #![allow(unused_macros)] +/// Helper for rustdoc to generate cross platform documentation. +/// +/// This implements the approach taken by libstd and documented in [advanced +/// features of +/// rustdoc](https://doc.rust-lang.org/rustdoc/advanced-features.html). +/// +/// We leverage that the content of functions are largely ignored by rustdoc, +/// and provide the ability to mock anything that is required for rustdoc to +/// compile documentation on other platforms +/// +/// This does have a few downsides: +/// * Anything outlined in the `mock` section won't *correctly* link to the +/// correct upstream crate for types used *unless* it's built for that +/// platform. +/// * Trait implementations that mentions types in the `mock` section won't be +/// visible in generated documentation *unless* it's built for that platform. +macro_rules! doc_prelude { + ( + $vis:vis mod stub {$($stubs:tt)* } + $(#[cfg($($meta:meta)*)] { $($items:tt)* })* + ) => { + #[cfg(docsrs)] + #[doc(hidden)] + $vis mod doc { + $($stubs)* + } + + $( + #[cfg(all(not(docsrs), $($meta)*))] + #[doc(hidden)] + $vis mod doc { + $($items)* + } + )* + + $vis use self::doc::*; + } +} + macro_rules! feature { ( #![$meta:meta] @@ -177,7 +216,7 @@ macro_rules! cfg_net_unix { ($($item:item)*) => { $( #[cfg(all(unix, feature = "net"))] - #[cfg_attr(docsrs, doc(cfg(feature = "net")))] + #[cfg_attr(docsrs, doc(cfg(all(unix, feature = "net"))))] $item )* } diff --git a/tokio/src/net/unix/datagram/socket.rs b/tokio/src/net/unix/datagram/socket.rs index 6bc5615917c..d477bda10ad 100644 --- a/tokio/src/net/unix/datagram/socket.rs +++ b/tokio/src/net/unix/datagram/socket.rs @@ -399,11 +399,11 @@ impl UnixDatagram { /// [`tokio::net::UnixDatagram`]: UnixDatagram /// [`std::os::unix::net::UnixDatagram`]: std::os::unix::net::UnixDatagram /// [`set_nonblocking`]: fn@std::os::unix::net::UnixDatagram::set_nonblocking - pub fn into_std(self) -> io::Result { + pub fn into_std(self) -> io::Result { self.io .into_inner() .map(|io| io.into_raw_fd()) - .map(|raw_fd| unsafe { std::os::unix::net::UnixDatagram::from_raw_fd(raw_fd) }) + .map(|raw_fd| unsafe { net::UnixDatagram::from_raw_fd(raw_fd) }) } fn new(socket: mio::net::UnixDatagram) -> io::Result { @@ -1249,14 +1249,14 @@ impl UnixDatagram { } } -impl TryFrom for UnixDatagram { +impl TryFrom for UnixDatagram { type Error = io::Error; /// Consumes stream, returning the Tokio I/O object. /// /// This is equivalent to /// [`UnixDatagram::from_std(stream)`](UnixDatagram::from_std). - fn try_from(stream: std::os::unix::net::UnixDatagram) -> Result { + fn try_from(stream: net::UnixDatagram) -> Result { Self::from_std(stream) } } diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index b5b05a6935d..bfdc3a5b719 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -110,7 +110,7 @@ impl UnixListener { /// [`tokio::net::UnixListener`]: UnixListener /// [`std::os::unix::net::UnixListener`]: std::os::unix::net::UnixListener /// [`set_nonblocking`]: fn@std::os::unix::net::UnixListener::set_nonblocking - pub fn into_std(self) -> io::Result { + pub fn into_std(self) -> io::Result { self.io .into_inner() .map(|io| io.into_raw_fd()) @@ -154,14 +154,14 @@ impl UnixListener { } } -impl TryFrom for UnixListener { +impl TryFrom for UnixListener { type Error = io::Error; /// Consumes stream, returning the tokio I/O object. /// /// This is equivalent to /// [`UnixListener::from_std(stream)`](UnixListener::from_std). - fn try_from(stream: std::os::unix::net::UnixListener) -> io::Result { + fn try_from(stream: net::UnixListener) -> io::Result { Self::from_std(stream) } } diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs index d797aae0700..e6d99fc2819 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -546,11 +546,11 @@ impl UnixStream { /// [`tokio::net::UnixStream`]: UnixStream /// [`std::os::unix::net::UnixStream`]: std::os::unix::net::UnixStream /// [`set_nonblocking`]: fn@std::os::unix::net::UnixStream::set_nonblocking - pub fn into_std(self) -> io::Result { + pub fn into_std(self) -> io::Result { self.io .into_inner() .map(|io| io.into_raw_fd()) - .map(|raw_fd| unsafe { std::os::unix::net::UnixStream::from_raw_fd(raw_fd) }) + .map(|raw_fd| unsafe { net::UnixStream::from_raw_fd(raw_fd) }) } /// Creates an unnamed pair of connected sockets. diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index 9f8d256913b..1274c703154 100644 --- a/tokio/src/signal/unix.rs +++ b/tokio/src/signal/unix.rs @@ -4,12 +4,12 @@ //! `Signal` type for receiving notifications of signals. #![cfg(unix)] +#![cfg_attr(docsrs, doc(cfg(all(unix, feature = "signal"))))] use crate::signal::registry::{globals, EventId, EventInfo, Globals, Init, Storage}; use crate::signal::RxFuture; use crate::sync::watch; -use mio::net::UnixStream; use std::io::{self, Error, ErrorKind, Write}; use std::pin::Pin; use std::sync::atomic::{AtomicBool, Ordering}; @@ -46,13 +46,13 @@ impl Storage for OsStorage { #[derive(Debug)] pub(crate) struct OsExtraData { - sender: UnixStream, - receiver: UnixStream, + sender: mio::net::UnixStream, + receiver: mio::net::UnixStream, } impl Init for OsExtraData { fn init() -> Self { - let (receiver, sender) = UnixStream::pair().expect("failed to create UnixStream"); + let (receiver, sender) = mio::net::UnixStream::pair().expect("failed to create UnixStream"); Self { sender, receiver } } diff --git a/tokio/src/signal/unix/driver.rs b/tokio/src/signal/unix/driver.rs index 315f3bd5830..a1cf0c430e6 100644 --- a/tokio/src/signal/unix/driver.rs +++ b/tokio/src/signal/unix/driver.rs @@ -9,6 +9,8 @@ use crate::signal::registry::globals; use mio::net::UnixStream; use std::io::{self, Read}; +use std::os::unix::io::{AsRawFd, FromRawFd}; +use std::os::unix::net; use std::ptr; use std::sync::{Arc, Weak}; use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker}; @@ -45,7 +47,6 @@ impl Driver { /// Creates a new signal `Driver` instance that delegates wakeups to `park`. pub(crate) fn new(park: IoDriver) -> io::Result { use std::mem::ManuallyDrop; - use std::os::unix::io::{AsRawFd, FromRawFd}; // NB: We give each driver a "fresh" reciever file descriptor to avoid // the issues described in alexcrichton/tokio-process#42. @@ -71,8 +72,7 @@ impl Driver { let receiver_fd = globals().receiver.as_raw_fd(); // safety: there is nothing unsafe about this, but the `from_raw_fd` fn is marked as unsafe. - let original = - ManuallyDrop::new(unsafe { std::os::unix::net::UnixStream::from_raw_fd(receiver_fd) }); + let original = ManuallyDrop::new(unsafe { net::UnixStream::from_raw_fd(receiver_fd) }); let receiver = UnixStream::from_std(original.try_clone()?); let receiver = PollEvented::new_with_interest_and_handle( receiver, diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index c231d6268b4..5beedc5c998 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -5,7 +5,8 @@ //! `SetConsoleCtrlHandler` function which receives events of the type //! `CTRL_C_EVENT` and `CTRL_BREAK_EVENT`. -#![cfg(windows)] +#![cfg(any(docsrs, windows))] +#![cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))] use crate::signal::registry::{globals, EventId, EventInfo, Init, Storage}; use crate::signal::RxFuture; @@ -14,9 +15,20 @@ use std::convert::TryFrom; use std::io; use std::sync::Once; use std::task::{Context, Poll}; -use winapi::shared::minwindef::{BOOL, DWORD, FALSE, TRUE}; -use winapi::um::consoleapi::SetConsoleCtrlHandler; -use winapi::um::wincon::{CTRL_BREAK_EVENT, CTRL_C_EVENT}; + +// helps rustdoc on non-unix platforms. +doc_prelude! { + mod stub { + pub(super) struct DWORD(()); + pub(super) struct BOOL(()); + } + + #[cfg(windows)] { + pub(super) use winapi::shared::minwindef::{BOOL, DWORD, FALSE, TRUE}; + pub(super) use winapi::um::consoleapi::SetConsoleCtrlHandler; + pub(super) use winapi::um::wincon::{CTRL_BREAK_EVENT, CTRL_C_EVENT}; + } +} #[derive(Debug)] pub(crate) struct OsStorage {