Sync unnamed pipe examples

examples/unnamed_pipe/sync/main.rs

@@ -1,6 +1,18 @@
 mod side_a;
 mod side_b;
 
-fn main() {
-	todo!()
+#[cfg(windows)]
+type Handle = std::os::windows::io::OwnedHandle;
+#[cfg(unix)]
+type Handle = std::os::unix::io::OwnedFd;
+
+use std::{io, sync::mpsc, thread};
+
+fn main() -> io::Result<()> {
+	let (htx, hrx) = mpsc::sync_channel(1);
+	let jh = thread::spawn(move || side_a::main(htx));
+	let handle = hrx.recv().unwrap();
+
+	side_b::main(handle)?;
+	jh.join().unwrap()
 }

examples/unnamed_pipe/sync/side_a.rs

@@ -0,0 +1,31 @@
+//{
+use std::{io, sync::mpsc};
+pub(super) fn main(handle_sender: mpsc::SyncSender<super::Handle>) -> io::Result<()> {
+	//}
+	use interprocess::unnamed_pipe::pipe;
+	use std::io::{prelude::*, BufReader};
+
+	// Create the unnamed pipe, yielding a sender and a receiver.
+	let (tx, rx) = pipe()?;
+
+	// Let's extract the raw handle or file descriptor of the sender. Note that `OwnedHandle` and
+	// `OwnedFd` both implement `From<unnamed_pipe::Sender>`.
+	let txh = tx.into();
+	// Now deliver `txh` to the child process. This may be done by starting it here with a
+	// command-line argument or via stdin. This works because child processes inherit handles and
+	// file descriptors to unnamed pipes. You can also use a different platform-specific way of
+	// transferring handles or file descriptors across a process boundary.
+	//{
+	handle_sender.send(txh).unwrap();
+	//}
+
+	let mut buf = String::with_capacity(128);
+	// We'd like to receive a line, so buffer our input.
+	let mut rx = BufReader::new(rx);
+	// Receive the line from the other process.
+	rx.read_line(&mut buf)?;
+
+	assert_eq!(buf.trim(), "Hello from side B!");
+	//{
+	Ok(())
+} //}

examples/unnamed_pipe/sync/side_b.rs

@@ -0,0 +1,17 @@
+//{
+pub(super) fn main(handle: super::Handle) -> std::io::Result<()> {
+	//}
+	use interprocess::unnamed_pipe;
+	use std::io::prelude::*;
+
+	// `handle` here is an `OwnedHandle` or an `OwnedFd` from the standard library. Those
+	// implement `FromRawHandle` and `FromRawFd` respectively. The actual value can be transferred
+	// via a command-line parameter since it's numerically equal to the value obtained in the
+	// parent process via `OwnedHandle::from()`/`OwnedFd::from()` thanks to handle inheritance.
+	let mut tx = unnamed_pipe::Sender::from(handle);
+
+	// Send our message to the other side.
+	tx.write_all(b"Hello from side B!\n")?;
+	//{
+	Ok(())
+} //}

src/unnamed_pipe.rs

@@ -15,6 +15,9 @@
 //! which can be used in simple cases instead of unnamed pipes. Making use of that feature is
 //! advisable if the program of the child process can be modified to communicate with its parent
 //! via standard I/O streams.
+//!
+//! # Examples
+//! See [`pipe()`].
 
 #[cfg(feature = "tokio")]
 #[cfg_attr(feature = "doc_cfg", doc(cfg(feature = "tokio")))]
@@ -33,6 +36,17 @@ use std::io;
 ///
 /// The platform-specific builders in the `os` module of the crate might be more helpful if extra
 /// configuration for the pipe is needed.
+///
+/// # Examples
+/// ## Basic communication
+/// In a parent process:
+/// ```no_run
+#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_a.rs")]
+/// ```
+/// In a child process:
+/// ```no_run
+#[doc = doctest_file::include_doctest!("examples/unnamed_pipe/sync/side_b.rs")]
+/// ```
 #[inline]
 pub fn pipe() -> io::Result<(Sender, Recver)> {
 	pipe_impl()