Is ClientOptions::open() expected to be called directly from async tasks?

[spellsaif]

Hi,

I’m working on a reqwest PR seanmonstar/reqwest#3086 involving Windows named pipes and wanted to clarify the intended behavior of Tokio’s ClientOptions::open().

ClientOptions::open() calls the Windows CreateFileW API synchronously, while the resulting pipe handle uses FILE_FLAG_OVERLAPPED.

Is ClientOptions::open() intentionally synchronous, and is it expected to be called directly from an async task? Or should callers take any precautions to avoid potentially blocking a Tokio worker thread during pipe creation?

I’d like to understand the intended API semantics before deciding whether this belongs in reqwest or Tokio.

Thanks!

[gitsult4n]

ClientOptions::open() is indeed synchronous end-to-end — CreateFileW is invoked directly on the calling thread, and it is not wrapped in spawn_blocking anywhere in Tokio. Calling it directly from an async task is also, in practice, the pattern Tokio itself demonstrates: it's exactly what the doc example above open() does. That much is verifiable directly from the source. Whether this was a deliberate, discussed design decision by the maintainers (versus simply "the obvious way to write it, and nobody has revisited it") I could not confirm — I checked tokio-rs/tokio's issues, PRs, and the file's git history for any explanation of the tradeoff and found none, so treat the "why" below as informed inference, not a documented decision.

The implementation

tokio/src/net/windows/named_pipe.rs:

pub fn open(&self, addr: impl AsRef<OsStr>) -> io::Result<NamedPipeClient> {
    // Safety: We're calling open_with_security_attributes_raw w/ a null
    // pointer which disables it.
    unsafe { self.open_with_security_attributes_raw(addr, ptr::null_mut()) }
}

pub unsafe fn open_with_security_attributes_raw(
    &self,
    addr: impl AsRef<OsStr>,
    attrs: *mut c_void,
) -> io::Result<NamedPipeClient> {
    ...
    let h = unsafe {
        windows_sys::CreateFileW(
            addr.as_ptr(),
            desired_access,
            0,
            attrs as *mut _,
            windows_sys::OPEN_EXISTING,
            self.get_flags(),
            null_mut(),
        )
    };

    if h == windows_sys::INVALID_HANDLE_VALUE {
        return Err(io::Error::last_os_error());
    }
    ...
    unsafe { NamedPipeClient::from_raw_handle(h as _) }
}

get_flags() just ORs in FILE_FLAG_OVERLAPPED:

fn get_flags(&self) -> u32 {
    self.security_qos_flags | windows_sys::FILE_FLAG_OVERLAPPED
}

FILE_FLAG_OVERLAPPED only affects how the resulting handle behaves for later ReadFile/WriteFile (it makes those overlapped/IOCP-driven, which is how the rest of NamedPipeClient gets async reads/writes). It has no effect on the CreateFileW call itself.

Why CreateFileW can't be made async, structurally

This is the part worth being precise about, because it's easy to reach for the wrong explanation. CreateFileW's signature simply has no LPOVERLAPPED parameter — unlike ConnectNamedPipe, ReadFile, WriteFile, and DeviceIoControl, which all take one and can be driven through IOCP. There is no Win32 mechanism to open a file/pipe handle asynchronously at all, independent of how long that particular open happens to take. FILE_FLAG_OVERLAPPED configures the handle for overlapped I/O after it exists; it can't make the act of creating the handle overlapped, because the OS gives you nothing to register with a completion port until the handle already exists.

So the fail-fast behavior the docs describe (NotFound if no server, ERROR_PIPE_BUSY if all instances are taken — see the doc comment's bullets) doesn't explain why Tokio can't do this asynchronously; it explains why the lack of async-ness is usually cheap in practice. Even a client-side open that took a long time (a remote/UNC pipe path, filesystem-filter-driver/AV contention) would still have to go through a synchronous CreateFileW call — the only way to avoid blocking a worker thread on that would be to hop to a blocking-pool thread (spawn_blocking), exactly what the reqwest PR below does. Tokio simply doesn't do that hop itself.

The doc example shows this is the pattern in practice

The doc comment directly above open() shows the retry loop:

/// # #[tokio::main] async fn main() -> std::io::Result<()> {
/// let client = loop {
///     match ClientOptions::new().open(PIPE_NAME) {
///         Ok(client) => break client,
///         Err(e) if e.raw_os_error() == Some(ERROR_PIPE_BUSY as i32) => (),
///         Err(e) => return Err(e),
///     }
///
///     time::sleep(Duration::from_millis(50)).await;
/// };

.open() is called directly, synchronously, inside async fn main, with the .await only on the time::sleep backoff — not on the open call. Whatever the original rationale, this is the pattern Tokio's own example puts in front of users, and it contains no caveat about worker-thread blocking.

Contrast with the server side

NamedPipeServer::connect genuinely is async:

pub async fn connect(&self) -> io::Result<()> {
    match self.io.connect() {
        Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
            self.io
                .registration()
                .async_io(Interest::WRITABLE, || self.io.connect())
                .await
        }
        x => x,
    }
}

This works because ConnectNamedPipe does accept an OVERLAPPED argument at the OS level, so Tokio can register it with the reactor and let it complete via IOCP instead of blocking a thread. There's no equivalent path available for CreateFileW.

Practical takeaway for the reqwest PR

Given the above, Tokio's public API doesn't require spawn_blocking for .open(), and calling it inline — as the doc example does — is the pattern Tokio itself shows. That said, CreateFileW is a real synchronous kernel call with no async alternative in the Win32 API: for remote/UNC pipe paths, or under filesystem-filter-driver contention (AV, EDR agents), it can take longer than the near-instant case the doc example is implicitly optimized for. Since reqwest is a general-purpose client that can't assume a friendly local-only pipe, wrapping it in spawn_blocking as done in seanmonstar/reqwest#3086 looks like a reasonable defensive choice for that codebase, even though it's not something Tokio's own docs push callers toward.

[spellsaif]

Thanks for such a detailed answer. It now makes more sense. Arigato