unix_signals.rs

Overview

This file provides functionality to set up asynchronous Unix signal handlers using the Tokio runtime. Specifically, it configures handlers for the SIGINT (interrupt) and SIGTERM (terminate) signals, which are commonly used for graceful shutdown operations in Unix-based systems. The signals are wrapped in Tokio's asynchronous Signal stream, allowing reactive event-driven programming in applications that need to respond to these signals.

Functions

setup_signals() -> anyhow::Result<(Signal, Signal)>

• Purpose:
  Initializes and returns asynchronous streams for the Unix signals SIGINT and SIGTERM.

• Parameters:
  None.

• Return Value:
  Returns a Result containing a tuple of two Signal objects on success:

  • The first Signal corresponds to the SIGINT signal (interrupt).

  • The second Signal corresponds to the SIGTERM signal (terminate).
    If any error occurs during the setup, it returns an error wrapped in anyhow::Result.

• Usage Example:

  use unix_signals::setup_signals;
  
  #[tokio::main]
  async fn main() -> anyhow::Result<()> {
      let (mut sigint, mut sigterm) = setup_signals()?;
  
      tokio::select! {
          _ = sigint.recv() => {
              println!("Received SIGINT, shutting down...");
          }
          _ = sigterm.recv() => {
              println!("Received SIGTERM, shutting down...");
          }
      }
  
      Ok(())
  }
  

• Implementation Details:
  The function calls tokio::signal::unix::signal with SignalKind::interrupt() and SignalKind::terminate() to create two separate signal streams. These streams asynchronously notify when their respective signals are received. The use of anyhow::Result provides a convenient error handling mechanism compatible with many Rust applications.

Important Implementation Notes

• The function leverages Tokio's asynchronous signal handling capabilities, which integrate well with the event loop and allow non-blocking signal processing.

• The choice of SIGINT and SIGTERM covers the most common signals used to interrupt and terminate Unix processes.

• The returned Signal objects implement Stream, enabling the use of async/await and combinators like tokio::select! for concurrent signal handling.

Interaction with Other System Components

• This module is intended to be used in the context of asynchronous applications that require clean shutdown logic or special handling upon receiving Unix signals.

• It depends on Tokio's Unix signal handling facilities (tokio::signal::unix), so the Tokio runtime must be active in the application.

• Other parts of the application can import this module to easily obtain signal streams without manually configuring each signal handler.

• This file does not expose any higher-level shutdown or cleanup logic; it provides only the low-level signal streams. Application logic consuming these streams should implement the actual response to signals.

Diagram: Signal Setup Flow

flowchart TD
A[Start] --> B["Call setup_signals()"]
B --> C[Create SIGINT Signal Stream]
B --> D[Create SIGTERM Signal Stream]
C --> E{Success?}
D --> E
E -- Yes --> F["Return (SIGINT, SIGTERM) tuple"]
E -- No --> G[Return Error]

This diagram represents the flow within the setup_signals function, showing the creation of the two signal streams and their conditional success or failure.