Skip to main content

aws_s3_transfer/runtime/
shutdown.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6//! Opaque observation of transfer-manager-owned runtime destruction.
7
8use std::{error::Error, fmt};
9
10/// Observes managed-runtime completion without retaining the client or owner.
11///
12/// Obtain this value from [`crate::Client::shutdown_completion`] before releasing
13/// the client. Clones and repeated waits observe the same shutdown outcome.
14/// wasm targets have no managed runtime, so no value of this type exists there.
15#[non_exhaustive]
16#[derive(Debug, Clone)]
17pub struct ShutdownCompletion {
18    inner: Inner,
19}
20
21#[cfg(not(target_family = "wasm"))]
22type Inner = aws_smithy_execution::ShutdownCompletion;
23#[cfg(target_family = "wasm")]
24type Inner = std::convert::Infallible;
25
26impl ShutdownCompletion {
27    #[cfg(not(target_family = "wasm"))]
28    pub(crate) fn new(inner: aws_smithy_execution::ShutdownCompletion) -> Self {
29        Self { inner }
30    }
31
32    /// Waits for all managed runtime threads to be joined after owner release.
33    ///
34    /// Waiting does not request shutdown or cancel transfers. Release client
35    /// clones and transfer ownership first; active work and delayed scheduler
36    /// reclamation can retain the owner. Success includes runtime destruction
37    /// and managed-thread local cleanup, but not destruction of independently
38    /// retained HTTP clients or SDK configuration.
39    ///
40    /// Running blocking work must finish; indefinitely blocked or non-yielding
41    /// work can prevent completion. No ambient Tokio runtime is required.
42    /// Dropping this future does not stop joining that has already started.
43    ///
44    /// # Errors
45    ///
46    /// Rejects waiting from this managed runtime's own threads. Also reports
47    /// joiner startup failure, lost completion, and managed-thread panics.
48    pub async fn wait(&self) -> Result<(), ShutdownError> {
49        #[cfg(not(target_family = "wasm"))]
50        return self
51            .inner
52            .wait()
53            .await
54            .map_err(ShutdownError::from_execution);
55        #[cfg(target_family = "wasm")]
56        match self.inner {}
57    }
58}
59
60/// Classifies a failure to observe managed-runtime shutdown.
61#[non_exhaustive]
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub enum ShutdownErrorKind {
64    /// Waiting was attempted from a thread owned by the managed runtime.
65    FromRuntime,
66    /// The joining thread could not be created.
67    Joiner,
68    /// The joining thread did not provide a completion result.
69    Completion,
70    /// A managed thread panicked; all managed threads have been joined.
71    ThreadPanic,
72    /// An unclassified shutdown failure occurred.
73    Other,
74}
75
76/// Failure to observe transfer-manager-owned runtime completion.
77#[non_exhaustive]
78#[derive(Debug)]
79pub struct ShutdownError {
80    kind: ShutdownErrorKind,
81    source: crate::error::BoxError,
82}
83
84impl ShutdownError {
85    /// Returns the classification of this shutdown failure.
86    pub fn kind(&self) -> ShutdownErrorKind {
87        self.kind
88    }
89}
90
91impl ShutdownError {
92    #[cfg(not(target_family = "wasm"))]
93    fn from_execution(source: aws_smithy_execution::ShutdownError) -> Self {
94        use aws_smithy_execution::ShutdownErrorKind as Kind;
95        let kind = match source.kind() {
96            Kind::FromRuntime => ShutdownErrorKind::FromRuntime,
97            Kind::Joiner => ShutdownErrorKind::Joiner,
98            Kind::Completion => ShutdownErrorKind::Completion,
99            Kind::ThreadPanic => ShutdownErrorKind::ThreadPanic,
100            _ => ShutdownErrorKind::Other,
101        };
102        Self {
103            kind,
104            source: Box::new(source),
105        }
106    }
107}
108
109impl fmt::Display for ShutdownError {
110    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
111        write!(f, "managed runtime shutdown failed: {}", self.source)
112    }
113}
114
115impl Error for ShutdownError {
116    fn source(&self) -> Option<&(dyn Error + 'static)> {
117        Some(self.source.as_ref())
118    }
119}