This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch write_can_multig in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit d33dda723e405875f1fc218d98eef04a6fdf70bd Author: Xuanwo <[email protected]> AuthorDate: Wed Sep 13 08:51:14 2023 +0800 Add comments Signed-off-by: Xuanwo <[email protected]> --- core/src/types/operator/operator_futures.rs | 2 +- core/src/types/writer.rs | 39 +++++++++++++++++++++-------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/core/src/types/operator/operator_futures.rs b/core/src/types/operator/operator_futures.rs index 74c7eb159..63c013f05 100644 --- a/core/src/types/operator/operator_futures.rs +++ b/core/src/types/operator/operator_futures.rs @@ -440,7 +440,7 @@ impl FutureWriter { /// /// If the append mode is set, the data will be appended to the end of the file. /// - /// # Notes + /// ## Notes /// /// Service could return `Unsupported` if the underlying storage does not support append. pub fn append(mut self, v: bool) -> Self { diff --git a/core/src/types/writer.rs b/core/src/types/writer.rs index 5cfedca47..b350f9625 100644 --- a/core/src/types/writer.rs +++ b/core/src/types/writer.rs @@ -38,20 +38,39 @@ use crate::*; /// Please make sure either `close` or `abort` has been called before /// dropping the writer otherwise the data could be lost. /// -/// ## Notes +/// ## 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. +/// +/// ```no_build +/// 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 can be used in two ways: +/// Writer also supports to write with append enabled. This is useful when users want to append +/// some data to the end of the file. /// -/// - Sized: write data with a known size by specify the content length. -/// - Unsized: write data with an unknown size, also known as streaming. +/// - 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. /// -/// All services will support `sized` writer and provide special optimization if -/// the given data size is the same as the content length, allowing them to -/// be written in one request. +/// Possible Errors: /// -/// Some services also supports `unsized` writer. They MAY buffer part of the data -/// and flush them into storage at needs. And finally, the file will be available -/// after `close` has been called. +/// - 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. pub struct Writer { inner: oio::Writer, }
