aws-s3-transfer 1.0.0

Transfer Manager for Amazon S3 - a high-performance data plane client for uploading and downloading objects and directories.
Documentation
/*
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

//! Execution runtime for running IO requests dispatched by the scheduler.
//!
//! The scheduler decides WHAT to run and WHEN. The runtime decides WHERE and HOW.

mod tokio_mt;
pub(crate) use tokio_mt::TokioMultiThreadRuntime;

#[cfg(test)]
pub(crate) mod test_util;

mod shutdown;
pub use shutdown::{ShutdownCompletion, ShutdownError, ShutdownErrorKind};

// Managed execution spawns OS threads and builds a native HTTP transport,
// neither of which wasm targets provide.
#[cfg(not(target_family = "wasm"))]
mod managed;
#[cfg(not(target_family = "wasm"))]
pub(crate) use managed::{prepare_components, ManagedExecution};

#[allow(dead_code)]
pub(crate) mod buffer_pool;
pub(crate) mod platform;
pub(crate) mod sizing;
pub(crate) mod sync;

use aws_smithy_runtime_api::client::http::SharedHttpClient;

use crate::runtime::sync::SubmissionGuard;
use crate::scheduler::descriptor::TransferDescriptor;
use crate::transfer::{IoRequest, TransferId};

/// Work item with scheduler tracking attached.
///
/// Wraps an `IoRequest` with a `TransferDescriptor` that the runtime uses to
/// report execution lifecycle events back to the scheduler. The runtime calls
/// `descriptor.work_started()` when execution begins and the scheduler observes
/// completion via `descriptor.work_finished()` in `on_completion`. This lets the
/// scheduler track outstanding work without prescribing when or how the runtime
/// executes it.
#[derive(Debug)]
pub(crate) struct ScheduledWork {
    pub(crate) item: IoRequest,
    pub(crate) descriptor: TransferDescriptor,
}

/// The execution layer that runs IO requests dispatched by the scheduler.
///
/// The scheduler decides WHAT to run and WHEN. The runtime decides WHERE and HOW.
pub(crate) trait ExecutionRuntime: Send + Sync + std::fmt::Debug {
    /// Dispatch a batch of IO requests for execution.
    fn dispatch(&self, batch: &mut SubmissionGuard<'_, ScheduledWork>);

    /// Requests execution shutdown.
    fn shutdown(&self);

    /// Returns an observer for owned execution, or None for caller-owned execution.
    fn shutdown_completion(&self) -> Option<ShutdownCompletion>;

    /// Remove all pending work for a transfer. Returns count removed.
    fn remove_pending_for_transfer(&self, id: TransferId) -> usize;

    /// Runtime-provided components for S3 client construction and execution.
    fn components(&self) -> &RuntimeComponents;
}

/// Options for the HTTP transport a runtime provides to the S3 client.
///
/// Present only when that transport will be installed, so a runtime given
/// `None` builds no HTTP client.
#[derive(Debug, Clone)]
#[cfg_attr(
    target_family = "wasm",
    expect(dead_code, reason = "read only by the managed runtime's transport")
)]
pub(crate) struct RuntimeHttpOptions {
    /// Interfaces to bind connections to, assigned to worker threads
    /// round-robin. Empty leaves interface selection to OS routing.
    pub(crate) network_interfaces: Vec<String>,
    /// Maximum connections to one origin across all worker threads.
    pub(crate) max_connections_per_host: usize,
}

/// Components provided by the execution runtime to the rest of the system.
///
/// The runtime populates these based on its execution model.
#[derive(Debug, Clone, Default)]
pub(crate) struct RuntimeComponents {
    http_client: Option<SharedHttpClient>,
    /// When true, file I/O runs directly on the calling thread: managed
    /// threads, and wasm targets, whose threads are unavailable or cooperative.
    /// When false, file I/O is offloaded via spawn_blocking (shared runtimes).
    direct_io: bool,
    /// Whether file bodies may read synchronously on the HTTP polling thread:
    /// with TM-built managed HTTP, and on wasm targets.
    direct_body_io: bool,
}

impl RuntimeComponents {
    /// HTTP client appropriate for this runtime's execution model.
    pub(crate) fn http_client(&self) -> Option<&SharedHttpClient> {
        self.http_client.as_ref()
    }

    /// Whether file I/O should run directly on the calling thread.
    pub(crate) fn direct_io(&self) -> bool {
        self.direct_io
    }

    /// Whether file bodies may read synchronously when HTTP polls them.
    pub(crate) fn direct_body_io(&self) -> bool {
        self.direct_body_io
    }

    /// Enables direct transfer reads, and direct body reads only for owned HTTP.
    #[cfg(not(target_family = "wasm"))]
    pub(crate) fn managed(http_client: Option<SharedHttpClient>) -> Self {
        Self {
            direct_io: true,
            direct_body_io: http_client.is_some(),
            http_client,
        }
    }

    /// Enables direct transfer and body reads without an HTTP client, for
    /// targets where blocking offload cannot keep a read off the polling
    /// thread: wasip1 and wasip2 cannot spawn the threads a blocking pool
    /// needs, and wasip3's cooperative threads run one at a time.
    pub(crate) fn inline_io() -> Self {
        Self {
            direct_io: true,
            direct_body_io: true,
            http_client: None,
        }
    }
}