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}