proc_daemon/
lib.rs

1//! # proc-daemon: High-Performance Daemon Framework
2//!
3//! A foundational framework for building high-performance, resilient daemon services in Rust.
4//! Designed for enterprise applications requiring nanosecond-level performance, bulletproof
5//! reliability, and extreme concurrency.
6//!
7//! ## Key Features
8//!
9//! - **Zero-Copy Architecture**: Minimal allocations with memory pooling
10//! - **Runtime Agnostic**: Support for both Tokio and async-std via feature flags
11//! - **Cross-Platform**: First-class support for Linux, macOS, and Windows
12//! - **Graceful Shutdown**: Coordinated shutdown with configurable timeouts
13//! - **Signal Handling**: Robust cross-platform signal management
14//! - **Configuration**: Hot-reloadable configuration with multiple sources
15//! - **Structured Logging**: High-performance tracing with JSON support
16//! - **Subsystem Management**: Concurrent subsystem lifecycle management
17//! - **Enterprise Ready**: Built for 100,000+ concurrent operations
18//!
19//! ## Quick Start
20//!
21//! ```rust,compile_fail
22//! // This example is marked as compile_fail to prevent freezing in doctests
23//! use proc_daemon::{Daemon, Config, Result};
24//! use std::time::Duration;
25//!
26//! async fn my_service(mut shutdown: proc_daemon::ShutdownHandle) -> Result<()> {
27//!     // Limited iterations to prevent infinite loops
28//!     for _ in 0..3 {
29//!         tokio::select! {
30//!             _ = shutdown.cancelled() => {
31//!                 tracing::info!("Service shutting down gracefully");
32//!                 return Ok(());
33//!             }
34//!             _ = tokio::time::sleep(Duration::from_millis(10)) => {
35//!                 tracing::info!("Service working...");
36//!             }
37//!         }
38//!     }
39//!     Ok(())
40//! }
41//!
42//! #[tokio::main]
43//! async fn main() -> Result<()> {
44//!     let config = Config::new()?;
45//!     
46//!     // Set a timeout for the daemon to auto-shutdown
47//!     let daemon_handle = Daemon::builder(config)
48//!         .with_subsystem_fn("main", my_service)
49//!         .run()
50//!         .await?
51//!     
52//!     // Wait for a short time, then explicitly shut down
53//!     tokio::time::sleep(Duration::from_millis(100)).await;
54//!     daemon_handle.initiate_shutdown();
55//!     Ok(())
56//! }
57//! ```
58//!
59//! ```rust,ignore
60//! // This example is marked as ignore to prevent freezing in doctests
61//! use proc_daemon::{Daemon, Config, Result};
62//! use std::time::Duration;
63//!
64//! async fn my_service(mut shutdown: proc_daemon::ShutdownHandle) -> Result<()> {
65//!     // Use a counter to avoid infinite loops
66//!     let mut counter = 0;
67//!     while counter < 3 {
68//!         tokio::select! {
69//!             _ = shutdown.cancelled() => {
70//!                 tracing::info!("Service shutting down gracefully");
71//!                 break;
72//!             }
73//!             _ = tokio::time::sleep(Duration::from_millis(10)) => {
74//!                 tracing::info!("Service working...");
75//!                 counter += 1;
76//!             }
77//!         }
78//!     }
79//!     Ok(())
80//! }
81//!
82//! #[tokio::main]
83//! async fn main() -> Result<()> {
84//!     let config = Config::new()?;
85//!     
86//!     // Auto-shutdown after a brief time
87//!     tokio::spawn(async {
88//!         tokio::time::sleep(Duration::from_millis(50)).await;
89//!         std::process::exit(0); // Force exit to prevent hanging
90//!     });
91//!     
92//!     Daemon::builder(config)
93//!         .with_subsystem_fn("main", my_service)
94//!         .run()
95//!         .await
96//! }
97//! ```
98
99#![deny(missing_docs)]
100#![deny(unsafe_code)]
101#![warn(clippy::all)]
102#![warn(clippy::pedantic)]
103#![warn(clippy::nursery)]
104
105// Private modules
106mod config;
107mod daemon;
108mod error;
109mod pool;
110
111// Public modules
112pub mod lock;
113pub mod resources;
114pub mod shutdown;
115pub mod signal;
116pub mod subsystem;
117
118// Public exports
119pub use config::{Config, LogLevel};
120pub use daemon::{Daemon, DaemonBuilder};
121pub use error::{Error, Result};
122pub use pool::*;
123pub use shutdown::{ShutdownHandle, ShutdownReason};
124pub use subsystem::{RestartPolicy, Subsystem, SubsystemId};
125
126#[cfg(feature = "metrics")]
127pub mod metrics;
128
129#[cfg(feature = "ipc")]
130pub mod ipc;
131
132/// Version of the proc-daemon library
133pub const VERSION: &str = env!("CARGO_PKG_VERSION");
134
135/// Default shutdown timeout in milliseconds
136pub const DEFAULT_SHUTDOWN_TIMEOUT_MS: u64 = 5000;
137
138/// Default configuration file name
139pub const DEFAULT_CONFIG_FILE: &str = "daemon.toml";
proc_daemon/lib.rs

proc_daemon/
lib.rs
