interprocess/
unnamed_pipe.rs

1//! Creation and usage of unnamed pipes.
2//!
3//! Unlike named pipes, unnamed pipes are only accessible through their handles – once an endpoint
4//! is closed, its corresponding end of the pipe is no longer accessible. Unnamed pipes typically
5//! work best when communicating with child processes.
6//!
7//! The handles and file descriptors are inheritable by default. The `AsRawHandle` and `AsRawFd`
8//! traits can be used to get a numeric handle value which can then be communicated to a child
9//! process using a command-line argument, environment variable or some other program startup IPC
10//! method. The numeric value can then be reconstructed into an I/O object using
11//! `FromRawHandle`/`FromRawFd`. Interprocess does not concern itself with how this is done.
12//!
13//! Note
14//! [the standard library's support for piping `stdin`, `stdout` and `stderr`](std::process::Stdio),
15//! which can be used in simple cases instead of unnamed pipes. Making use of that feature is
16//! advisable if the program of the child process can be modified to communicate with its parent
17//! via standard I/O streams.
18//!
19//! # Examples
20//! See [`pipe()`].
21
22#[cfg(feature = "tokio")]
23#[cfg_attr(feature = "doc_cfg", doc(cfg(feature = "tokio")))]
24pub mod tokio;
25
26impmod! {unnamed_pipe,
27    Recver as RecverImpl,
28    Sender as SenderImpl,
29    pipe_impl,
30}
31use {crate::Sealed, std::io};
32
33/// Creates a new pipe with the default creation settings and returns the handles to its sending end
34/// and receiving end.
35///
36/// The platform-specific builders in the `os` module of the crate might be more helpful if extra
37/// configuration for the pipe is needed.
38///
39/// # Examples
40/// ## Basic communication
41/// In a parent process:
42/// ```no_run
43#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_a.rs")]
44/// ```
45/// In a child process:
46/// ```no_run
47#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_b.rs")]
48/// ```
49#[inline]
50pub fn pipe() -> io::Result<(Sender, Recver)> { pipe_impl() }
51
52/// Handle to the receiving end of an unnamed pipe, created by the [`pipe()`] function together
53/// with the [sending end](Sender).
54///
55/// The core functionality is exposed via the [`Read`](io::Read) trait. The type is convertible to
56/// and from handles/file descriptors and allows its internal handle/FD to be borrowed. On
57/// Windows, the `ShareHandle` trait is also implemented.
58///
59/// The handle/file descriptor is inheritable. See [module-level documentation](self) for more on
60/// how this can be used.
61// field is pub(crate) to allow platform builders to create the public-facing pipe types
62pub struct Recver(pub(crate) RecverImpl);
63impl Sealed for Recver {}
64multimacro! {
65    Recver,
66    forward_sync_read,
67    forward_handle,
68    forward_debug,
69    derive_raw,
70}
71
72/// Handle to the sending end of an unnamed pipe, created by the [`pipe()`] function together with
73/// the [receiving end](Recver).
74///
75/// The core functionality is exposed via the [`Write`](io::Write) trait. The type is convertible
76/// to and from handles/file descriptors and allows its internal handle/FD to be borrowed. On
77/// Windows, the `ShareHandle` trait is also implemented.
78///
79/// The handle/file descriptor is inheritable. See [module-level documentation](self) for more on
80/// how this can be used.
81///
82/// # Limbo
83/// On Windows, much like named pipes, unnamed pipes are subject to limbo, meaning that dropping
84/// an unnamed pipe does not immediately discard the contents of the send buffer. See the
85/// documentation on `named_pipe::PipeStream` for more.
86///
87/// [ARH]: https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html
88/// [IRH]: https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawHandle.html
89/// [`FromRawHandle`]: https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html
90/// [ARF]: https://doc.rust-lang.org/std/os/unix/io/trait.AsRawFd.html
91/// [IRF]: https://doc.rust-lang.org/std/os/unix/io/trait.IntoRawFd.html
92/// [`FromRawFd`]: https://doc.rust-lang.org/std/os/unix/io/trait.FromRawFd.html
93pub struct Sender(pub(crate) SenderImpl);
94impl Sealed for Sender {}
95multimacro! {
96    Sender,
97    forward_sync_write,
98    forward_handle,
99    forward_debug,
100    derive_raw,
101}
interprocess/unnamed_pipe.rs

interprocess/
unnamed_pipe.rs
