1
- //! Module for anonymous pipe
1
+ //! A cross-platform anonymous pipe.
2
2
//!
3
- //! ```
4
- //! #![feature(anonymous_pipe)]
3
+ //! This module provides support for anonymous OS pipes, like [pipe] on Linux or [CreatePipe] on
4
+ //! Windows, which can be used as synchronous communication channels between related processes.
5
+ //!
6
+ //! # Behavior
7
+ //!
8
+ //! A pipe can be thought of as a bounded, interprocess [`mpsc`](crate::sync::mpsc), provided by
9
+ //! the OS, with a platform-dependent capacity. In particular:
10
+ //!
11
+ //! * A read on a [`PipeReader`] blocks until the pipe is non-empty.
12
+ //! * A write on a [`PipeWriter`] blocks when the pipe is full.
13
+ //! * When all copies of a [`PipeWriter`] are closed, a read on the corresponding [`PipeReader`]
14
+ //! returns EOF.
15
+ //! * [`PipeReader`] can be shared through copying the underlying file descriptor, but only one
16
+ //! process will consume the data in the pipe at any given time.
17
+ //!
18
+ //! # Capacity
19
+ //!
20
+ //! Pipe capacity is platform-dependent. To quote the Linux [man page]:
21
+ //!
22
+ //! > Different implementations have different limits for the pipe capacity. Applications should
23
+ //! > not rely on a particular capacity: an application should be designed so that a reading process
24
+ //! > consumes data as soon as it is available, so that a writing process does not remain blocked.
5
25
//!
26
+ //! # Examples
27
+ //!
28
+ //! ```no_run
29
+ //! #![feature(anonymous_pipe)]
6
30
//! # #[cfg(miri)] fn main() {}
7
31
//! # #[cfg(not(miri))]
32
+ //! # use std::process::Command;
33
+ //! # use std::io::{Read, Write};
8
34
//! # fn main() -> std::io::Result<()> {
9
- //! let (reader, writer) = std::pipe::pipe()?;
35
+ //! let (ping_rx, mut ping_tx) = std::pipe::pipe()?;
36
+ //! let (mut pong_rx, pong_tx) = std::pipe::pipe()?;
37
+ //!
38
+ //! let mut echo_server = Command::new("cat").stdin(ping_rx).stdout(pong_tx).spawn()?;
39
+ //!
40
+ //! ping_tx.write_all(b"hello")?;
41
+ //! // Close to unblock server's reader.
42
+ //! drop(ping_tx);
43
+ //!
44
+ //! let mut buf = String::new();
45
+ //! // Block until server's writer is closed.
46
+ //! pong_rx.read_to_string(&mut buf)?;
47
+ //! assert_eq!(&buf, "hello");
48
+ //!
49
+ //! echo_server.wait()?;
10
50
//! # Ok(())
11
51
//! # }
12
52
//! ```
13
-
53
+ //! [pipe]: https://man7.org/linux/man-pages/man2/pipe.2.html
54
+ //! [CreatePipe]: https://learn.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe
55
+ //! [man page]: https://man7.org/linux/man-pages/man7/pipe.7.html
14
56
use crate :: io;
15
57
use crate :: sys:: anonymous_pipe:: { AnonPipe , pipe as pipe_inner} ;
16
58
17
59
/// Create anonymous pipe that is close-on-exec and blocking.
60
+ ///
61
+ /// # Examples
62
+ ///
63
+ /// See the [module-level](crate::pipe) documentation for examples.
18
64
#[ unstable( feature = "anonymous_pipe" , issue = "127154" ) ]
19
65
#[ inline]
20
66
pub fn pipe ( ) -> io:: Result < ( PipeReader , PipeWriter ) > {
@@ -33,6 +79,53 @@ pub struct PipeWriter(pub(crate) AnonPipe);
33
79
34
80
impl PipeReader {
35
81
/// Create a new [`PipeReader`] instance that shares the same underlying file description.
82
+ ///
83
+ /// # Examples
84
+ ///
85
+ /// ```no_run
86
+ /// #![feature(anonymous_pipe)]
87
+ /// # #[cfg(miri)] fn main() {}
88
+ /// # #[cfg(not(miri))]
89
+ /// # use std::fs;
90
+ /// # use std::io::Write;
91
+ /// # use std::process::Command;
92
+ /// # fn main() -> std::io::Result<()> {
93
+ /// const NUM_SLOT: u8 = 2;
94
+ /// const NUM_PROC: u8 = 5;
95
+ /// const OUTPUT: &str = "output.txt";
96
+ ///
97
+ /// let mut jobs = vec![];
98
+ /// let (reader, mut writer) = std::pipe::pipe()?;
99
+ ///
100
+ /// writer.write_all(&[b'|'; NUM_SLOT as usize])?;
101
+ ///
102
+ /// for _ in 0..NUM_PROC {
103
+ /// jobs.push(
104
+ /// Command::new("bash")
105
+ /// .args(["-c",
106
+ /// &format!(
107
+ /// "read -n 1\n\
108
+ /// echo -n 'x' >> '{}'\n\
109
+ /// echo -n '|'",
110
+ /// OUTPUT
111
+ /// ),
112
+ /// ])
113
+ /// .stdin(reader.try_clone()?)
114
+ /// .stdout(writer.try_clone()?)
115
+ /// .spawn()?,
116
+ /// );
117
+ /// }
118
+ ///
119
+ /// for mut job in jobs {
120
+ /// job.wait()?;
121
+ /// }
122
+ ///
123
+ /// let xs = fs::read_to_string(OUTPUT)?;
124
+ /// fs::remove_file(OUTPUT)?;
125
+ /// assert_eq!(xs, "x".repeat(NUM_PROC.into()));
126
+ /// # Ok(())
127
+ /// # }
128
+ /// ```
36
129
#[ unstable( feature = "anonymous_pipe" , issue = "127154" ) ]
37
130
pub fn try_clone ( & self ) -> io:: Result < Self > {
38
131
self . 0 . try_clone ( ) . map ( Self )
@@ -41,6 +134,36 @@ impl PipeReader {
41
134
42
135
impl PipeWriter {
43
136
/// Create a new [`PipeWriter`] instance that shares the same underlying file description.
137
+ ///
138
+ /// # Examples
139
+ ///
140
+ /// ```no_run
141
+ /// #![feature(anonymous_pipe)]
142
+ /// # #[cfg(miri)] fn main() {}
143
+ /// # #[cfg(not(miri))]
144
+ /// # use std::process::Command;
145
+ /// # use std::io::Read;
146
+ /// # fn main() -> std::io::Result<()> {
147
+ /// let (mut reader, writer) = std::pipe::pipe()?;
148
+ ///
149
+ /// let mut peer = Command::new("bash")
150
+ /// .args([
151
+ /// "-c",
152
+ /// "echo -n foo\n\
153
+ /// echo -n bar >&2"
154
+ /// ])
155
+ /// .stdout(writer.try_clone()?)
156
+ /// .stderr(writer)
157
+ /// .spawn()?;
158
+ ///
159
+ /// let mut msg = String::new();
160
+ /// reader.read_to_string(&mut msg)?;
161
+ /// assert_eq!(&msg, "foobar");
162
+ ///
163
+ /// peer.wait()?;
164
+ /// # Ok(())
165
+ /// # }
166
+ /// ```
44
167
#[ unstable( feature = "anonymous_pipe" , issue = "127154" ) ]
45
168
pub fn try_clone ( & self ) -> io:: Result < Self > {
46
169
self . 0 . try_clone ( ) . map ( Self )
0 commit comments