1#[cfg(unix)]
2use super::unix::{self as os_impl};
3#[cfg(windows)]
4use super::windows::{self as os_impl};
5
6use std::io;
7
8/// Completes when a "ctrl-c" notification is sent to the process.
9///
10/// While signals are handled very differently between Unix and Windows, both
11/// platforms support receiving a signal on "ctrl-c". This function provides a
12/// portable API for receiving this notification.
13///
14/// Once the returned future is polled, a listener is registered. The future
15/// will complete on the first received `ctrl-c` **after** the initial call to
16/// either `Future::poll` or `.await`.
17///
18/// # Caveats
19///
20/// On Unix platforms, the first time that a `Signal` instance is registered for a
21/// particular signal kind, an OS signal-handler is installed which replaces the
22/// default platform behavior when that signal is received, **for the duration of
23/// the entire process**.
24///
25/// For example, Unix systems will terminate a process by default when it
26/// receives a signal generated by `"CTRL+C"` on the terminal. But, when a
27/// `ctrl_c` stream is created to listen for this signal, the time it arrives,
28/// it will be translated to a stream event, and the process will continue to
29/// execute. **Even if this `Signal` instance is dropped, subsequent `SIGINT`
30/// deliveries will end up captured by Tokio, and the default platform behavior
31/// will NOT be reset**.
32///
33/// Thus, applications should take care to ensure the expected signal behavior
34/// occurs as expected after listening for specific signals.
35///
36/// # Examples
37///
38/// ```rust,no_run
39/// use tokio::signal;
40///
41/// #[tokio::main]
42/// async fn main() {
43/// println!("waiting for ctrl-c");
44///
45/// signal::ctrl_c().await.expect("failed to listen for event");
46///
47/// println!("received ctrl-c event");
48/// }
49/// ```
50///
51/// Listen in the background:
52///
53/// ```rust,no_run
54/// tokio::spawn(async move {
55/// tokio::signal::ctrl_c().await.unwrap();
56/// // Your handler here
57/// });
58/// ```
59pub async fn ctrl_c() -> io::Result<()> {
60 os_impl::ctrl_c()?.recv().await;
61 Ok(())
62}
63