aws_s3_transfer/config/runtime.rs
1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6//! Execution configuration with managed ownership or caller-provided Tokio execution.
7
8use crate::runtime::buffer_pool::BufferPool;
9use crate::types::ByteSize;
10use aws_smithy_types::error::operation::BuildError;
11
12/// Selects execution for transfer-manager work.
13///
14/// Defaults to owned managed execution. Configuring HTTP on the SDK or S3
15/// configuration does not change this selection.
16///
17/// ```
18/// use aws_s3_transfer::{config::Managed, config::RuntimeConfig};
19///
20/// let managed = RuntimeConfig::managed(Managed::default());
21/// let caller_runtime = RuntimeConfig::multi_thread_tokio();
22/// ```
23///
24/// # HTTP transport
25///
26/// With managed execution and no HTTP client configured, the transfer manager
27/// builds its own transport:
28///
29/// - One connection pool, partitioned by managed thread, so each connection is
30/// driven by the thread that opened it.
31/// - Connections per host capped according to the process's file-descriptor
32/// limit. Requests beyond the cap wait for a connection.
33/// - Proxy settings from `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` and
34/// `NO_PROXY`.
35///
36/// wasm targets have no such transport; see [`Managed`].
37///
38/// An HTTP client set on the [`SdkConfig`](aws_types::SdkConfig) or S3
39/// configuration replaces this transport: its pool, TLS, DNS and proxy settings
40/// apply, its connections are not partitioned by managed thread, and the
41/// transfer manager does not cap its connections per host. With
42/// [`multi_thread_tokio`](Self::multi_thread_tokio), the S3 client uses the
43/// configured HTTP client or, without one, the SDK default.
44///
45/// Configure an HTTP client to change TLS, DNS or connection settings.
46#[non_exhaustive]
47#[derive(Debug)]
48pub struct RuntimeConfig {
49 kind: Kind,
50}
51
52#[derive(Debug)]
53enum Kind {
54 Managed(Managed),
55 MultiThreadTokio,
56}
57
58impl RuntimeConfig {
59 /// Uses execution owned by the transfer manager.
60 pub fn managed(managed: Managed) -> Self {
61 Self {
62 kind: Kind::Managed(managed),
63 }
64 }
65
66 /// Uses the caller's Tokio runtime without creating managed threads.
67 ///
68 /// Transfer tasks are spawned on the runtime performing dispatch. Use a
69 /// multi-thread runtime so concurrent work can execute on different threads.
70 /// wasm targets are the exception: their threads are unavailable or
71 /// cooperative, so a current-thread runtime is supported there.
72 pub fn multi_thread_tokio() -> Self {
73 Self {
74 kind: Kind::MultiThreadTokio,
75 }
76 }
77
78 pub(crate) fn managed_config(&self) -> Option<&Managed> {
79 match &self.kind {
80 Kind::Managed(managed) => Some(managed),
81 Kind::MultiThreadTokio => None,
82 }
83 }
84
85 #[cfg(not(target_family = "wasm"))]
86 pub(crate) fn managed_config_mut(&mut self) -> Option<&mut Managed> {
87 match &mut self.kind {
88 Kind::Managed(managed) => Some(managed),
89 Kind::MultiThreadTokio => None,
90 }
91 }
92}
93
94impl Default for RuntimeConfig {
95 fn default() -> Self {
96 Self::managed(Managed::default())
97 }
98}
99
100/// Configures managed execution owned by the transfer manager.
101///
102/// Default construction discovers usable execution targets when the client
103/// is created. Active transfers retain the owner after client clones are
104/// dropped. Owner destruction requests shutdown without synchronously joining
105/// the managed threads. [`crate::Client::shutdown_completion`] provides a
106/// non-owning observer of their joins.
107///
108/// wasm targets cannot run managed threads. There, managed execution behaves
109/// as [`RuntimeConfig::multi_thread_tokio`], including its support for a
110/// current-thread runtime, and creates no owner to observe.
111#[non_exhaustive]
112#[derive(Debug, Default)]
113pub struct Managed {
114 #[cfg_attr(
115 target_family = "wasm",
116 expect(dead_code, reason = "wasm targets build no managed runtime")
117 )]
118 source: Source,
119}
120
121#[derive(Debug, Default)]
122enum Source {
123 #[default]
124 Automatic,
125 #[cfg(feature = "__unstable_ext")]
126 Adopted(Option<aws_smithy_execution::ManagedRuntime>),
127}
128
129impl Managed {
130 #[cfg(feature = "__unstable_ext")]
131 pub(crate) fn from_runtime(runtime: aws_smithy_execution::ManagedRuntime) -> Self {
132 Self {
133 source: Source::Adopted(Some(runtime)),
134 }
135 }
136
137 #[cfg(not(target_family = "wasm"))]
138 pub(crate) fn build(
139 &mut self,
140 ) -> Result<aws_smithy_execution::ManagedRuntime, aws_smithy_runtime_api::box_error::BoxError>
141 {
142 match &mut self.source {
143 Source::Automatic => aws_smithy_execution::ManagedRuntime::builder()
144 .thread_name_prefix("s3-tm")
145 .pin_threads(false)
146 .build()
147 .map_err(Into::into),
148 #[cfg(feature = "__unstable_ext")]
149 Source::Adopted(owner) => {
150 // Config retains its managed selection after execution takes
151 // ownership. A second take must not construct another runtime.
152 Ok(owner.take().expect("adopted managed runtime already taken"))
153 }
154 }
155 }
156}
157
158#[cfg(all(test, feature = "__unstable_ext", not(miri)))]
159mod tests {
160 use super::*;
161 use aws_smithy_execution::{topology::Topology, ManagedRuntime};
162
163 #[test]
164 fn adoption_preserves_identity_topology_and_names_and_takes_owner_once() {
165 let runtime = ManagedRuntime::builder()
166 .topology(Topology::detect().unwrap().with_max_placements(1))
167 .thread_name_prefix("external")
168 .pin_threads(false)
169 .build()
170 .unwrap();
171 let before = runtime.handle();
172 let mut managed = Managed::from_runtime(runtime);
173 let runtime = managed.build().unwrap();
174 let after = runtime.handle();
175 assert_eq!(before.id(), after.id());
176 assert_eq!(
177 before.topology().placements(),
178 after.topology().placements()
179 );
180 let caller = tokio::runtime::Builder::new_current_thread()
181 .enable_all()
182 .build()
183 .unwrap();
184 let partition = after.partitions()[0].clone();
185 let expected = partition.id();
186 let observed = after.clone();
187 caller
188 .block_on(partition.spawn(async move {
189 assert_eq!(observed.current_partition().unwrap().id(), expected);
190 assert!(std::thread::current()
191 .name()
192 .unwrap()
193 .starts_with("external-"));
194 }))
195 .unwrap();
196 let repeated = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| managed.build()));
197 assert!(
198 repeated.is_err(),
199 "a consumed owner must not become automatic execution"
200 );
201 caller.block_on(runtime.shutdown()).unwrap();
202 }
203}
204
205/// The concurrency mode the client should use for executing requests.
206#[non_exhaustive]
207#[derive(Debug, Clone, Default)]
208pub enum ConcurrencyMode {
209 /// Automatically configured concurrency based on the execution environment.
210 #[default]
211 Auto,
212
213 /// Concurrency sized for a network throughput target, in gigabits per second.
214 ///
215 /// The target replaces the throughput estimated from the execution
216 /// environment. It sets the in-flight request target once, when the client
217 /// is constructed; it does not limit throughput at run time. Requests beyond
218 /// what the per-host connection cap or the payload-memory ceiling allows wait
219 /// for a connection or for memory.
220 TargetThroughput(TargetThroughput),
221
222 /// Explicit concurrency control
223 Explicit(usize),
224}
225
226/// A network throughput target for [`ConcurrencyMode::TargetThroughput`].
227///
228/// One target currently applies to uploads and downloads alike. The value is
229/// private so that per-direction targets can be added later without breaking
230/// callers.
231#[derive(Debug, Clone, Copy, PartialEq)]
232pub struct TargetThroughput {
233 gbps: f64,
234}
235
236impl TargetThroughput {
237 /// A target of `gbps` gigabits per second, for uploads and downloads.
238 ///
239 /// Returns an error unless `gbps` is finite and positive.
240 pub fn gbps(gbps: f64) -> Result<Self, BuildError> {
241 if gbps.is_finite() && gbps > 0.0 {
242 Ok(Self { gbps })
243 } else {
244 Err(BuildError::invalid_field(
245 "gbps",
246 format!("throughput target must be finite and positive, got {gbps}"),
247 ))
248 }
249 }
250
251 /// The target in gigabits per second.
252 pub fn as_gbps(&self) -> f64 {
253 self.gbps
254 }
255}
256
257/// Selects the payload-memory pool used by a transfer-manager client.
258#[non_exhaustive]
259#[derive(Debug, Clone, Default)]
260pub enum MemoryConfig {
261 /// Construct an automatically sized pool when the client is created.
262 ///
263 /// The ceiling follows [`MemoryBudgetConfig::Auto`], raised to at least
264 /// 256 MiB but not above half of detected memory.
265 #[default]
266 Auto,
267 /// Use an existing pool.
268 ///
269 /// Every client or component using a clone of this pool shares one
270 /// admission ceiling, prepared-storage cache, and metrics domain.
271 Explicit(BufferPool),
272}
273
274/// Configured capacity for reservation-based pooled transfer data.
275///
276/// Requests that fit within the resolved capacity backpressure when capacity
277/// is unavailable. A single reservation larger than the resolved capacity is
278/// rejected. Unreserved acquisition and process or runtime overhead are
279/// outside this ceiling.
280#[non_exhaustive]
281#[derive(Debug, Clone, Default)]
282pub enum MemoryBudgetConfig {
283 /// Use up to one quarter of detected effective memory, capped at 32 GiB.
284 ///
285 /// Effective memory includes process or container limits where the platform
286 /// exposes them. The result may be rounded down to the pool's allocation
287 /// unit. If detection is unavailable, the pool uses 2 GiB.
288 #[default]
289 Auto,
290 /// Use the given fraction of detected effective memory.
291 ///
292 /// The fraction must be finite and in `(0.0, 1.0]`. This policy requires
293 /// memory detection and does not apply the automatic 32 GiB cap.
294 Fraction(f64),
295 /// An explicit byte limit that bypasses memory detection.
296 ///
297 /// The resolved capacity never exceeds this value and may be smaller by
298 /// less than one platform allocation unit. Values too small to fund one
299 /// allocation unit are rejected. The resolved capacity is reported by
300 /// [`MemoryMetrics::capacity_bytes`].
301 ///
302 /// [`MemoryMetrics::capacity_bytes`]:
303 /// crate::metrics::MemoryMetrics::capacity_bytes
304 Limit(ByteSize),
305}