Struct opendal::Writer

pub struct Writer { /* private fields */ }

Writer is designed to write data into given path in an asynchronous manner.

Notes

Please make sure either close or abort has been called before dropping the writer otherwise the data could be lost.

Usage

Write Multiple Chunks

Some services support to write multiple chunks of data into given path. Services that doesn’t support write multiple chunks will return ErrorKind::Unsupported error when calling write at the second time.

let mut w = op.writer("path/to/file").await?;
w.write(bs).await?;
w.write(bs).await?;
w.close().await?

Our writer also provides Writer::sink and Writer::copy support.

Besides, our writer implements [AsyncWrite] and tokio::io::AsyncWrite.

Write with append enabled

Writer also supports to write with append enabled. This is useful when users want to append some data to the end of the file.

• If file doesn’t exist, it will be created and just like calling write.
• If file exists, data will be appended to the end of the file.

Possible Errors:

• Some services store normal file and appendable file in different way. Trying to append on non-appendable file could return ErrorKind::ConditionNotMatch error.
• Services that doesn’t support append will return ErrorKind::Unsupported error when creating writer with append enabled.

Implementations

impl Writer

pub async fn write(&mut self, bs: impl Into<Bytes>) -> Result<()>

Write into inner writer.

pub async fn sink<S, T>(&mut self, sink_from: S) -> Result<u64>

where S: Stream<Item = Result<T>>, T: Into<Bytes>,

Sink into writer.

sink will read data from given streamer and write them into writer directly without extra in-memory buffer.

Notes

• Sink doesn’t support to be used with write concurrently.
• Sink doesn’t support to be used without content length now.

Examples

use std::io::Result;

use bytes::Bytes;
use futures::stream;
use futures::StreamExt;
use opendal::Operator;

#[tokio::main]
async fn sink_example(op: Operator) -> Result<()> {
    let mut w = op.writer_with("path/to/file").await?;
    let stream = stream::iter(vec![vec![0; 4096], vec![1; 4096]]).map(Ok);
    w.sink(stream).await?;
    w.close().await?;
    Ok(())
}

pub async fn copy<R>(&mut self, read_from: R) -> Result<u64>

where R: AsyncRead,

Copy into writer.

copy will read data from given reader and write them into writer directly with only one constant in-memory buffer.

Notes

• Copy doesn’t support to be used with write concurrently.
• Copy doesn’t support to be used without content length now.

Examples

use std::io::Result;

use bytes::Bytes;
use futures::io::Cursor;
use futures::stream;
use futures::StreamExt;
use opendal::Operator;

#[tokio::main]
async fn copy_example(op: Operator) -> Result<()> {
    let mut w = op.writer_with("path/to/file").await?;
    let reader = Cursor::new(vec![0; 4096]);
    w.copy(reader).await?;
    w.close().await?;
    Ok(())
}

pub async fn abort(&mut self) -> Result<()>

Abort the writer and clean up all written data.

Notes

Abort should only be called when the writer is not closed or aborted, otherwise an unexpected error could be returned.

pub async fn close(&mut self) -> Result<()>

Close the writer and make sure all data have been committed.

Notes

Close should only be called when the writer is not closed or aborted, otherwise an unexpected error could be returned.

Trait Implementations

impl AsyncWrite for Writer

fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<()>>

Writer makes sure that every write is flushed.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl AsyncWrite for Writer

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.