Skip to content

Commit

Permalink
enable windows-specific docs to build on non-windows
Browse files Browse the repository at this point in the history
  • Loading branch information
@udoprog
udoprog committed May 8, 2021
1 parent 7c07f79 commit ef03f09
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 46 deletions.
4 changes: 2 additions & 2 deletions tokio/src/macros/cfg.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,8 +186,8 @@ macro_rules! cfg_net_unix {
macro_rules! cfg_net_windows {
($($item:item)*) => {
$(
#[cfg(all(windows, feature = "net"))]
#[cfg_attr(docsrs, doc(cfg(feature = "net")))]
#[cfg(all(any(doc, windows), feature = "net"))]
#[cfg_attr(docsrs, doc(all(windows, cfg(feature = "net"))))]
$item
)*
}
Expand Down
117 changes: 73 additions & 44 deletions tokio/src/net/windows/named_pipe.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,68 @@ use std::ffi::OsStr;
use std::fmt;
use std::io;
use std::mem;
use std::os::windows::ffi::OsStrExt as _;
use std::os::windows::io::RawHandle;
use std::os::windows::io::{AsRawHandle, FromRawHandle};
use std::pin::Pin;
use std::ptr;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Duration;
use winapi::shared::minwindef::{DWORD, FALSE};
use winapi::um::fileapi;
use winapi::um::handleapi;
use winapi::um::namedpipeapi;
use winapi::um::winbase;
use winapi::um::winnt;

use crate::io::{AsyncRead, AsyncWrite, Interest, PollEvented, ReadBuf};
use crate::net::asyncify;

// Interned constant to wait forever. Not available in winapi.
const NMPWAIT_WAIT_FOREVER: DWORD = 0xffffffff;
// This module permits rustdoc to work by hiding non-existant items for other
// platforms.
#[cfg(not(doc))]
mod sys {
pub(super) use mio::windows as mio_windows;
pub(super) use std::os::windows::ffi::OsStrExt;
pub(super) use std::os::windows::io::RawHandle;
pub(super) use std::os::windows::io::{AsRawHandle, FromRawHandle};
pub(super) use winapi::shared::minwindef::{DWORD, FALSE};
pub(super) use winapi::um::fileapi;
pub(super) use winapi::um::handleapi;
pub(super) use winapi::um::namedpipeapi;
pub(super) use winapi::um::winbase;
pub(super) use winapi::um::winnt;

// Interned constant to wait forever. Not available in winapi.
pub(super) const NMPWAIT_WAIT_FOREVER: DWORD = 0xffffffff;

/// Raw handle conversion for [NamedPipe].
///
/// # Panics
///
/// This panics if called outside of a [Tokio Runtime] which doesn't have [I/O
/// enabled].
///
/// [Tokio Runtime]: crate::runtime::Runtime
/// [I/O enabled]: crate::runtime::Builder::enable_io
impl FromRawHandle for super::NamedPipe {
unsafe fn from_raw_handle(handle: RawHandle) -> Self {
Self::try_from_raw_handle(handle).unwrap()
}
}

impl AsRawHandle for super::NamedPipe {
fn as_raw_handle(&self) -> RawHandle {
self.io.as_raw_handle()
}
}
}

// Stubs needed when generating documentation. None of these show up in public
// docs, but because they are present in function signatures rustdoc needs them.
#[cfg(doc)]
mod sys {
pub(super) type DWORD = u32;
pub(super) type RawHandle = ();

pub(super) mod mio_windows {
pub type NamedPipe = ();
}
}

use self::sys::*;

/// A [Windows named pipe].
///
Expand Down Expand Up @@ -121,12 +163,12 @@ const NMPWAIT_WAIT_FOREVER: DWORD = 0xffffffff;
/// ```
///
/// [create]: NamedPipeClientBuilder::create
/// [ERROR_PIPE_BUSY]: winapi::shared::winerror::ERROR_PIPE_BUSY
/// [ERROR_PIPE_BUSY]: ::winapi::shared::winerror::ERROR_PIPE_BUSY
/// [wait]: NamedPipeClientBuilder::wait
/// [Windows named pipe]: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
#[derive(Debug)]
pub struct NamedPipe {
io: PollEvented<mio::windows::NamedPipe>,
io: PollEvented<mio_windows::NamedPipe>,
}

impl NamedPipe {
Expand All @@ -149,7 +191,7 @@ impl NamedPipe {
/// [Tokio Runtime]: crate::runtime::Runtime
/// [I/O enabled]: crate::runtime::RuntimeBuilder::enable_io
unsafe fn try_from_raw_handle(handle: RawHandle) -> io::Result<Self> {
let named_pipe = mio::windows::NamedPipe::from_raw_handle(handle);
let named_pipe = mio_windows::NamedPipe::from_raw_handle(handle);

Ok(NamedPipe {
io: PollEvented::new(named_pipe)?,
Expand Down Expand Up @@ -335,27 +377,6 @@ impl AsyncWrite for NamedPipe {
}
}

/// Raw handle conversion for [NamedPipe].
///
/// # Panics
///
/// This panics if called outside of a [Tokio Runtime] which doesn't have [I/O
/// enabled].
///
/// [Tokio Runtime]: crate::runtime::Runtime
/// [I/O enabled]: crate::runtime::Builder::enable_io
impl FromRawHandle for NamedPipe {
unsafe fn from_raw_handle(handle: RawHandle) -> Self {
Self::try_from_raw_handle(handle).unwrap()
}
}

impl AsRawHandle for NamedPipe {
fn as_raw_handle(&self) -> RawHandle {
self.io.as_raw_handle()
}
}

// Helper to set a boolean flag as a bitfield.
macro_rules! bool_flag {
($f:expr, $t:expr, $flag:expr) => {{
Expand Down Expand Up @@ -562,7 +583,7 @@ impl NamedPipeBuilder {
///
/// This corresponds to setting [FILE_FLAG_FIRST_PIPE_INSTANCE].
///
/// [ERROR_ACCESS_DENIED]: winapi::shared::winerror::ERROR_ACCESS_DENIED
/// [ERROR_ACCESS_DENIED]: ::winapi::shared::winerror::ERROR_ACCESS_DENIED
/// [FILE_FLAG_FIRST_PIPE_INSTANCE]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createnamedpipea#pipe_first_pipe_instance
///
/// # Examples
Expand Down Expand Up @@ -708,7 +729,7 @@ impl NamedPipeBuilder {
return Err(io::Error::last_os_error());
}

let io = mio::windows::NamedPipe::from_raw_handle(h);
let io = mio_windows::NamedPipe::from_raw_handle(h);
let io = PollEvented::new(io)?;

Ok(NamedPipe { io })
Expand Down Expand Up @@ -976,7 +997,8 @@ impl NamedPipeClientBuilder {
/// [winapi]. This error is raised when the named pipe has been created,
/// but the server is not currently waiting for a connection.
///
/// [ERROR_PIPE_BUSY]: winapi::shared::winerror::ERROR_PIPE_BUSY
/// [winapi]: ::winapi
/// [ERROR_PIPE_BUSY]: ::winapi::shared::winerror::ERROR_PIPE_BUSY
///
/// The generic connect loop looks like this.
///
Expand Down Expand Up @@ -1042,7 +1064,7 @@ impl NamedPipeClientBuilder {
return Err(io::Error::last_os_error());
}

let io = mio::windows::NamedPipe::from_raw_handle(h);
let io = mio_windows::NamedPipe::from_raw_handle(h);
let io = PollEvented::new(io)?;

Ok(NamedPipe { io })
Expand All @@ -1067,16 +1089,19 @@ pub enum PipeMode {
/// Data is written to the pipe as a stream of bytes. The pipe does not
/// distinguish bytes written during different write operations.
///
/// Corresponds to [PIPE_TYPE_BYTE][winbase::PIPE_TYPE_BYTE].
/// Corresponds to [PIPE_TYPE_BYTE].
///
/// [PIPE_TYPE_BYTE]: ::winapi::um::winbase::PIPE_TYPE_BYTE
Byte,
/// Data is written to the pipe as a stream of messages. The pipe treats the
/// bytes written during each write operation as a message unit. Any reading
/// function on [NamedPipe] returns [ERROR_MORE_DATA] when a message is not
/// read completely.
///
/// Corresponds to [PIPE_TYPE_MESSAGE][winbase::PIPE_TYPE_MESSAGE].
/// Corresponds to [PIPE_TYPE_MESSAGE].
///
/// [ERROR_MORE_DATA]: winapi::shared::winerror::ERROR_MORE_DATA
/// [ERROR_MORE_DATA]: ::winapi::shared::winerror::ERROR_MORE_DATA
/// [PIPE_TYPE_MESSAGE]: ::winapi::um::winbase::PIPE_TYPE_MESSAGE
Message,
}

Expand All @@ -1086,11 +1111,15 @@ pub enum PipeMode {
pub enum PipeEnd {
/// The [NamedPipe] refers to the client end of a named pipe instance.
///
/// Corresponds to [PIPE_CLIENT_END][winbase::PIPE_CLIENT_END].
/// Corresponds to [PIPE_CLIENT_END].
///
/// [PIPE_CLIENT_END]: ::winapi::um::winbase::PIPE_CLIENT_END
Client,
/// The [NamedPipe] refers to the server end of a named pipe instance.
///
/// Corresponds to [PIPE_SERVER_END][winbase::PIPE_SERVER_END].
/// Corresponds to [PIPE_SERVER_END].
///
/// [PIPE_SERVER_END]: ::winapi::um::winbase::PIPE_SERVER_END
Server,
}

Expand Down

0 comments on commit ef03f09

Please sign in to comment.