Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor: add additional documentation about BufWriter #5519

Merged
merged 4 commits into from
Mar 16, 2024
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion object_store/src/buffered.rs
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is such an important feature I think it is worth calling out explicitly

/// [`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 multipart upload created by this
/// writer, if any.
pub fn multipart_id(&self) -> Option<&MultipartId> {
self.multipart_id.as_ref()
}
13 changes: 9 additions & 4 deletions object_store/src/lib.rs
Original file line number Diff line number Diff line change
@@ -88,19 +88,24 @@
//!
//! # 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
//! * Abstracts away filesystem and operating system specific quirks, ensuring portability
//! * Allows for functionality not native to filesystems, such as operation preconditions
//! and atomic multipart uploads
//!
//! This crate does provide a [`BufReader`] and [`BufWriter`] adapters
alamb marked this conversation as resolved.
Show resolved Hide resolved
//! which provide a more filesystem-like API for working with the
//! [`ObjectStore`] trait.
alamb marked this conversation as resolved.
Show resolved Hide resolved
//!
//! [`BufReader`]: buffered::BufReader
//! [`BufWriter`]: buffered::BufWriter
//!
//! # Adapters
//!