From fcb3d264c60495eba9586e4c905add6529472569 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 15 Mar 2024 09:33:42 -0400 Subject: [PATCH 1/4] Minor: add additional documentation about BufWriter --- object_store/src/buffered.rs | 7 ++++++- object_store/src/lib.rs | 13 +++++++++---- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/object_store/src/buffered.rs b/object_store/src/buffered.rs index fdefe599f79e..1c66c8aae262 100644 --- a/object_store/src/buffered.rs +++ b/object_store/src/buffered.rs @@ -207,6 +207,10 @@ impl AsyncBufRead for BufReader { /// An async buffered writer compatible with the tokio IO traits /// +/// This writer adaptively uses [`ObjectStore::put`] or +/// [`ObjectStore::put_multipart`] depending on the amount of data that has +/// been written. +/// /// Up to `capacity` bytes will be buffered in memory, and flushed on shutdown /// using [`ObjectStore::put`]. If `capacity` is exceeded, data will instead be /// streamed using [`ObjectStore::put_multipart`] @@ -255,7 +259,8 @@ impl BufWriter { } } - /// Returns the [`MultipartId`] if multipart upload + /// Returns the [`MultipartId`] of the last multipart upload created by this + /// writer, if any. pub fn multipart_id(&self) -> Option<&MultipartId> { self.multipart_id.as_ref() } diff --git a/object_store/src/lib.rs b/object_store/src/lib.rs index 8132002b6e01..09c6ba33f3de 100644 --- a/object_store/src/lib.rs +++ b/object_store/src/lib.rs @@ -88,11 +88,11 @@ //! //! # Why not a Filesystem Interface? //! -//! Whilst this crate does provide a [`BufReader`], the [`ObjectStore`] interface mirrors the APIs -//! of object stores and not filesystems, opting to provide stateless APIs instead of the cursor -//! based interfaces such as [`Read`] or [`Seek`] favoured by filesystems. +//! The [`ObjectStore`] interface is designed to mirror the APIs +//! of object stores and *not* filesystems, and thus has stateless APIs instead +//! of cursor based interfaces such as [`Read`] or [`Seek`] available in filesystems. //! -//! This provides some compelling advantages: +//! This design provides the following advantages: //! //! * All operations are atomic, and readers cannot observe partial and/or failed writes //! * Methods map directly to object store APIs, providing both efficiency and predictability @@ -100,7 +100,12 @@ //! * Allows for functionality not native to filesystems, such as operation preconditions //! and atomic multipart uploads //! +//! This crate does provide a [`BufReader`] and [`BufWriter`] adapters +//! which provide a more filesystem-like API for working with the +//! [`ObjectStore`] trait. +//! //! [`BufReader`]: buffered::BufReader +//! [`BufWriter`]: buffered::BufWriter //! //! # Adapters //! From 503531ea7498d632221ae8b2c6c16fdb662cb718 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 15 Mar 2024 09:39:37 -0400 Subject: [PATCH 2/4] Update object_store/src/buffered.rs --- object_store/src/buffered.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/object_store/src/buffered.rs b/object_store/src/buffered.rs index 1c66c8aae262..9299e1147bc1 100644 --- a/object_store/src/buffered.rs +++ b/object_store/src/buffered.rs @@ -259,7 +259,7 @@ impl BufWriter { } } - /// Returns the [`MultipartId`] of the last multipart upload created by this + /// Returns the [`MultipartId`] of the multipart upload created by this /// writer, if any. pub fn multipart_id(&self) -> Option<&MultipartId> { self.multipart_id.as_ref() From 4bd278eb71c28829039f736358ebc125ab456879 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 15 Mar 2024 16:38:57 -0400 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com> --- object_store/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/object_store/src/lib.rs b/object_store/src/lib.rs index 09c6ba33f3de..86bd45f4ef9a 100644 --- a/object_store/src/lib.rs +++ b/object_store/src/lib.rs @@ -100,9 +100,9 @@ //! * Allows for functionality not native to filesystems, such as operation preconditions //! and atomic multipart uploads //! -//! This crate does provide a [`BufReader`] and [`BufWriter`] adapters +//! This crate does provide [`BufReader`] and [`BufWriter`] adapters //! which provide a more filesystem-like API for working with the -//! [`ObjectStore`] trait. +//! [`ObjectStore`] trait, however, they should be used with care //! //! [`BufReader`]: buffered::BufReader //! [`BufWriter`]: buffered::BufWriter From f55b05044b823a2d0147eadc48feeead9c5c0092 Mon Sep 17 00:00:00 2001 From: Raphael Taylor-Davies Date: Sun, 17 Mar 2024 11:16:32 +1300 Subject: [PATCH 4/4] Format --- object_store/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/object_store/src/lib.rs b/object_store/src/lib.rs index 86bd45f4ef9a..4960f3ba390a 100644 --- a/object_store/src/lib.rs +++ b/object_store/src/lib.rs @@ -102,7 +102,7 @@ //! //! This crate does provide [`BufReader`] and [`BufWriter`] adapters //! which provide a more filesystem-like API for working with the -//! [`ObjectStore`] trait, however, they should be used with care +//! [`ObjectStore`] trait, however, they should be used with care //! //! [`BufReader`]: buffered::BufReader //! [`BufWriter`]: buffered::BufWriter