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::AtomicUsize;
7use crate::sync::atomic::Ordering::Relaxed;
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 let theirs = AnonPipe { inner: theirs.into_inner() };
147
148 Ok(Pipes {
149 ours: AnonPipe { inner: ours },
150 theirs: AnonPipe { inner: theirs.into_inner() },
151 })
152 }
153}
154
155/// Takes an asynchronous source pipe and returns a synchronous pipe suitable
156/// for sending to a child process.
157///
158/// This is achieved by creating a new set of pipes and spawning a thread that
159/// relays messages between the source and the synchronous pipe.
160pub fn spawn_pipe_relay(
161 source: &AnonPipe,
162 ours_readable: bool,
163 their_handle_inheritable: bool,
164) -> io::Result<AnonPipe> {
165 // We need this handle to live for the lifetime of the thread spawned below.
166 let source = source.try_clone()?;
167
168 // create a new pair of anon pipes.
169 let Pipes { theirs, ours } = anon_pipe(ours_readable, their_handle_inheritable)?;
170
171 // Spawn a thread that passes messages from one pipe to the other.
172 // Any errors will simply cause the thread to exit.
173 let (reader, writer) = if ours_readable { (ours, source) } else { (source, ours) };
174 crate::thread::spawn(move || {
175 let mut buf = [0_u8; 4096];
176 'reader: while let Ok(len) = reader.read(&mut buf) {
177 if len == 0 {
178 break;
179 }
180 let mut start = 0;
181 while let Ok(written) = writer.write(&buf[start..len]) {
182 start += written;
183 if start == len {
184 continue 'reader;
185 }
186 }
187 break;
188 }
189 });
190
191 // Return the pipe that should be sent to the child process.
192 Ok(theirs)
193}
194
195fn random_number() -> usize {
196 static N: AtomicUsize = AtomicUsize::new(0);
197 loop {
198 if N.load(Relaxed) != 0 {
199 return N.fetch_add(1, Relaxed);
200 }
201
202 N.store(usize::random(&mut DefaultRandomSource), Relaxed);
203 }
204}
205
206impl AnonPipe {
207 pub fn handle(&self) -> &Handle {
208 &self.inner
209 }
210 pub fn into_handle(self) -> Handle {
211 self.inner
212 }
213
214 pub fn try_clone(&self) -> io::Result<Self> {
215 self.inner.duplicate(0, false, c::DUPLICATE_SAME_ACCESS).map(|inner| AnonPipe { inner })
216 }
217
218 pub fn read(&self, buf: &mut [u8]) -> io::Result<usize> {
219 let result = unsafe {
220 let len = crate::cmp::min(buf.len(), u32::MAX as usize) as u32;
221 let ptr = buf.as_mut_ptr();
222 self.alertable_io_internal(|overlapped, callback| {
223 c::ReadFileEx(self.inner.as_raw_handle(), ptr, len, overlapped, callback)
224 })
225 };
226
227 match result {
228 // The special treatment of BrokenPipe is to deal with Windows
229 // pipe semantics, which yields this error when *reading* from
230 // a pipe after the other end has closed; we interpret that as
231 // EOF on the pipe.
232 Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(0),
233 _ => result,
234 }
235 }
236
237 pub fn read_buf(&self, mut buf: BorrowedCursor<'_>) -> io::Result<()> {
238 let result = unsafe {
239 let len = crate::cmp::min(buf.capacity(), u32::MAX as usize) as u32;
240 let ptr = buf.as_mut().as_mut_ptr().cast::<u8>();
241 self.alertable_io_internal(|overlapped, callback| {
242 c::ReadFileEx(self.inner.as_raw_handle(), ptr, len, overlapped, callback)
243 })
244 };
245
246 match result {
247 // The special treatment of BrokenPipe is to deal with Windows
248 // pipe semantics, which yields this error when *reading* from
249 // a pipe after the other end has closed; we interpret that as
250 // EOF on the pipe.
251 Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(()),
252 Err(e) => Err(e),
253 Ok(n) => {
254 unsafe {
255 buf.advance_unchecked(n);
256 }
257 Ok(())
258 }
259 }
260 }
261
262 pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
263 self.inner.read_vectored(bufs)
264 }
265
266 #[inline]
267 pub fn is_read_vectored(&self) -> bool {
268 self.inner.is_read_vectored()
269 }
270
271 pub fn read_to_end(&self, buf: &mut Vec<u8>) -> io::Result<usize> {
272 self.handle().read_to_end(buf)
273 }
274
275 pub fn write(&self, buf: &[u8]) -> io::Result<usize> {
276 unsafe {
277 let len = crate::cmp::min(buf.len(), u32::MAX as usize) as u32;
278 self.alertable_io_internal(|overlapped, callback| {
279 c::WriteFileEx(self.inner.as_raw_handle(), buf.as_ptr(), len, overlapped, callback)
280 })
281 }
282 }
283
284 pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
285 self.inner.write_vectored(bufs)
286 }
287
288 #[inline]
289 pub fn is_write_vectored(&self) -> bool {
290 self.inner.is_write_vectored()
291 }
292
293 /// Synchronizes asynchronous reads or writes using our anonymous pipe.
294 ///
295 /// This is a wrapper around [`ReadFileEx`] or [`WriteFileEx`] that uses
296 /// [Asynchronous Procedure Call] (APC) to synchronize reads or writes.
297 ///
298 /// Note: This should not be used for handles we don't create.
299 ///
300 /// # Safety
301 ///
302 /// `buf` must be a pointer to a buffer that's valid for reads or writes
303 /// up to `len` bytes. The `AlertableIoFn` must be either `ReadFileEx` or `WriteFileEx`
304 ///
305 /// [`ReadFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfileex
306 /// [`WriteFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefileex
307 /// [Asynchronous Procedure Call]: https://docs.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls
308 unsafe fn alertable_io_internal(
309 &self,
310 io: impl FnOnce(&mut c::OVERLAPPED, c::LPOVERLAPPED_COMPLETION_ROUTINE) -> c::BOOL,
311 ) -> io::Result<usize> {
312 // Use "alertable I/O" to synchronize the pipe I/O.
313 // This has four steps.
314 //
315 // STEP 1: Start the asynchronous I/O operation.
316 // This simply calls either `ReadFileEx` or `WriteFileEx`,
317 // giving it a pointer to the buffer and callback function.
318 //
319 // STEP 2: Enter an alertable state.
320 // The callback set in step 1 will not be called until the thread
321 // enters an "alertable" state. This can be done using `SleepEx`.
322 //
323 // STEP 3: The callback
324 // Once the I/O is complete and the thread is in an alertable state,
325 // the callback will be run on the same thread as the call to
326 // `ReadFileEx` or `WriteFileEx` done in step 1.
327 // In the callback we simply set the result of the async operation.
328 //
329 // STEP 4: Return the result.
330 // At this point we'll have a result from the callback function
331 // and can simply return it. Note that we must not return earlier,
332 // while the I/O is still in progress.
333
334 // The result that will be set from the asynchronous callback.
335 let mut async_result: Option<AsyncResult> = None;
336 struct AsyncResult {
337 error: u32,
338 transferred: u32,
339 }
340
341 // STEP 3: The callback.
342 unsafe extern "system" fn callback(
343 dwErrorCode: u32,
344 dwNumberOfBytesTransferred: u32,
345 lpOverlapped: *mut c::OVERLAPPED,
346 ) {
347 // Set `async_result` using a pointer smuggled through `hEvent`.
348 // SAFETY:
349 // At this point, the OVERLAPPED struct will have been written to by the OS,
350 // except for our `hEvent` field which we set to a valid AsyncResult pointer (see below)
351 unsafe {
352 let result =
353 AsyncResult { error: dwErrorCode, transferred: dwNumberOfBytesTransferred };
354 *(*lpOverlapped).hEvent.cast::<Option<AsyncResult>>() = Some(result);
355 }
356 }
357
358 // STEP 1: Start the I/O operation.
359 let mut overlapped: c::OVERLAPPED = unsafe { crate::mem::zeroed() };
360 // `hEvent` is unused by `ReadFileEx` and `WriteFileEx`.
361 // Therefore the documentation suggests using it to smuggle a pointer to the callback.
362 overlapped.hEvent = (&raw mut async_result) as *mut _;
363
364 // Asynchronous read of the pipe.
365 // If successful, `callback` will be called once it completes.
366 let result = io(&mut overlapped, Some(callback));
367 if result == c::FALSE {
368 // We can return here because the call failed.
369 // After this we must not return until the I/O completes.
370 return Err(io::Error::last_os_error());
371 }
372
373 // Wait indefinitely for the result.
374 let result = loop {
375 // STEP 2: Enter an alertable state.
376 // The second parameter of `SleepEx` is used to make this sleep alertable.
377 unsafe { c::SleepEx(c::INFINITE, c::TRUE) };
378 if let Some(result) = async_result {
379 break result;
380 }
381 };
382 // STEP 4: Return the result.
383 // `async_result` is always `Some` at this point
384 match result.error {
385 c::ERROR_SUCCESS => Ok(result.transferred as usize),
386 error => Err(io::Error::from_raw_os_error(error as _)),
387 }
388 }
389}
390
391pub fn read2(p1: AnonPipe, v1: &mut Vec<u8>, p2: AnonPipe, v2: &mut Vec<u8>) -> io::Result<()> {
392 let p1 = p1.into_handle();
393 let p2 = p2.into_handle();
394
395 let mut p1 = AsyncPipe::new(p1, v1)?;
396 let mut p2 = AsyncPipe::new(p2, v2)?;
397 let objs = [p1.event.as_raw_handle(), p2.event.as_raw_handle()];
398
399 // In a loop we wait for either pipe's scheduled read operation to complete.
400 // If the operation completes with 0 bytes, that means EOF was reached, in
401 // which case we just finish out the other pipe entirely.
402 //
403 // Note that overlapped I/O is in general super unsafe because we have to
404 // be careful to ensure that all pointers in play are valid for the entire
405 // duration of the I/O operation (where tons of operations can also fail).
406 // The destructor for `AsyncPipe` ends up taking care of most of this.
407 loop {
408 let res = unsafe { c::WaitForMultipleObjects(2, objs.as_ptr(), c::FALSE, c::INFINITE) };
409 if res == c::WAIT_OBJECT_0 {
410 if !p1.result()? || !p1.schedule_read()? {
411 return p2.finish();
412 }
413 } else if res == c::WAIT_OBJECT_0 + 1 {
414 if !p2.result()? || !p2.schedule_read()? {
415 return p1.finish();
416 }
417 } else {
418 return Err(io::Error::last_os_error());
419 }
420 }
421}
422
423struct AsyncPipe<'a> {
424 pipe: Handle,
425 event: Handle,
426 overlapped: Box<c::OVERLAPPED>, // needs a stable address
427 dst: &'a mut Vec<u8>,
428 state: State,
429}
430
431#[derive(PartialEq, Debug)]
432enum State {
433 NotReading,
434 Reading,
435 Read(usize),
436}
437
438impl<'a> AsyncPipe<'a> {
439 fn new(pipe: Handle, dst: &'a mut Vec<u8>) -> io::Result<AsyncPipe<'a>> {
440 // Create an event which we'll use to coordinate our overlapped
441 // operations, this event will be used in WaitForMultipleObjects
442 // and passed as part of the OVERLAPPED handle.
443 //
444 // Note that we do a somewhat clever thing here by flagging the
445 // event as being manually reset and setting it initially to the
446 // signaled state. This means that we'll naturally fall through the
447 // WaitForMultipleObjects call above for pipes created initially,
448 // and the only time an even will go back to "unset" will be once an
449 // I/O operation is successfully scheduled (what we want).
450 let event = Handle::new_event(true, true)?;
451 let mut overlapped: Box<c::OVERLAPPED> = unsafe { Box::new(mem::zeroed()) };
452 overlapped.hEvent = event.as_raw_handle();
453 Ok(AsyncPipe { pipe, overlapped, event, dst, state: State::NotReading })
454 }
455
456 /// Executes an overlapped read operation.
457 ///
458 /// Must not currently be reading, and returns whether the pipe is currently
459 /// at EOF or not. If the pipe is not at EOF then `result()` must be called
460 /// to complete the read later on (may block), but if the pipe is at EOF
461 /// then `result()` should not be called as it will just block forever.
462 fn schedule_read(&mut self) -> io::Result<bool> {
463 assert_eq!(self.state, State::NotReading);
464 let amt = unsafe {
465 if self.dst.capacity() == self.dst.len() {
466 let additional = if self.dst.capacity() == 0 { 16 } else { 1 };
467 self.dst.reserve(additional);
468 }
469 self.pipe.read_overlapped(self.dst.spare_capacity_mut(), &mut *self.overlapped)?
470 };
471
472 // If this read finished immediately then our overlapped event will
473 // remain signaled (it was signaled coming in here) and we'll progress
474 // down to the method below.
475 //
476 // Otherwise the I/O operation is scheduled and the system set our event
477 // to not signaled, so we flag ourselves into the reading state and move
478 // on.
479 self.state = match amt {
480 Some(0) => return Ok(false),
481 Some(amt) => State::Read(amt),
482 None => State::Reading,
483 };
484 Ok(true)
485 }
486
487 /// Wait for the result of the overlapped operation previously executed.
488 ///
489 /// Takes a parameter `wait` which indicates if this pipe is currently being
490 /// read whether the function should block waiting for the read to complete.
491 ///
492 /// Returns values:
493 ///
494 /// * `true` - finished any pending read and the pipe is not at EOF (keep
495 /// going)
496 /// * `false` - finished any pending read and pipe is at EOF (stop issuing
497 /// reads)
498 fn result(&mut self) -> io::Result<bool> {
499 let amt = match self.state {
500 State::NotReading => return Ok(true),
501 State::Reading => self.pipe.overlapped_result(&mut *self.overlapped, true)?,
502 State::Read(amt) => amt,
503 };
504 self.state = State::NotReading;
505 unsafe {
506 let len = self.dst.len();
507 self.dst.set_len(len + amt);
508 }
509 Ok(amt != 0)
510 }
511
512 /// Finishes out reading this pipe entirely.
513 ///
514 /// Waits for any pending and schedule read, and then calls `read_to_end`
515 /// if necessary to read all the remaining information.
516 fn finish(&mut self) -> io::Result<()> {
517 while self.result()? && self.schedule_read()? {
518 // ...
519 }
520 Ok(())
521 }
522}
523
524impl<'a> Drop for AsyncPipe<'a> {
525 fn drop(&mut self) {
526 match self.state {
527 State::Reading => {}
528 _ => return,
529 }
530
531 // If we have a pending read operation, then we have to make sure that
532 // it's *done* before we actually drop this type. The kernel requires
533 // that the `OVERLAPPED` and buffer pointers are valid for the entire
534 // I/O operation.
535 //
536 // To do that, we call `CancelIo` to cancel any pending operation, and
537 // if that succeeds we wait for the overlapped result.
538 //
539 // If anything here fails, there's not really much we can do, so we leak
540 // the buffer/OVERLAPPED pointers to ensure we're at least memory safe.
541 if self.pipe.cancel_io().is_err() || self.result().is_err() {
542 let buf = mem::take(self.dst);
543 let overlapped = Box::new(unsafe { mem::zeroed() });
544 let overlapped = mem::replace(&mut self.overlapped, overlapped);
545 mem::forget((buf, overlapped));
546 }
547 }
548}