Struct OperatorFuture

pub struct OperatorFuture<I, O, F: Future<Output = Result<O>>> { /* private fields */ }

OperatorFuture is the future generated by Operator.

The future will consume all the input to generate a future.

NOTES

This struct is by design to keep in crate. We don’t want users to use this struct directly.

Implementations

impl<F: Future<Output = Result<Metadata>>> OperatorFuture<StatOptions, Metadata, F>

pub fn if_match(self, v: &str) -> Self

Set the If-Match for this operation.

Refer to options::StatOptions::if_match for more details.

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match for this operation.

Refer to options::StatOptions::if_none_match for more details.

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

Set the If-Modified-Since for this operation.

Refer to options::StatOptions::if_modified_since for more details.

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set the If-Unmodified-Since for this operation.

Refer to options::StatOptions::if_unmodified_since for more details.

pub fn version(self, v: &str) -> Self

Set the version for this operation.

Refer to options::StatOptions::version for more details.

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpStat, Duration), PresignedRequest, F>

pub fn override_content_disposition(self, v: &str) -> Self

Sets the content-disposition header that should be sent back by the remote read operation.

pub fn override_cache_control(self, v: &str) -> Self

Sets the cache-control header that should be sent back by the remote read operation.

pub fn override_content_type(self, v: &str) -> Self

Sets the content-type header that should be sent back by the remote read operation.

pub fn if_match(self, v: &str) -> Self

Set the If-Match of the option

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match of the option

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpRead, Duration), PresignedRequest, F>

pub fn override_content_disposition(self, v: &str) -> Self

Sets the content-disposition header that should be sent back by the remote read operation.

pub fn override_cache_control(self, v: &str) -> Self

Sets the cache-control header that should be sent back by the remote read operation.

pub fn override_content_type(self, v: &str) -> Self

Sets the content-type header that should be sent back by the remote read operation.

pub fn if_match(self, v: &str) -> Self

Set the If-Match of the option

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match of the option

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpWrite, Duration), PresignedRequest, F>

pub fn content_type(self, v: &str) -> Self

Set the content type of option

pub fn content_disposition(self, v: &str) -> Self

Set the content disposition of option

pub fn content_encoding(self, v: &str) -> Self

Set the content encoding of the operation

pub fn cache_control(self, v: &str) -> Self

Set the content type of option

impl<F: Future<Output = Result<Buffer>>> OperatorFuture<ReadOptions, Buffer, F>

pub fn range(self, range: impl RangeBounds<u64>) -> Self

Set range for this read request.

If we have a file with size n.

• .. means read bytes in range [0, n) of file.
• 0..1024 and ..1024 means read bytes in range [0, 1024) of file
• 1024.. means read bytes in range [1024, n) of file

let bs = op.read_with("path/to/file").range(0..1024).await?;

pub fn concurrent(self, concurrent: usize) -> Self

Set concurrent for the reader.

OpenDAL by default to write file without concurrent. This is not efficient for cases when users read large chunks of data. By setting concurrent, opendal will read files concurrently on support storage services.

By setting concurrent, opendal will fetch chunks concurrently with the given chunk size.

let r = op.read_with("path/to/file").concurrent(8).await?;

pub fn chunk(self, chunk_size: usize) -> Self

OpenDAL will use services’ preferred chunk size by default. Users can set chunk based on their own needs.

This following example will make opendal read data in 4MiB chunks:

let r = op.read_with("path/to/file").chunk(4 * 1024 * 1024).await?;

pub fn version(self, v: &str) -> Self

Set version for this read request.

This feature can be used to retrieve the data of a specified version of the given path.

If the version doesn’t exist, an error with kind ErrorKind::NotFound will be returned.

let mut bs = op.read_with("path/to/file").version(version).await?;

pub fn if_match(self, v: &str) -> Self

Set if_match for this read request.

This feature can be used to check if the file’s ETag matches the given ETag.

If file exists and it’s etag doesn’t match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut metadata = op.read_with("path/to/file").if_match(etag).await?;

pub fn if_none_match(self, v: &str) -> Self

Set if_none_match for this read request.

This feature can be used to check if the file’s ETag doesn’t match the given ETag.

If file exists and it’s etag match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut metadata = op.read_with("path/to/file").if_none_match(etag).await?;

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

if_modified_since

Set if_modified_since for this read request.

This feature can be used to check if the file has been modified since the given timestamp.

If file exists and it hasn’t been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut metadata = op.read_with("path/to/file").if_modified_since(time).await?;

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set if_unmodified_since for this read request.

This feature can be used to check if the file hasn’t been modified since the given timestamp.

If file exists and it has been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut metadata = op.read_with("path/to/file").if_unmodified_since(time).await?;

impl<F: Future<Output = Result<Reader>>> OperatorFuture<ReaderOptions, Reader, F>

pub fn version(self, v: &str) -> Self

Set version for this reader.

This feature can be used to retrieve the data of a specified version of the given path.

If the version doesn’t exist, an error with kind ErrorKind::NotFound will be returned.

let mut r = op.reader_with("path/to/file").version(version).await?;

pub fn concurrent(self, concurrent: usize) -> Self

Set concurrent for the reader.

OpenDAL by default to write file without concurrent. This is not efficient for cases when users read large chunks of data. By setting concurrent, opendal will reading files concurrently on support storage services.

By setting concurrent, opendal will fetch chunks concurrently with the give chunk size.

let r = op.reader_with("path/to/file").concurrent(8).await?;

pub fn chunk(self, chunk_size: usize) -> Self

OpenDAL will use services’ preferred chunk size by default. Users can set chunk based on their own needs.

This following example will make opendal read data in 4MiB chunks:

let r = op
    .reader_with("path/to/file")
    .chunk(4 * 1024 * 1024)
    .await?;

pub fn gap(self, gap_size: usize) -> Self

Controls the optimization strategy for range reads in Reader::fetch.

When performing range reads, if the gap between two requested ranges is smaller than the configured gap size, OpenDAL will merge these ranges into a single read request and discard the unrequested data in between. This helps reduce the number of API calls to remote storage services.

This optimization is particularly useful when performing multiple small range reads that are close to each other, as it reduces the overhead of multiple network requests at the cost of transferring some additional data.

In this example, if two requested ranges are separated by less than 1MiB, they will be merged into a single read request:

let r = op
    .reader_with("path/to/file")
    .chunk(4 * 1024 * 1024)
    .gap(1024 * 1024)  // 1MiB gap
    .await?;

pub fn if_match(self, etag: &str) -> Self

Set if-match for this read request.

This feature can be used to check if the file’s ETag matches the given ETag.

If file exists and it’s etag doesn’t match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut r = op.reader_with("path/to/file").if_match(etag).await?;

pub fn if_none_match(self, etag: &str) -> Self

Set if-none-match for this read request.

This feature can be used to check if the file’s ETag doesn’t match the given ETag.

If file exists and it’s etag match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut r = op.reader_with("path/to/file").if_none_match(etag).await?;

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

Set if-modified-since for this read request.

This feature can be used to check if the file has been modified since the given timestamp.

If file exists and it hasn’t been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut r = op.reader_with("path/to/file").if_modified_since(time).await?;

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set if-unmodified-since for this read request.

This feature can be used to check if the file hasn’t been modified since the given timestamp.

If file exists and it has been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut r = op.reader_with("path/to/file").if_unmodified_since(time).await?;

impl<F: Future<Output = Result<Metadata>>> OperatorFuture<(WriteOptions, Buffer), Metadata, F>

pub fn append(self, v: bool) -> Self

Sets append mode for this write request.

Refer to options::WriteOptions::append for more details.

Example

use bytes::Bytes;

let _ = op.write_with("path/to/file", vec![0; 4096]).append(true).await?;

pub fn chunk(self, v: usize) -> Self

Sets chunk size for buffered writes.

Refer to options::WriteOptions::chunk for more details.

Example

use bytes::Bytes;

// Set 8MiB chunk size - data will be sent in one API call at close
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .chunk(8 * 1024 * 1024)
    .await?;

pub fn concurrent(self, v: usize) -> Self

Sets concurrent write operations for this writer.

Refer to options::WriteOptions::concurrent for more details.

Example

use bytes::Bytes;

// Enable concurrent writes with 8 parallel operations at 128B chunk.
let _ = op.write_with("path/to/file", vec![0; 4096]).chunk(128).concurrent(8).await?;

pub fn cache_control(self, v: &str) -> Self

Sets Cache-Control header for this write operation.

Refer to options::WriteOptions::cache_control for more details.

Example

use bytes::Bytes;

// Cache content for 7 days (604800 seconds)
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .cache_control("max-age=604800")
    .await?;

pub fn content_type(self, v: &str) -> Self

Sets Content-Type header for this write operation.

Refer to options::WriteOptions::content_type for more details.

Example

use bytes::Bytes;

// Set content type for plain text file
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_type("text/plain")
    .await?;

pub fn content_disposition(self, v: &str) -> Self

Sets Content-Disposition header for this write request.

Refer to options::WriteOptions::content_disposition for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_disposition("attachment; filename=\"filename.jpg\"")
    .await?;

pub fn content_encoding(self, v: &str) -> Self

Sets Content-Encoding header for this write request.

Refer to options::WriteOptions::content_encoding for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_encoding("gzip")
    .await?;

pub fn if_match(self, s: &str) -> Self

Sets If-Match header for this write request.

Refer to options::WriteOptions::if_match for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_match("\"686897696a7c876b7e\"")
    .await?;

pub fn if_none_match(self, s: &str) -> Self

Sets If-None-Match header for this write request.

Refer to options::WriteOptions::if_none_match for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_none_match("\"686897696a7c876b7e\"")
    .await?;

pub fn if_not_exists(self, b: bool) -> Self

Sets the condition that write operation will succeed only if target does not exist.

Refer to options::WriteOptions::if_not_exists for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_not_exists(true)
    .await?;

pub fn user_metadata( self, data: impl IntoIterator<Item = (String, String)>, ) -> Self

Sets user metadata for this write request.

Refer to options::WriteOptions::user_metadata for more details.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .user_metadata([
        ("language".to_string(), "rust".to_string()),
        ("author".to_string(), "OpenDAL".to_string()),
    ])
    .await?;

impl<F: Future<Output = Result<Writer>>> OperatorFuture<WriteOptions, Writer, F>

pub fn append(self, v: bool) -> Self

Sets append mode for this write request.

Refer to options::WriteOptions::append for more details.

Example

use bytes::Bytes;

let mut w = op.writer_with("path/to/file").append(true).await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn chunk(self, v: usize) -> Self

Sets chunk size for buffered writes.

Refer to options::WriteOptions::chunk for more details.

Example

use bytes::Bytes;

// Set 8MiB chunk size - data will be sent in one API call at close
let mut w = op
    .writer_with("path/to/file")
    .chunk(8 * 1024 * 1024)
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn concurrent(self, v: usize) -> Self

Sets concurrent write operations for this writer.

Refer to options::WriteOptions::concurrent for more details.

Example

use bytes::Bytes;

// Enable concurrent writes with 8 parallel operations
let mut w = op.writer_with("path/to/file").concurrent(8).await?;

// First write starts immediately
w.write(vec![0; 4096]).await?;

// Second write runs concurrently with first
w.write(vec![1; 4096]).await?;

// Ensures all writes complete successfully and in order
w.close().await?;

pub fn cache_control(self, v: &str) -> Self

Sets Cache-Control header for this write operation.

Refer to options::WriteOptions::cache_control for more details.

Example

use bytes::Bytes;

// Cache content for 7 days (604800 seconds)
let mut w = op
    .writer_with("path/to/file")
    .cache_control("max-age=604800")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn content_type(self, v: &str) -> Self

Sets Content-Type header for this write operation.

Refer to options::WriteOptions::content_type for more details.

Example

use bytes::Bytes;

// Set content type for plain text file
let mut w = op
    .writer_with("path/to/file")
    .content_type("text/plain")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn content_disposition(self, v: &str) -> Self

Sets Content-Disposition header for this write request.

Refer to options::WriteOptions::content_disposition for more details.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .content_disposition("attachment; filename=\"filename.jpg\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn content_encoding(self, v: &str) -> Self

Sets Content-Encoding header for this write request.

Refer to options::WriteOptions::content_encoding for more details.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .content_encoding("gzip")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_match(self, s: &str) -> Self

Sets If-Match header for this write request.

Refer to options::WriteOptions::if_match for more details.

Behavior

• If supported, the write operation will only succeed if the target’s ETag matches the specified value
• The value should be a valid ETag string
• Common values include:
  • A specific ETag value like "686897696a7c876b7e"
  • * - Matches any existing resource
• If not supported, the value will be ignored

This operation provides conditional write functionality based on ETag matching, helping prevent unintended overwrites in concurrent scenarios.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_match("\"686897696a7c876b7e\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_none_match(self, s: &str) -> Self

Sets If-None-Match header for this write request.

Refer to options::WriteOptions::if_none_match for more details.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_none_match("\"686897696a7c876b7e\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_not_exists(self, b: bool) -> Self

Sets the condition that write operation will succeed only if target does not exist.

Refer to options::WriteOptions::if_not_exists for more details.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_not_exists(true)
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn user_metadata( self, data: impl IntoIterator<Item = (String, String)>, ) -> Self

Sets user metadata for this write request.

Refer to options::WriteOptions::user_metadata for more details.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .user_metadata([
        ("content-type".to_string(), "text/plain".to_string()),
        ("author".to_string(), "OpenDAL".to_string()),
    ])
    .await?;
w.write(vec![0; 4096]).await?;
w.close().await?;

impl<F: Future<Output = Result<()>>> OperatorFuture<DeleteOptions, (), F>

pub fn version(self, v: &str) -> Self

Change the version of this delete operation.

impl<F: Future<Output = Result<Vec<Entry>>>> OperatorFuture<ListOptions, Vec<Entry>, F>

pub fn limit(self, v: usize) -> Self

The limit passed to underlying service to specify the max results that could return per-request.

Users could use this to control the memory usage of list operation.

pub fn start_after(self, v: &str) -> Self

The start_after passes to underlying service to specify the specified key to start listing from.

pub fn recursive(self, v: bool) -> Self

The recursive is used to control whether the list operation is recursive.

• If false, list operation will only list the entries under the given path.
• If true, list operation will list all entries that starts with given path.

Default to false.

pub fn versions(self, v: bool) -> Self

Controls whether the list operation should return file versions.

This function allows you to specify if the list operation, when executed, should include information about different versions of files, if versioning is supported and enabled.

If true, subsequent list operations will include version information for each file. If false, version information will be omitted from the list results.

Default to false

pub fn deleted(self, v: bool) -> Self

Controls whether the list operation should include deleted files (or versions).

This function allows you to specify if the list operation, when executed, should include entries for files or versions that have been marked as deleted. This is particularly relevant in object storage systems that support soft deletion or versioning.

If true, subsequent list operations will include deleted files or versions. If false, deleted files or versions will be excluded from the list results.

impl<F: Future<Output = Result<Lister>>> OperatorFuture<ListOptions, Lister, F>

pub fn limit(self, v: usize) -> Self

The limit passed to underlying service to specify the max results that could return per-request.

Users could use this to control the memory usage of list operation.

pub fn start_after(self, v: &str) -> Self

The start_after passes to underlying service to specify the specified key to start listing from.

pub fn recursive(self, v: bool) -> Self

The recursive is used to control whether the list operation is recursive.

• If false, list operation will only list the entries under the given path.
• If true, list operation will list all entries that starts with given path.

Default to false.

pub fn versions(self, v: bool) -> Self

Controls whether the list operation should return file versions.

This function allows you to specify if the list operation, when executed, should include information about different versions of files, if versioning is supported and enabled.

If true, subsequent list operations will include version information for each file. If false, version information will be omitted from the list results.

Default to false

pub fn deleted(self, v: bool) -> Self

Controls whether the list operation should include deleted files (or versions).

This function allows you to specify if the list operation, when executed, should include entries for files or versions that have been marked as deleted. This is particularly relevant in object storage systems that support soft deletion or versioning.

If true, subsequent list operations will include deleted files or versions. If false, deleted files or versions will be excluded from the list results.

Trait Implementations

impl<I, O, F> IntoFuture for OperatorFuture<I, O, F>

where F: Future<Output = Result<O>>,

type Output = Result<O, Error>

The output that the future will produce on completion.

type IntoFuture = F

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.