interprocess/unnamed_pipe/
tokio.rs

1//! Tokio-based asynchronous unnamed pipes.
2//!
3//! See the [parent-level documentation](super) for more.
4//!
5//! # Examples
6//! See [`pipe()`].
7
8impmod! {unnamed_pipe::tokio,
9	Recver as RecverImpl,
10	Sender as SenderImpl,
11	pipe_impl,
12}
13use std::io;
14
15/// Creates a new pipe with the default creation settings and returns Tokio-based handles to its
16/// sending end and receiving end.
17///
18/// The platform-specific builders in the `os` module of the crate might be more helpful if extra
19/// configuration for the pipe is needed.
20///
21/// # Examples
22/// ## Basic communication
23/// In a parent process, within a Tokio runtime:
24/// ```no_run
25#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_a.rs")]
26/// ```
27/// In a child process, within a Tokio runtime:
28/// ```no_run
29#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_b.rs")]
30/// ```
31#[inline]
32pub fn pipe() -> io::Result<(Sender, Recver)> {
33	pipe_impl()
34}
35
36/// Tokio-based handle to the receiving end of an unnamed pipe, created by the [`pipe()`] function
37/// together with the [sending end](Sender).
38///
39/// The core functionality is exposed via the [`AsyncRead`](tokio::io::AsyncRead) trait. The type
40/// is convertible to and from handles/file descriptors and allows its internal handle/FD to be
41/// borrowed. On Windows, the `ShareHandle` trait is also implemented.
42///
43/// The handle/file descriptor is inheritable. See [module-level documentation](self) for more on
44/// how this can be used.
45// field is pub(crate) to allow platform builders to create the public-facing pipe types
46pub struct Recver(pub(crate) RecverImpl);
47multimacro! {
48	Recver,
49	pinproj_for_unpin(RecverImpl),
50	forward_tokio_read,
51	forward_as_handle,
52	forward_try_handle(io::Error),
53	forward_debug,
54	derive_asraw,
55}
56
57/// Handle to the sending end of an unnamed pipe, created by the [`pipe()`] function together with
58/// the [receiving end](Recver).
59///
60/// The core functionality is exposed via the [`AsyncWrite`](tokio::io::AsyncWrite) trait. The
61/// type is convertible to and from handles/file descriptors and allows its internal handle/FD to
62/// be borrowed. On Windows, the `ShareHandle` trait is also implemented.
63///
64/// The handle/file descriptor is inheritable. See [module-level documentation](self) for more on
65/// how this can be used.
66pub struct Sender(pub(crate) SenderImpl);
67multimacro! {
68	Sender,
69	pinproj_for_unpin(SenderImpl),
70	forward_rbv(SenderImpl, &),
71	forward_tokio_write,
72	forward_as_handle,
73	forward_try_handle(io::Error),
74	forward_debug,
75	derive_asraw,
76}
interprocess/unnamed_pipe/tokio.rs

interprocess/unnamed_pipe/
tokio.rs
