std\sys\pal\windows/
pipe.rs

1use crate::ffi::OsStr;
2use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut};
3use crate::os::windows::prelude::*;
4use crate::path::Path;
5use crate::random::{DefaultRandomSource, Random};
6use crate::sync::atomic::Ordering::Relaxed;
7use crate::sync::atomic::{Atomic, AtomicUsize};
8use crate::sys::c;
9use crate::sys::fs::{File, OpenOptions};
10use crate::sys::handle::Handle;
11use crate::sys::pal::windows::api::{self, WinError};
12use crate::sys_common::{FromInner, IntoInner};
13use crate::{mem, ptr};
14
15////////////////////////////////////////////////////////////////////////////////
16// Anonymous pipes
17////////////////////////////////////////////////////////////////////////////////
18
19pub struct AnonPipe {
20    inner: Handle,
21}
22
23impl IntoInner<Handle> for AnonPipe {
24    fn into_inner(self) -> Handle {
25        self.inner
26    }
27}
28
29impl FromInner<Handle> for AnonPipe {
30    fn from_inner(inner: Handle) -> AnonPipe {
31        Self { inner }
32    }
33}
34
35pub struct Pipes {
36    pub ours: AnonPipe,
37    pub theirs: AnonPipe,
38}
39
40/// Although this looks similar to `anon_pipe` in the Unix module it's actually
41/// subtly different. Here we'll return two pipes in the `Pipes` return value,
42/// but one is intended for "us" where as the other is intended for "someone
43/// else".
44///
45/// Currently the only use case for this function is pipes for stdio on
46/// processes in the standard library, so "ours" is the one that'll stay in our
47/// process whereas "theirs" will be inherited to a child.
48///
49/// The ours/theirs pipes are *not* specifically readable or writable. Each
50/// one only supports a read or a write, but which is which depends on the
51/// boolean flag given. If `ours_readable` is `true`, then `ours` is readable and
52/// `theirs` is writable. Conversely, if `ours_readable` is `false`, then `ours`
53/// is writable and `theirs` is readable.
54///
55/// Also note that the `ours` pipe is always a handle opened up in overlapped
56/// mode. This means that technically speaking it should only ever be used
57/// with `OVERLAPPED` instances, but also works out ok if it's only ever used
58/// once at a time (which we do indeed guarantee).
59pub fn anon_pipe(ours_readable: bool, their_handle_inheritable: bool) -> io::Result<Pipes> {
60    // A 64kb pipe capacity is the same as a typical Linux default.
61    const PIPE_BUFFER_CAPACITY: u32 = 64 * 1024;
62
63    // Note that we specifically do *not* use `CreatePipe` here because
64    // unfortunately the anonymous pipes returned do not support overlapped
65    // operations. Instead, we create a "hopefully unique" name and create a
66    // named pipe which has overlapped operations enabled.
67    //
68    // Once we do this, we connect do it as usual via `CreateFileW`, and then
69    // we return those reader/writer halves. Note that the `ours` pipe return
70    // value is always the named pipe, whereas `theirs` is just the normal file.
71    // This should hopefully shield us from child processes which assume their
72    // stdout is a named pipe, which would indeed be odd!
73    unsafe {
74        let ours;
75        let mut name;
76        let mut tries = 0;
77        loop {
78            tries += 1;
79            name = format!(
80                r"\\.\pipe\__rust_anonymous_pipe1__.{}.{}",
81                c::GetCurrentProcessId(),
82                random_number(),
83            );
84            let wide_name = OsStr::new(&name).encode_wide().chain(Some(0)).collect::<Vec<_>>();
85            let mut flags = c::FILE_FLAG_FIRST_PIPE_INSTANCE | c::FILE_FLAG_OVERLAPPED;
86            if ours_readable {
87                flags |= c::PIPE_ACCESS_INBOUND;
88            } else {
89                flags |= c::PIPE_ACCESS_OUTBOUND;
90            }
91
92            let handle = c::CreateNamedPipeW(
93                wide_name.as_ptr(),
94                flags,
95                c::PIPE_TYPE_BYTE
96                    | c::PIPE_READMODE_BYTE
97                    | c::PIPE_WAIT
98                    | c::PIPE_REJECT_REMOTE_CLIENTS,
99                1,
100                PIPE_BUFFER_CAPACITY,
101                PIPE_BUFFER_CAPACITY,
102                0,
103                ptr::null_mut(),
104            );
105
106            // We pass the `FILE_FLAG_FIRST_PIPE_INSTANCE` flag above, and we're
107            // also just doing a best effort at selecting a unique name. If
108            // `ERROR_ACCESS_DENIED` is returned then it could mean that we
109            // accidentally conflicted with an already existing pipe, so we try
110            // again.
111            //
112            // Don't try again too much though as this could also perhaps be a
113            // legit error.
114            if handle == c::INVALID_HANDLE_VALUE {
115                let error = api::get_last_error();
116                if tries < 10 && error == WinError::ACCESS_DENIED {
117                    continue;
118                } else {
119                    return Err(io::Error::from_raw_os_error(error.code as i32));
120                }
121            }
122
123            ours = Handle::from_raw_handle(handle);
124            break;
125        }
126
127        // Connect to the named pipe we just created. This handle is going to be
128        // returned in `theirs`, so if `ours` is readable we want this to be
129        // writable, otherwise if `ours` is writable we want this to be
130        // readable.
131        //
132        // Additionally we don't enable overlapped mode on this because most
133        // client processes aren't enabled to work with that.
134        let mut opts = OpenOptions::new();
135        opts.write(ours_readable);
136        opts.read(!ours_readable);
137        opts.share_mode(0);
138        let size = size_of::<c::SECURITY_ATTRIBUTES>();
139        let mut sa = c::SECURITY_ATTRIBUTES {
140            nLength: size as u32,
141            lpSecurityDescriptor: ptr::null_mut(),
142            bInheritHandle: their_handle_inheritable as i32,
143        };
144        opts.security_attributes(&mut sa);
145        let theirs = File::open(Path::new(&name), &opts)?;
146
147        Ok(Pipes {
148            ours: AnonPipe { inner: ours },
149            theirs: AnonPipe { inner: theirs.into_inner() },
150        })
151    }
152}
153
154/// Takes an asynchronous source pipe and returns a synchronous pipe suitable
155/// for sending to a child process.
156///
157/// This is achieved by creating a new set of pipes and spawning a thread that
158/// relays messages between the source and the synchronous pipe.
159pub fn spawn_pipe_relay(
160    source: &AnonPipe,
161    ours_readable: bool,
162    their_handle_inheritable: bool,
163) -> io::Result<AnonPipe> {
164    // We need this handle to live for the lifetime of the thread spawned below.
165    let source = source.try_clone()?;
166
167    // create a new pair of anon pipes.
168    let Pipes { theirs, ours } = anon_pipe(ours_readable, their_handle_inheritable)?;
169
170    // Spawn a thread that passes messages from one pipe to the other.
171    // Any errors will simply cause the thread to exit.
172    let (reader, writer) = if ours_readable { (ours, source) } else { (source, ours) };
173    crate::thread::spawn(move || {
174        let mut buf = [0_u8; 4096];
175        'reader: while let Ok(len) = reader.read(&mut buf) {
176            if len == 0 {
177                break;
178            }
179            let mut start = 0;
180            while let Ok(written) = writer.write(&buf[start..len]) {
181                start += written;
182                if start == len {
183                    continue 'reader;
184                }
185            }
186            break;
187        }
188    });
189
190    // Return the pipe that should be sent to the child process.
191    Ok(theirs)
192}
193
194fn random_number() -> usize {
195    static N: Atomic<usize> = AtomicUsize::new(0);
196    loop {
197        if N.load(Relaxed) != 0 {
198            return N.fetch_add(1, Relaxed);
199        }
200
201        N.store(usize::random(&mut DefaultRandomSource), Relaxed);
202    }
203}
204
205impl AnonPipe {
206    pub fn handle(&self) -> &Handle {
207        &self.inner
208    }
209    pub fn into_handle(self) -> Handle {
210        self.inner
211    }
212
213    pub fn try_clone(&self) -> io::Result<Self> {
214        self.inner.duplicate(0, false, c::DUPLICATE_SAME_ACCESS).map(|inner| AnonPipe { inner })
215    }
216
217    pub fn read(&self, buf: &mut [u8]) -> io::Result<usize> {
218        let result = unsafe {
219            let len = crate::cmp::min(buf.len(), u32::MAX as usize) as u32;
220            let ptr = buf.as_mut_ptr();
221            self.alertable_io_internal(|overlapped, callback| {
222                c::ReadFileEx(self.inner.as_raw_handle(), ptr, len, overlapped, callback)
223            })
224        };
225
226        match result {
227            // The special treatment of BrokenPipe is to deal with Windows
228            // pipe semantics, which yields this error when *reading* from
229            // a pipe after the other end has closed; we interpret that as
230            // EOF on the pipe.
231            Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(0),
232            _ => result,
233        }
234    }
235
236    pub fn read_buf(&self, mut buf: BorrowedCursor<'_>) -> io::Result<()> {
237        let result = unsafe {
238            let len = crate::cmp::min(buf.capacity(), u32::MAX as usize) as u32;
239            let ptr = buf.as_mut().as_mut_ptr().cast::<u8>();
240            self.alertable_io_internal(|overlapped, callback| {
241                c::ReadFileEx(self.inner.as_raw_handle(), ptr, len, overlapped, callback)
242            })
243        };
244
245        match result {
246            // The special treatment of BrokenPipe is to deal with Windows
247            // pipe semantics, which yields this error when *reading* from
248            // a pipe after the other end has closed; we interpret that as
249            // EOF on the pipe.
250            Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(()),
251            Err(e) => Err(e),
252            Ok(n) => {
253                unsafe {
254                    buf.advance_unchecked(n);
255                }
256                Ok(())
257            }
258        }
259    }
260
261    pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
262        self.inner.read_vectored(bufs)
263    }
264
265    #[inline]
266    pub fn is_read_vectored(&self) -> bool {
267        self.inner.is_read_vectored()
268    }
269
270    pub fn read_to_end(&self, buf: &mut Vec<u8>) -> io::Result<usize> {
271        self.handle().read_to_end(buf)
272    }
273
274    pub fn write(&self, buf: &[u8]) -> io::Result<usize> {
275        unsafe {
276            let len = crate::cmp::min(buf.len(), u32::MAX as usize) as u32;
277            self.alertable_io_internal(|overlapped, callback| {
278                c::WriteFileEx(self.inner.as_raw_handle(), buf.as_ptr(), len, overlapped, callback)
279            })
280        }
281    }
282
283    pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
284        self.inner.write_vectored(bufs)
285    }
286
287    #[inline]
288    pub fn is_write_vectored(&self) -> bool {
289        self.inner.is_write_vectored()
290    }
291
292    /// Synchronizes asynchronous reads or writes using our anonymous pipe.
293    ///
294    /// This is a wrapper around [`ReadFileEx`] or [`WriteFileEx`] that uses
295    /// [Asynchronous Procedure Call] (APC) to synchronize reads or writes.
296    ///
297    /// Note: This should not be used for handles we don't create.
298    ///
299    /// # Safety
300    ///
301    /// `buf` must be a pointer to a buffer that's valid for reads or writes
302    /// up to `len` bytes. The `AlertableIoFn` must be either `ReadFileEx` or `WriteFileEx`
303    ///
304    /// [`ReadFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfileex
305    /// [`WriteFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefileex
306    /// [Asynchronous Procedure Call]: https://docs.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls
307    unsafe fn alertable_io_internal(
308        &self,
309        io: impl FnOnce(&mut c::OVERLAPPED, c::LPOVERLAPPED_COMPLETION_ROUTINE) -> c::BOOL,
310    ) -> io::Result<usize> {
311        // Use "alertable I/O" to synchronize the pipe I/O.
312        // This has four steps.
313        //
314        // STEP 1: Start the asynchronous I/O operation.
315        //         This simply calls either `ReadFileEx` or `WriteFileEx`,
316        //         giving it a pointer to the buffer and callback function.
317        //
318        // STEP 2: Enter an alertable state.
319        //         The callback set in step 1 will not be called until the thread
320        //         enters an "alertable" state. This can be done using `SleepEx`.
321        //
322        // STEP 3: The callback
323        //         Once the I/O is complete and the thread is in an alertable state,
324        //         the callback will be run on the same thread as the call to
325        //         `ReadFileEx` or `WriteFileEx` done in step 1.
326        //         In the callback we simply set the result of the async operation.
327        //
328        // STEP 4: Return the result.
329        //         At this point we'll have a result from the callback function
330        //         and can simply return it. Note that we must not return earlier,
331        //         while the I/O is still in progress.
332
333        // The result that will be set from the asynchronous callback.
334        let mut async_result: Option<AsyncResult> = None;
335        struct AsyncResult {
336            error: u32,
337            transferred: u32,
338        }
339
340        // STEP 3: The callback.
341        unsafe extern "system" fn callback(
342            dwErrorCode: u32,
343            dwNumberOfBytesTransferred: u32,
344            lpOverlapped: *mut c::OVERLAPPED,
345        ) {
346            // Set `async_result` using a pointer smuggled through `hEvent`.
347            // SAFETY:
348            // At this point, the OVERLAPPED struct will have been written to by the OS,
349            // except for our `hEvent` field which we set to a valid AsyncResult pointer (see below)
350            unsafe {
351                let result =
352                    AsyncResult { error: dwErrorCode, transferred: dwNumberOfBytesTransferred };
353                *(*lpOverlapped).hEvent.cast::<Option<AsyncResult>>() = Some(result);
354            }
355        }
356
357        // STEP 1: Start the I/O operation.
358        let mut overlapped: c::OVERLAPPED = unsafe { crate::mem::zeroed() };
359        // `hEvent` is unused by `ReadFileEx` and `WriteFileEx`.
360        // Therefore the documentation suggests using it to smuggle a pointer to the callback.
361        overlapped.hEvent = (&raw mut async_result) as *mut _;
362
363        // Asynchronous read of the pipe.
364        // If successful, `callback` will be called once it completes.
365        let result = io(&mut overlapped, Some(callback));
366        if result == c::FALSE {
367            // We can return here because the call failed.
368            // After this we must not return until the I/O completes.
369            return Err(io::Error::last_os_error());
370        }
371
372        // Wait indefinitely for the result.
373        let result = loop {
374            // STEP 2: Enter an alertable state.
375            // The second parameter of `SleepEx` is used to make this sleep alertable.
376            unsafe { c::SleepEx(c::INFINITE, c::TRUE) };
377            if let Some(result) = async_result {
378                break result;
379            }
380        };
381        // STEP 4: Return the result.
382        // `async_result` is always `Some` at this point
383        match result.error {
384            c::ERROR_SUCCESS => Ok(result.transferred as usize),
385            error => Err(io::Error::from_raw_os_error(error as _)),
386        }
387    }
388}
389
390pub fn read2(p1: AnonPipe, v1: &mut Vec<u8>, p2: AnonPipe, v2: &mut Vec<u8>) -> io::Result<()> {
391    let p1 = p1.into_handle();
392    let p2 = p2.into_handle();
393
394    let mut p1 = AsyncPipe::new(p1, v1)?;
395    let mut p2 = AsyncPipe::new(p2, v2)?;
396    let objs = [p1.event.as_raw_handle(), p2.event.as_raw_handle()];
397
398    // In a loop we wait for either pipe's scheduled read operation to complete.
399    // If the operation completes with 0 bytes, that means EOF was reached, in
400    // which case we just finish out the other pipe entirely.
401    //
402    // Note that overlapped I/O is in general super unsafe because we have to
403    // be careful to ensure that all pointers in play are valid for the entire
404    // duration of the I/O operation (where tons of operations can also fail).
405    // The destructor for `AsyncPipe` ends up taking care of most of this.
406    loop {
407        let res = unsafe { c::WaitForMultipleObjects(2, objs.as_ptr(), c::FALSE, c::INFINITE) };
408        if res == c::WAIT_OBJECT_0 {
409            if !p1.result()? || !p1.schedule_read()? {
410                return p2.finish();
411            }
412        } else if res == c::WAIT_OBJECT_0 + 1 {
413            if !p2.result()? || !p2.schedule_read()? {
414                return p1.finish();
415            }
416        } else {
417            return Err(io::Error::last_os_error());
418        }
419    }
420}
421
422struct AsyncPipe<'a> {
423    pipe: Handle,
424    event: Handle,
425    overlapped: Box<c::OVERLAPPED>, // needs a stable address
426    dst: &'a mut Vec<u8>,
427    state: State,
428}
429
430#[derive(PartialEq, Debug)]
431enum State {
432    NotReading,
433    Reading,
434    Read(usize),
435}
436
437impl<'a> AsyncPipe<'a> {
438    fn new(pipe: Handle, dst: &'a mut Vec<u8>) -> io::Result<AsyncPipe<'a>> {
439        // Create an event which we'll use to coordinate our overlapped
440        // operations, this event will be used in WaitForMultipleObjects
441        // and passed as part of the OVERLAPPED handle.
442        //
443        // Note that we do a somewhat clever thing here by flagging the
444        // event as being manually reset and setting it initially to the
445        // signaled state. This means that we'll naturally fall through the
446        // WaitForMultipleObjects call above for pipes created initially,
447        // and the only time an even will go back to "unset" will be once an
448        // I/O operation is successfully scheduled (what we want).
449        let event = Handle::new_event(true, true)?;
450        let mut overlapped: Box<c::OVERLAPPED> = unsafe { Box::new(mem::zeroed()) };
451        overlapped.hEvent = event.as_raw_handle();
452        Ok(AsyncPipe { pipe, overlapped, event, dst, state: State::NotReading })
453    }
454
455    /// Executes an overlapped read operation.
456    ///
457    /// Must not currently be reading, and returns whether the pipe is currently
458    /// at EOF or not. If the pipe is not at EOF then `result()` must be called
459    /// to complete the read later on (may block), but if the pipe is at EOF
460    /// then `result()` should not be called as it will just block forever.
461    fn schedule_read(&mut self) -> io::Result<bool> {
462        assert_eq!(self.state, State::NotReading);
463        let amt = unsafe {
464            if self.dst.capacity() == self.dst.len() {
465                let additional = if self.dst.capacity() == 0 { 16 } else { 1 };
466                self.dst.reserve(additional);
467            }
468            self.pipe.read_overlapped(self.dst.spare_capacity_mut(), &mut *self.overlapped)?
469        };
470
471        // If this read finished immediately then our overlapped event will
472        // remain signaled (it was signaled coming in here) and we'll progress
473        // down to the method below.
474        //
475        // Otherwise the I/O operation is scheduled and the system set our event
476        // to not signaled, so we flag ourselves into the reading state and move
477        // on.
478        self.state = match amt {
479            Some(0) => return Ok(false),
480            Some(amt) => State::Read(amt),
481            None => State::Reading,
482        };
483        Ok(true)
484    }
485
486    /// Wait for the result of the overlapped operation previously executed.
487    ///
488    /// Takes a parameter `wait` which indicates if this pipe is currently being
489    /// read whether the function should block waiting for the read to complete.
490    ///
491    /// Returns values:
492    ///
493    /// * `true` - finished any pending read and the pipe is not at EOF (keep
494    ///            going)
495    /// * `false` - finished any pending read and pipe is at EOF (stop issuing
496    ///             reads)
497    fn result(&mut self) -> io::Result<bool> {
498        let amt = match self.state {
499            State::NotReading => return Ok(true),
500            State::Reading => self.pipe.overlapped_result(&mut *self.overlapped, true)?,
501            State::Read(amt) => amt,
502        };
503        self.state = State::NotReading;
504        unsafe {
505            let len = self.dst.len();
506            self.dst.set_len(len + amt);
507        }
508        Ok(amt != 0)
509    }
510
511    /// Finishes out reading this pipe entirely.
512    ///
513    /// Waits for any pending and schedule read, and then calls `read_to_end`
514    /// if necessary to read all the remaining information.
515    fn finish(&mut self) -> io::Result<()> {
516        while self.result()? && self.schedule_read()? {
517            // ...
518        }
519        Ok(())
520    }
521}
522
523impl<'a> Drop for AsyncPipe<'a> {
524    fn drop(&mut self) {
525        match self.state {
526            State::Reading => {}
527            _ => return,
528        }
529
530        // If we have a pending read operation, then we have to make sure that
531        // it's *done* before we actually drop this type. The kernel requires
532        // that the `OVERLAPPED` and buffer pointers are valid for the entire
533        // I/O operation.
534        //
535        // To do that, we call `CancelIo` to cancel any pending operation, and
536        // if that succeeds we wait for the overlapped result.
537        //
538        // If anything here fails, there's not really much we can do, so we leak
539        // the buffer/OVERLAPPED pointers to ensure we're at least memory safe.
540        if self.pipe.cancel_io().is_err() || self.result().is_err() {
541            let buf = mem::take(self.dst);
542            let overlapped = Box::new(unsafe { mem::zeroed() });
543            let overlapped = mem::replace(&mut self.overlapped, overlapped);
544            mem::forget((buf, overlapped));
545        }
546    }
547}