1 #[cfg(unix)]
2 use super::unix::{self as os_impl};
3 #[cfg(windows)]
4 use super::windows::{self as os_impl};
5
6 use 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 /// ```
ctrl_c() -> io::Result<()>50 pub async fn ctrl_c() -> io::Result<()> {
51 os_impl::ctrl_c()?.recv().await;
52 Ok(())
53 }
54