Struct netbuf::Buf
[−]
[src]
pub struct Buf { /* fields omitted */ }
A buffer object to be used for reading from network
Assumptions:
-
Buffer needs to be growable as sometimes requests are large
-
Buffer should deallocate when empty as most of the time connections are idle
a. Deallocations are cheap as we have a cool memory allocator (jemalloc)
b. First allocation should be big (i.e. kilobytes not few bytes)
-
Should be easy to peek and get a slice as it makes packet parsing easy
-
Cheap removing bytes at the start of the buf
Methods
impl Buf
[src]
ⓘImportant traits for Bufpub fn new() -> Buf
[src]
Create empty buffer. It has no preallocated size. The underlying memory chunk is always deallocated when there are no useful bytes in the buffer.
pub fn consume(&mut self, bytes: usize)
[src]
Mark the first bytes
of the buffer as read. Basically it's shaving
off bytes from the buffer, but does it efficiently. When there are
no more bytes in the buffer it's deallocated.
Note: Buffer currently doesn't shrink when calling this method. It's assumed that all bytes will be consumed shortly. In case you're appending to the buffer after consume, old data is discarded.
Panics
Panics if bytes
is larger than current length of buffer
pub fn remove_range<R: Into<RangeArgument>>(&mut self, range: R)
[src]
Allows removing an arbitrary range of bytes
A more comprehensive version of consume()
. It's occasionally useful
if your data is in frames/chunks but you want to buffer the whole body
anyway. E.g. in http chunked encoding you have each chunk prefixed by
its length, but that doesn't mean you can't buffer the whole request
into memory. This method allows you to continue reading the next chunk
into the same buffer while removing the chunk length.
Note: it's not super efficient, as it requires to move (copy) bytes after the range, in case range is neither at the start nor at the end of buffer. Still it should be faster than copying everything to yet another buffer.
We never shrink the buffer here (except when it becomes empty, to keep this invariant), assuming that you will receive more data into the buffer shortly.
The RangeArgument
type is a temporary type until rust provides
the one in standard library, you should use the range syntax directly:
buf.remove_range(5..7)
Panics
Panics if range is invalid for the buffer
pub fn capacity(&self) -> usize
[src]
Capacity of the buffer. I.e. the bytes it is allocated for. Use for
debugging or for calculating memory usage. Note it's not guaranteed
that you can write buf.capacity() - buf.len()
bytes without resize
pub fn len(&self) -> usize
[src]
Number of useful bytes in the buffer
pub fn is_empty(&self) -> bool
[src]
If buffer is empty. Potentially a little bit faster than
getting len()
pub fn extend(&mut self, buf: &[u8])
[src]
Extend buffer. Note unlike Write::write()
and read_from()
this
method reserves as small as possible a chunk of memory. So it's
inefficien to grow with this method. You may use the Write trait to
grow incrementally.
pub fn read_from<R: Read>(&mut self, stream: &mut R) -> Result<usize>
[src]
Read some bytes from stream (object implementing Read
) into buffer
Note this does not continue to read until getting WouldBlock
. It
passes all errors as is. It preallocates some chunk to read into
buffer. It may be possible that the stream still has bytes buffered
after this method returns. This method is expected either to be called
until WouldBlock
is returned or is used with level-triggered polling.
pub fn read_max_from<R: Read>(
&mut self,
max: usize,
stream: &mut R
) -> Result<bool>
[src]
&mut self,
max: usize,
stream: &mut R
) -> Result<bool>
Reads no more than max bytes into buffer and returns boolean flag of whether max bytes are reached
Except for the limit on number of bytes and slightly different allocation strategy, this method has the same considerations as read_from
Note this method might be used for two purposes:
- Limit number of bytes buffered until parser can process data
(for example HTTP header size, which is number of bytes read before
\r\n\r\n
delimiter reached) - Wait until exact number of bytes are fully received
Since we support (1) we don't preallocate buffer for exact size of
the max
value. It also helps a little in case (2) for minimizing
DDoS attack vector. If that doesn't suit you, you may wish to use
Vec::with_capacity()
for the purpose of (2).
On the contrary we don't overallocate more than max
bytes, so if
you expect data to go after exact number of bytes read, it might be
better to use read_from()
and check buffer length.
pub fn write_to<W: Write>(&mut self, sock: &mut W) -> Result<usize>
[src]
Write contents of buffer to the stream (object implementing
the Write trait). We assume that stream is non-blocking, use
Write::write
(instead of Write::write_all
) and return all errors
to the caller (including WouldBlock
or Interrupted
).
In addition to returning the number of bytes written, it also
consume()
s those bytes from the buffer, so it's safe to retry calling
the method at any moment. Also it's a common pattern to append more
data to the buffer between calls.
ⓘImportant traits for Bufpub fn split_off(&mut self, at: usize) -> Buf
[src]
Splits buffer into two at the given index.
self
contains bytes [0, at)
and the returned Buf
contains
bytes [at, len)
.
Reallocates smaller part of buffer.
Panics
Panics if at > len.
Examples
let mut buf = netbuf::Buf::new(); buf.extend(b"Hello World!"); let tail = buf.split_off(6); assert_eq!(&buf[..], b"Hello "); assert_eq!(&tail[..], b"World!");
pub fn get(&self, index: usize) -> Option<u8>
[src]
Returns the byte at the index, or None
if the index is
out of bounds.
pub fn get_mut(&mut self, index: usize) -> Option<&mut u8>
[src]
Returns a mutable reference to the byte at the index, or
None
if the index is out of bounds.
Trait Implementations
impl Debug for Buf
[src]
fn fmt(&self, f: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl AsRef<[u8]> for Buf
[src]
impl Into<Vec<u8>> for Buf
[src]
impl Index<usize> for Buf
[src]
type Output = u8
The returned type after indexing.
fn index<'x>(&'x self, index: usize) -> &'x u8
[src]
Performs the indexing (container[index]
) operation.
impl Index<RangeFull> for Buf
[src]
type Output = [u8]
The returned type after indexing.
fn index<'x>(&'x self, _idx: RangeFull) -> &'x [u8]
[src]
Performs the indexing (container[index]
) operation.
impl Index<RangeTo<usize>> for Buf
[src]
type Output = [u8]
The returned type after indexing.
fn index<'x>(&'x self, slice: RangeTo<usize>) -> &'x [u8]
[src]
Performs the indexing (container[index]
) operation.
impl Index<RangeFrom<usize>> for Buf
[src]
type Output = [u8]
The returned type after indexing.
fn index<'x>(&'x self, slice: RangeFrom<usize>) -> &'x [u8]
[src]
Performs the indexing (container[index]
) operation.
impl Index<Range<usize>> for Buf
[src]
type Output = [u8]
The returned type after indexing.
fn index<'x>(&'x self, slice: Range<usize>) -> &'x [u8]
[src]
Performs the indexing (container[index]
) operation.
impl IndexMut<usize> for Buf
[src]
fn index_mut<'x>(&'x mut self, index: usize) -> &'x mut u8
[src]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeFull> for Buf
[src]
fn index_mut<'x>(&'x mut self, _idx: RangeFull) -> &'x mut [u8]
[src]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeTo<usize>> for Buf
[src]
fn index_mut<'x>(&'x mut self, slice: RangeTo<usize>) -> &'x mut [u8]
[src]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeFrom<usize>> for Buf
[src]
fn index_mut<'x>(&'x mut self, slice: RangeFrom<usize>) -> &'x mut [u8]
[src]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<Range<usize>> for Buf
[src]
fn index_mut<'x>(&'x mut self, slice: Range<usize>) -> &'x mut [u8]
[src]
Performs the mutable indexing (container[index]
) operation.
impl Write for Buf
[src]
fn write(&mut self, buf: &[u8]) -> Result<usize>
[src]
Write a buffer into this object, returning how many bytes were written. Read more
fn flush(&mut self) -> Result<()>
[src]
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
1.0.0[src]
Attempts to write an entire buffer into this write. Read more
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0[src]
Writes a formatted string into this writer, returning any error encountered. Read more
fn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Write
. Read more