1use std::future::Future;
24use std::pin::Pin;
25use std::sync::Arc;
26use std::sync::atomic::{AtomicU8, Ordering};
27use std::task::{Context, Poll};
28use std::time::Duration;
29
30use tokio::time::{Instant, timeout};
31
32use crate::error::{AppError, AppResult, EXIT_INTERRUPTED, ErrorKind};
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum CancelKind {
37 Interrupt,
39 Terminate,
41}
42
43const FLAG_NONE: u8 = 0;
44const FLAG_INTERRUPT: u8 = 1;
45const FLAG_TERMINATE: u8 = 2;
46
47#[derive(Debug, Clone, Default)]
61pub struct CancelFlag {
62 state: Arc<AtomicU8>,
63}
64
65impl CancelFlag {
66 pub fn new() -> Self {
68 Self {
69 state: Arc::new(AtomicU8::new(FLAG_NONE)),
70 }
71 }
72
73 pub fn cancel(&self) {
75 self.cancel_with(CancelKind::Terminate);
76 }
77
78 pub fn cancel_with(&self, kind: CancelKind) {
83 let v = match kind {
84 CancelKind::Interrupt => FLAG_INTERRUPT,
85 CancelKind::Terminate => FLAG_TERMINATE,
86 };
87 let _ = self
89 .state
90 .compare_exchange(FLAG_NONE, v, Ordering::SeqCst, Ordering::SeqCst);
91 }
92
93 pub fn is_cancelled(&self) -> bool {
95 self.state.load(Ordering::SeqCst) != FLAG_NONE
97 }
98
99 pub fn kind(&self) -> Option<CancelKind> {
101 match self.state.load(Ordering::SeqCst) {
103 FLAG_INTERRUPT => Some(CancelKind::Interrupt),
104 FLAG_TERMINATE => Some(CancelKind::Terminate),
105 _ => None,
106 }
107 }
108
109 pub fn check(&self) -> AppResult<()> {
115 match self.kind() {
116 None => Ok(()),
117 Some(CancelKind::Interrupt) => Err(AppError::interrupted()),
118 Some(CancelKind::Terminate) => Err(AppError::terminated()),
119 }
120 }
121}
122
123pub async fn with_wall_clock<T, F, Fut>(deadline: Duration, fut: F) -> AppResult<T>
130where
131 F: FnOnce() -> Fut,
132 Fut: Future<Output = AppResult<T>>,
133{
134 match timeout(deadline, fut()).await {
135 Ok(inner) => inner,
136 Err(_) => Err(AppError::new(
137 ErrorKind::Timeout,
138 format!("wall-clock timeout after {}s", deadline.as_secs()),
139 )),
140 }
141}
142
143pub async fn race_op_with_cancel_and_deadline<T, Fut>(
161 deadline: Duration,
162 cancel_flag: CancelFlag,
163 op: Fut,
164) -> AppResult<T>
165where
166 Fut: Future<Output = AppResult<T>>,
167{
168 tokio::pin!(op);
169 let cancel = wait_for_cancel();
170 tokio::pin!(cancel);
171
172 let timed = timeout(deadline, async {
173 tokio::select! {
174 biased;
175 kind = &mut cancel => {
176 cancel_flag.cancel_with(kind);
177 match kind {
178 CancelKind::Interrupt => Err(AppError::interrupted()),
179 CancelKind::Terminate => Err(AppError::terminated()),
180 }
181 }
182 res = &mut op => res,
183 }
184 });
185
186 match timed.await {
187 Ok(inner) => inner,
188 Err(_) => {
189 cancel_flag.cancel_with(CancelKind::Terminate);
190 Err(AppError::new(
191 ErrorKind::Timeout,
192 format!("wall-clock timeout after {}s", deadline.as_secs()),
193 ))
194 }
195 }
196}
197
198pub fn duration_ms(start: Instant) -> u64 {
200 start.elapsed().as_millis() as u64
201}
202
203pub fn flush_stdio() {
205 use std::io::Write;
206 let _ = std::io::stdout().flush();
207 let _ = std::io::stderr().flush();
208}
209
210pub async fn wait_for_cancel() -> CancelKind {
218 #[cfg(unix)]
219 {
220 use tokio::signal::unix::{SignalKind, signal};
221 let mut sigint = match signal(SignalKind::interrupt()) {
222 Ok(s) => s,
223 Err(_) => {
224 let _ = tokio::signal::ctrl_c().await;
225 return CancelKind::Interrupt;
226 }
227 };
228 let mut sigterm = match signal(SignalKind::terminate()) {
229 Ok(s) => s,
230 Err(_) => {
231 let _ = tokio::signal::ctrl_c().await;
232 return CancelKind::Interrupt;
233 }
234 };
235 let mut sighup = match signal(SignalKind::hangup()) {
236 Ok(s) => s,
237 Err(_) => {
238 tokio::select! {
240 _ = sigint.recv() => return CancelKind::Interrupt,
241 _ = sigterm.recv() => return CancelKind::Terminate,
242 }
243 }
244 };
245 tokio::select! {
246 _ = sigint.recv() => CancelKind::Interrupt,
247 _ = sigterm.recv() => CancelKind::Terminate,
248 _ = sighup.recv() => CancelKind::Terminate,
249 }
250 }
251 #[cfg(windows)]
252 {
253 use tokio::signal::windows::{ctrl_break, ctrl_c, ctrl_close};
254 let mut c_c = match ctrl_c() {
255 Ok(s) => s,
256 Err(_) => {
257 let _ = tokio::signal::ctrl_c().await;
258 return CancelKind::Interrupt;
259 }
260 };
261 let mut c_break = match ctrl_break() {
262 Ok(s) => s,
263 Err(_) => {
264 let _ = c_c.recv().await;
266 return CancelKind::Interrupt;
267 }
268 };
269 let mut c_close = match ctrl_close() {
270 Ok(s) => s,
271 Err(_) => {
272 tokio::select! {
273 _ = c_c.recv() => return CancelKind::Interrupt,
274 _ = c_break.recv() => return CancelKind::Terminate,
275 }
276 }
277 };
278 tokio::select! {
279 _ = c_c.recv() => CancelKind::Interrupt,
280 _ = c_break.recv() => CancelKind::Terminate,
281 _ = c_close.recv() => CancelKind::Terminate,
282 }
283 }
284 #[cfg(not(any(unix, windows)))]
285 {
286 let _ = tokio::signal::ctrl_c().await;
288 CancelKind::Interrupt
289 }
290}
291
292pub const DOUBLE_INTERRUPT_FORCE_SECS: u64 = 5;
294
295pub fn spawn_double_interrupt_force_exit() -> tokio::task::JoinHandle<()> {
301 tokio::spawn(async move {
302 #[cfg(unix)]
303 {
304 use tokio::signal::unix::{SignalKind, signal};
305 let mut sigint = match signal(SignalKind::interrupt()) {
306 Ok(s) => s,
307 Err(_) => return,
308 };
309 let _ = sigint.recv().await;
311 let first = Instant::now();
312 let second = sigint.recv();
314 tokio::pin!(second);
315 match tokio::time::timeout(
316 Duration::from_secs(DOUBLE_INTERRUPT_FORCE_SECS),
317 &mut second,
318 )
319 .await
320 {
321 Ok(Some(())) => {
322 let _ = first;
323 let _ = writeln_force_hint();
324 flush_stdio();
325 std::process::exit(i32::from(EXIT_INTERRUPTED));
327 }
328 Ok(None) => {
329 }
331 Err(_) => {
332 }
334 }
335 }
336 #[cfg(not(unix))]
337 {
338 let _ = tokio::signal::ctrl_c().await;
340 let first = Instant::now();
341 match tokio::time::timeout(
342 Duration::from_secs(DOUBLE_INTERRUPT_FORCE_SECS),
343 tokio::signal::ctrl_c(),
344 )
345 .await
346 {
347 Ok(Ok(())) => {
348 if first.elapsed() <= Duration::from_secs(DOUBLE_INTERRUPT_FORCE_SECS) {
349 let _ = writeln_force_hint();
350 flush_stdio();
351 std::process::exit(i32::from(EXIT_INTERRUPTED));
352 }
353 }
354 _ => {}
355 }
356 }
357 })
358}
359
360fn writeln_force_hint() -> std::io::Result<()> {
361 use std::io::Write;
362 let mut err = std::io::stderr();
363 writeln!(
364 err,
365 "docsrs-cli: second interrupt within {DOUBLE_INTERRUPT_FORCE_SECS}s; forcing exit {EXIT_INTERRUPTED}"
366 )?;
367 err.flush()
368}
369
370pub struct ProgressGuard {
382 done: Arc<std::sync::atomic::AtomicBool>,
383 handle: Option<tokio::task::JoinHandle<()>>,
384}
385
386impl ProgressGuard {
387 pub fn start(quiet: bool, delay: Duration, message: String) -> Self {
389 let done = Arc::new(std::sync::atomic::AtomicBool::new(false));
390 if quiet {
391 return Self { done, handle: None };
392 }
393 let flag = Arc::clone(&done);
394 let handle = tokio::spawn(async move {
395 tokio::time::sleep(delay).await;
396 if !flag.load(Ordering::SeqCst) {
398 use std::io::Write;
399 let _ = writeln!(std::io::stderr(), "{message}");
400 let _ = std::io::stderr().flush();
401 }
402 });
403 Self {
404 done,
405 handle: Some(handle),
406 }
407 }
408
409 pub fn finish(mut self) {
411 self.shutdown();
412 }
413
414 fn shutdown(&mut self) {
415 self.done.store(true, Ordering::SeqCst);
417 if let Some(h) = self.handle.take() {
418 h.abort();
419 }
420 }
421}
422
423impl Drop for ProgressGuard {
424 fn drop(&mut self) {
425 self.shutdown();
426 }
427}
428
429pub struct CancelPoll<'a> {
431 flag: &'a CancelFlag,
432}
433
434impl Future for CancelPoll<'_> {
435 type Output = AppResult<()>;
436 fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
437 Poll::Ready(self.flag.check())
438 }
439}
440
441#[cfg(test)]
442mod tests {
443 use super::*;
444
445 #[tokio::test]
446 async fn wall_clock_timeout() {
447 let err = with_wall_clock(Duration::from_millis(20), || async {
448 tokio::time::sleep(Duration::from_millis(200)).await;
449 Ok::<(), AppError>(())
450 })
451 .await
452 .unwrap_err();
453 assert_eq!(err.kind(), ErrorKind::Timeout);
454 }
455
456 #[tokio::test]
457 async fn cancel_flag_check_defaults_to_terminated() {
458 let f = CancelFlag::new();
459 assert!(f.check().is_ok());
460 f.cancel();
461 assert_eq!(f.check().unwrap_err().kind(), ErrorKind::Terminated);
462 assert_eq!(f.kind(), Some(CancelKind::Terminate));
463 }
464
465 #[tokio::test]
466 async fn cancel_flag_preserves_interrupt_kind() {
467 let f = CancelFlag::new();
468 f.cancel_with(CancelKind::Interrupt);
469 assert_eq!(f.check().unwrap_err().kind(), ErrorKind::Interrupted);
470 f.cancel_with(CancelKind::Terminate);
472 assert_eq!(f.check().unwrap_err().kind(), ErrorKind::Interrupted);
473 }
474
475 #[test]
476 fn duration_ms_non_zero_after_sleep() {
477 let start = Instant::now();
478 std::thread::sleep(Duration::from_millis(5));
479 assert!(duration_ms(start) >= 1);
480 }
481
482 #[tokio::test]
483 async fn race_deadline_wins() {
484 let flag = CancelFlag::new();
485 let err = race_op_with_cancel_and_deadline(Duration::from_millis(15), flag, async {
486 tokio::time::sleep(Duration::from_millis(200)).await;
487 Ok::<(), AppError>(())
488 })
489 .await
490 .unwrap_err();
491 assert_eq!(err.kind(), ErrorKind::Timeout);
492 }
493
494 #[tokio::test]
495 async fn progress_guard_quiet_is_noop() {
496 let g = ProgressGuard::start(true, Duration::from_millis(1), "x".into());
497 g.finish();
498 }
499
500 #[tokio::test]
501 async fn progress_guard_drop_aborts_without_finish() {
502 let g = ProgressGuard::start(false, Duration::from_secs(60), "must-not-print".into());
504 drop(g);
505 }
506
507 #[test]
508 fn flush_stdio_does_not_panic() {
509 flush_stdio();
510 }
511
512 #[test]
513 fn double_interrupt_window_is_five_seconds() {
514 assert_eq!(DOUBLE_INTERRUPT_FORCE_SECS, 5);
515 }
516
517 #[tokio::test]
518 async fn spawn_double_interrupt_handle_aborts_cleanly() {
519 let h = spawn_double_interrupt_force_exit();
520 h.abort();
521 let _ = h.await;
522 }
523}