unix_ipc/lib.rs
1//! This crate implements a minimal abstraction over UNIX domain sockets for
2//! the purpose of IPC. It lets you send both file handles and rust objects
3//! between processes.
4//!
5//! # How it works
6//!
7//! This uses [serde](https://serde.rs/) to serialize data over unix sockets
8//! via [bincode](https://github.com/servo/bincode). Thanks to the
9//! [`Handle`](struct.Handle.html) abstraction you can also send any object
10//! across that is convertable into a unix file handle.
11//!
12//! The way this works under the hood is that during serialization and
13//! deserialization encountered file descriptors are tracked. They are then
14//! sent over the unix socket separately. This lets unassociated processes
15//! share file handles.
16//!
17//! If you only want the unix socket abstraction you can disable all default
18//! features and use the raw channels.
19//!
20//! # Example
21//!
22//! ```rust
23//! # use ::serde_ as serde;
24//! use std::env;
25//! use std::process;
26//! use unix_ipc::{channel, Bootstrapper, Receiver, Sender};
27//! use serde::{Deserialize, Serialize};
28//!
29//! const ENV_VAR: &str = "PROC_CONNECT_TO";
30//!
31//! #[derive(Serialize, Deserialize, Debug)]
32//! # #[serde(crate = "serde_")]
33//! pub enum Task {
34//! Sum(Vec<i64>, Sender<i64>),
35//! Shutdown,
36//! }
37//!
38//! if let Ok(path) = env::var(ENV_VAR) {
39//! let receiver = Receiver::<Task>::connect(path).unwrap();
40//! loop {
41//! match receiver.recv().unwrap() {
42//! Task::Sum(values, tx) => {
43//! tx.send(values.into_iter().sum::<i64>()).unwrap();
44//! }
45//! Task::Shutdown => break,
46//! }
47//! }
48//! } else {
49//! let bootstrapper = Bootstrapper::new().unwrap();
50//! let mut child = process::Command::new(env::current_exe().unwrap())
51//! .env(ENV_VAR, bootstrapper.path())
52//! .spawn()
53//! .unwrap();
54//!
55//! let (tx, rx) = channel().unwrap();
56//! bootstrapper.send(Task::Sum(vec![23, 42], tx)).unwrap();
57//! println!("sum: {}", rx.recv().unwrap());
58//! bootstrapper.send(Task::Shutdown).unwrap();
59//! }
60//! ```
61//!
62//! # Feature Flags
63//!
64//! All features are enabled by default but a lot can be turned off to
65//! cut down on dependencies. With all default features enabled only
66//! the raw types are available.
67//!
68//! * `serde`: enables serialization and deserialization.
69//! * `bootstrap`: adds the `Bootstrapper` type.
70//! * `bootstrap-simple`: adds the default `new` constructor to the
71//! bootstrapper.
72mod raw_channel;
73
74#[cfg(feature = "bootstrap")]
75mod bootstrap;
76#[cfg(feature = "serde")]
77mod serde;
78#[cfg(feature = "serde")]
79mod typed_channel;
80
81pub use self::raw_channel::*;
82
83#[cfg(feature = "bootstrap")]
84pub use self::bootstrap::*;
85
86#[cfg(feature = "serde")]
87pub use self::{serde::*, typed_channel::*};
88
89#[doc(hidden)]
90#[cfg(feature = "serde")]
91pub use ::serde_ as _serde_ref;