Skip to main content

Client

Struct Client 

Source
pub struct Client { /* private fields */ }
Expand description

Transfer manager client for Amazon Simple Storage Service.

Implementations§

Source§

impl Client

Source

pub fn shutdown_completion(&self) -> Option<ShutdownCompletion>

Returns a non-owning observer of managed-runtime shutdown completion.

Returns Some for automatically created and adopted managed runtimes, and None for caller-owned Tokio execution. Retaining the observer does not keep this client or its runtime owner alive. Waiting does not request shutdown: release client clones and transfer ownership first.

Source

pub fn new(config: Config) -> Client

Creates a new client from a transfer manager config.

§Panics

Panics when a component the configuration selects cannot be constructed:

  • With the automatic memory configuration, the buffer pool cannot be sized for this machine: the OS page size is unavailable or produces an unsupported pool layout, or the detected memory is too small to hold one buffer. An explicitly configured BufferPool reports these conditions as errors from BufferPoolBuilder::build instead.
  • With managed execution, the managed runtime cannot be started, for example because topology discovery fails or a managed thread cannot be created or initialized.
  • With managed execution and no HTTP client configured on the S3 configuration, the default HTTP transport cannot be constructed.
Source

pub fn config(&self) -> &Config

Returns the client’s configuration

Source

pub fn metrics(&self) -> ClientMetrics

Returns point-in-time operational metrics for this client.

Source

pub fn upload(&self) -> UploadFluentBuilder

Upload a single object to S3.

Constructs a fluent builder for the Upload operation.

§Examples
use std::error::Error;
use std::path::Path;
use aws_s3_transfer::io::InputStream;

async fn upload_file(
    client: &aws_s3_transfer::Client,
    path: impl AsRef<Path>
) -> Result<(), Box<dyn Error>> {
    let stream = InputStream::from_path(path)?;
    let handle = client.upload()
        .bucket("my-bucket")
        .key("my-key")
        .body(stream)
        .initiate()?;

    // initiate() will return before the transfer is complete.
    // Call the `join()` method on the returned handle to drive the transfer to completion.
    // The handle also reports status and metrics, adjusts scheduling, and aborts the transfer.
    let response = handle.join().await?;
    // ... do something with response
    Ok(())
}
Source

pub fn download(&self) -> DownloadFluentBuilder

Download a single object from S3.

A single logical request may be split into many concurrent ranged GetObject requests to improve throughput.

Constructs a fluent builder for the Download operation.

§Examples
use std::error::Error;

async fn get_object(client: &aws_s3_transfer::Client) -> Result<(), Box<dyn Error>> {

    let handle = client
        .download()
        .bucket("my-bucket")
        .key("my-key")
        .initiate()?;

    // initiate() will return before the transfer is complete.
    // Call the `join()` method on the returned handle to drive the transfer to completion.
    // The handle also exposes the object metadata and body, reports status and metrics,
    // adjusts scheduling and read-ahead, and aborts the transfer.
    let response = handle.join().await?;
    // ... do something with response
    Ok(())
}
Source

pub fn download_objects(&self) -> DownloadObjectsFluentBuilder

Download multiple objects from an Amazon S3 bucket to a local directory

Each object is written at its full key under the destination directory. The walker’s prefix selects the objects and does not shorten their paths. See DownloadObjectsInput for how keys map to paths.

Each object is written to a temporary file beside its destination path and renamed into place when that object’s download succeeds, replacing any file already at that path. A successful join means the operating system accepted every byte of each downloaded object and completed each rename. The transfer manager does not call sync_data or sync_all on the files, or synchronize any directory, including the directories it creates, so success does not promise persistence across a system crash or power loss.

Constructs a fluent builder for the DownloadObjects operation.

§Examples
use std::path::PathBuf;
use aws_s3_transfer::error::Error;
use aws_s3_transfer::io::walk::S3Walker;

async fn download_photos(
    client: &aws_s3_transfer::Client,
    dest: PathBuf
) -> Result<(), Error> {

    let handle = client
        .download_objects()
        .bucket("my-bucket")
        .walker(S3Walker::builder().prefix("photos/").build())
        .destination(dest)
        .initiate()?;

    // wait for transfer to complete
    handle.join().await?;

    Ok(())
}
Source

pub fn upload_objects(&self) -> UploadObjectsFluentBuilder

Upload multiple objects from a local directory to an Amazon S3 bucket

Constructs a fluent builder for the UploadObjects operation.

The default walk is not recursive: it uploads the regular files directly inside the source directory and skips subdirectories. To upload a directory tree, supply a walker built with FsWalker::builder().recursive(true), as in the example below.

Examples

use std::path::Path;
use aws_s3_transfer::error::Error;
use aws_s3_transfer::io::walk::FsWalker;

async fn upload_directory(
    client: &aws_s3_transfer::Client,
    source: &Path,
) -> Result<(), Error> {

    let handle = client
        .upload_objects()
        .source(source)
        .bucket("my-bucket")
        .walker(FsWalker::builder().recursive(true).build())
        .initiate()?;

    // wait for transfer to complete
    handle.join().await?;

    Ok(())
}

Trait Implementations§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Client

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Client

§

impl !UnwindSafe for Client

§

impl Forget for Client

§

impl Freeze for Client

§

impl Move for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl UnsafeUnpin for Client

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<Unshared, Shared> IntoShared<Shared> for Unshared
where Shared: FromUnshared<Unshared>,

Source§

fn into_shared(self) -> Shared

Creates a shared type from an unshared type.
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more