Struct body_image::BodySink
source · pub struct BodySink { /* private fields */ }
Expand description
A logical buffer of bytes, which may or may not be RAM resident, in the
process of being written. This is the write-side corollary to
BodyImage
.
A BodySink
is always in one of the following states, as a buffering
strategy:
Ram
: A vector of zero, one, or many discontinuous (AKA scattered) byte
buffers in Random Access Memory. This state is also used to represent
an empty body (without allocation).
FsWrite
: Body being written to a (temporary) file.
Implementations§
source§impl BodySink
impl BodySink
sourcepub fn empty() -> BodySink
pub fn empty() -> BodySink
Create new empty instance, which does not pre-allocate. The state is
Ram
with a zero-capacity vector.
sourcepub fn with_ram(size_estimate: u64) -> BodySink
pub fn with_ram(size_estimate: u64) -> BodySink
Create a new Ram
instance by pre-allocating a vector of buffers
based on the given size estimate in bytes, assuming 8 KiB
buffers. With a size_estimate of 0, this is the same as empty
.
sourcepub fn with_ram_buffers(capacity: usize) -> BodySink
pub fn with_ram_buffers(capacity: usize) -> BodySink
Create a new Ram
instance by pre-allocating a vector of the
specified capacity.
sourcepub fn with_fs<P>(dir: P) -> Result<BodySink, BodyError>where
P: AsRef<Path>,
pub fn with_fs<P>(dir: P) -> Result<BodySink, BodyError>where
P: AsRef<Path>,
Create a new instance in state FsWrite
, using a new temporary file
created in dir.
sourcepub fn save<T>(&mut self, buf: T) -> Result<(), BodyError>where
T: Into<Bytes>,
pub fn save<T>(&mut self, buf: T) -> Result<(), BodyError>where
T: Into<Bytes>,
Save bytes by appending to Ram
or writing to FsWrite
file. When in
state Ram
this may be more efficient than write_all
if
Into<Bytes>
doesn’t copy.
sourcepub fn write_all<T>(&mut self, buf: T) -> Result<(), BodyError>where
T: AsRef<[u8]>,
pub fn write_all<T>(&mut self, buf: T) -> Result<(), BodyError>where
T: AsRef<[u8]>,
Write all bytes to self. When in state FsWrite
this is copy free
and more optimal than save
.
sourcepub fn write_back<P>(&mut self, dir: P) -> Result<&mut Self, BodyError>where
P: AsRef<Path>,
pub fn write_back<P>(&mut self, dir: P) -> Result<&mut Self, BodyError>where
P: AsRef<Path>,
If Ram
, convert to FsWrite
by writing all bytes in RAM to a
temporary file, created in dir. No-op if already FsWrite
. Buffers
are eagerly dropped as they are written. As a consequence, if any
error result is returned (e.g. opening or writing to the file), self
will be empty and in the Ram
state. There is no practical recovery
for the original body.