Skip to main content

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}