Type Alias FutureWrite

pub type FutureWrite<F> = OperatorFuture<(OpWrite, OpWriter, Buffer), Metadata, F>;

Future that generated by Operator::write_with.

Users can add more options by public functions provided by this struct.

Aliased Type

struct FutureWrite<F> { /* private fields */ }

Implementations

impl<F: Future<Output = Result<Metadata>>> FutureWrite<F>

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

Sets append mode for this write request.

Capability

Check Capability::write_can_append before using this feature.

Behavior

• By default, write operations overwrite existing files
• When append is set to true:
  • New data will be appended to the end of existing file
  • If file doesn’t exist, it will be created
• If not supported, will return an error

This operation allows adding data to existing files instead of overwriting them.

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.

Capability

Check Capability::write_multi_min_size and Capability::write_multi_max_size for size limits.

Behavior

• By default, OpenDAL sets optimal chunk size based on service capabilities
• When chunk size is set:
  • Data will be buffered until reaching chunk size
  • One API call will be made per chunk
  • Last chunk may be smaller than chunk size
• Important considerations:
  • Some services require minimum chunk sizes (e.g. S3’s EntityTooSmall error)
  • Smaller chunks increase API calls and costs
  • Larger chunks increase memory usage, but improve performance and reduce costs

Performance Impact

Setting appropriate chunk size can:

• Reduce number of API calls
• Improve overall throughput
• Lower operation costs
• Better utilize network bandwidth

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.

Behavior

• By default, OpenDAL writes files sequentially
• When concurrent is set:
  • Multiple write operations can execute in parallel
  • Write operations return immediately without waiting if tasks space are available
  • Close operation ensures all writes complete in order
  • Memory usage increases with concurrency level
• If not supported, falls back to sequential writes

This feature significantly improves performance when:

• Writing large files
• Network latency is high
• Storage service supports concurrent uploads like multipart uploads

Performance Impact

Setting appropriate concurrency can:

• Increase write throughput
• Reduce total write time
• Better utilize available bandwidth
• Trade memory for performance

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.

Capability

Check Capability::write_with_cache_control before using this feature.

Behavior

• If supported, sets Cache-Control as system metadata on the target file
• The value should follow HTTP Cache-Control header format
• If not supported, the value will be ignored

This operation allows controlling caching behavior for the written content.

Use Cases

• Setting browser cache duration
• Configuring CDN behavior
• Optimizing content delivery
• Managing cache invalidation

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?;

References

• MDN Cache-Control
• RFC 7234 Section 5.2

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

Sets Content-Type header for this write operation.

Capability

Check Capability::write_with_content_type before using this feature.

Behavior

• If supported, sets Content-Type as system metadata on the target file
• The value should follow MIME type format (e.g. “text/plain”, “image/jpeg”)
• If not supported, the value will be ignored

This operation allows specifying the media type of the content being written.

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

content_disposition

Sets Content-Disposition header for this write request.

Capability

Check Capability::write_with_content_disposition before using this feature.

Behavior

• If supported, sets Content-Disposition as system metadata on the target file
• The value should follow HTTP Content-Disposition header format
• Common values include:
  • inline - Content displayed within browser
  • attachment - Content downloaded as file
  • attachment; filename="example.jpg" - Downloaded with specified filename
• If not supported, the value will be ignored

This operation allows controlling how the content should be displayed or downloaded.

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.

Capability

Check Capability::write_with_content_encoding before using this feature.

Behavior

• If supported, sets Content-Encoding as system metadata on the target file
• The value should follow HTTP Content-Encoding header format
• Common values include:
  • gzip - Content encoded using gzip compression
  • deflate - Content encoded using deflate compression
  • br - Content encoded using Brotli compression
  • identity - No encoding applied (default value)
• If not supported, the value will be ignored

This operation allows specifying the encoding applied to the content being written.

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.

Capability

Check Capability::write_with_if_match before using this feature.

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 _ = 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.

Note: Certain services, like s3, support if_not_exists but not if_none_match. Use if_not_exists if you only want to check whether a file exists.

Capability

Check Capability::write_with_if_none_match before using this feature.

Behavior

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

This operation provides conditional write functionality based on ETag non-matching, useful for preventing overwriting existing resources or ensuring unique writes.

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.

Capability

Check Capability::write_with_if_not_exists before using this feature.

Behavior

• If supported, the write operation will only succeed if the target path does not exist
• Will return error if target already exists
• If not supported, the value will be ignored

This operation provides a way to ensure write operations only create new resources without overwriting existing ones, useful for implementing “create if not exists” logic.

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.

Capability

Check Capability::write_with_user_metadata before using this feature.

Behavior

• If supported, the user metadata will be attached to the object during write
• Accepts key-value pairs where both key and value are strings
• Keys are case-insensitive in most services
• Services may have limitations for user metadata, for example:
  • Key length is typically limited (e.g., 1024 bytes)
  • Value length is typically limited (e.g., 4096 bytes)
  • Total metadata size might be limited
  • Some characters might be forbidden in keys
• If not supported, the metadata will be ignored

User metadata provides a way to attach custom metadata to objects during write operations. This metadata can be retrieved later when reading the object.

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?;