shep_channel/lib.rs
1//! Speak the shep shepherd channel: signal readiness, emit a metric,
2//! answer an action. `docs/shepherd-channel.md` has the contract.
3//!
4//! With no channel, nothing is sent and no handler runs. Registering one
5//! still succeeds, so an app needs no branch at its call sites.
6//!
7//! ```
8//! let shepherd = shep_channel::serve();
9//!
10//! shepherd.on_action("gc", |params, _name| {
11//! format!("collected, params={params:?}")
12//! });
13//! shepherd.on_shutdown(|| { /* stop gracefully */ });
14//!
15//! // No channel here: this test runs outside shep. See `is_active`.
16//! assert!(!shepherd.is_active());
17//! shepherd.metric("rps", 4200.0);
18//! shepherd.ready().unwrap();
19//!
20//! // Before the app exits, so a queued reply is not lost with it.
21//! shepherd.flush(std::time::Duration::from_secs(2)).unwrap();
22//! ```
23//! - An action's handler runs on its own thread, never delaying the reader.
24//! - `metric` and `note` drop under backpressure; `ready` and a reply block.
25//! - Sending queues, and a writer thread writes. Call `flush` before exiting.
26//! - An unhandled shutdown warns on stderr. This crate never stops a process.
27
28#![doc(test(attr(deny(warnings))))]
29// Not `forbid`: `endpoint` needs unsafe to reach the channel. Three blocks
30// on unix probe an inherited descriptor before taking it. One on Windows
31// peeks a pipe's buffer. Each carries its own `// SAFETY:` comment.
32#![deny(unsafe_code)]
33
34#[cfg(feature = "client")]
35mod channel;
36#[cfg(feature = "client")]
37mod dispatch;
38#[cfg(feature = "client")]
39mod endpoint;
40#[cfg(feature = "client")]
41mod error;
42#[cfg(feature = "client")]
43mod loops;
44#[cfg(feature = "client")]
45mod metric;
46#[cfg(feature = "client")]
47mod outbox;
48#[cfg(feature = "client")]
49mod serve;
50#[cfg(feature = "client")]
51mod session;
52mod wire;
53
54#[cfg(feature = "client")]
55pub use channel::Channel;
56#[cfg(feature = "client")]
57pub use dispatch::{ActionHandler, CallerActionHandler, ShutdownHandler};
58#[cfg(all(feature = "client", unix))]
59pub use endpoint::take_inherited_socket;
60#[cfg(feature = "client")]
61pub use endpoint::{Endpoint, FD_VAR, PIPE_VAR, VERSION_VAR, discover};
62#[cfg(feature = "client")]
63pub use error::ChannelError;
64#[cfg(feature = "client")]
65pub use metric::MetricOptions;
66#[cfg(feature = "client")]
67pub use serve::{Shepherd, serve};
68pub use wire::{
69 CHANNEL_VERSION, ChildMessage, LambLabel, LambLabelError, MetricType, ShepherdMessage,
70};