pub struct BytesPool { /* private fields */ }Expand description
A pool for creating byte-slices and strings that can be cheaply cloned and shared across threads
without allocating memory. Byte-slices are shared as Bytes, and strings are shared as
ByteStrings.
Internally, a BytesPool is a wrapper around a BytesMut buffer from the bytes crate.
It shares data by appending the data to its buffer and then splitting the buffer off with
BytesMut::split. This only allocates memory if the buffer needs to resize.
Implementations§
Source§impl BytesPool
impl BytesPool
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new BytesPool with default capacity.
Resulting object has unspecified capacity. This function does not allocate.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::new();Sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Creates a new BytesPool with the specified capacity.
The returned BytesPool will be able to hold at least capacity bytes
without reallocating.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::with_capacity(64);Sourcepub fn capacity(&self) -> usize
pub fn capacity(&self) -> usize
Returns the number of bytes the BytesPool can hold without reallocating.
§Examples
use bytes_pool::BytesPool;
let b = BytesPool::with_capacity(64);
assert_eq!(b.capacity(), 64);Creates an immutable slice of bytes that can be shared across threads and cheaply cloned.
No allocation is performed unless the internal buffer needs to be resized to accomodate the additional bytes.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::with_capacity(64);
let bytes = pool.share_bytes(b"hello world");
assert_eq!(bytes, &b"hello world"[..]);Creates an immutable string that can be shared across threads and cheaply cloned.
No allocation is performed unless the internal buffer needs to be resized to accomodate the additional bytes.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::with_capacity(64);
let s = pool.share_str("hello world");
assert_eq!(s, "hello world");Sourcepub fn reserve(&mut self, additional: usize)
pub fn reserve(&mut self, additional: usize)
Reserves capacity for at least additional bytes to be inserted
into the given BytesPool.
More than additional bytes may be reserved in order to avoid frequent
reallocations. A call to reserve may result in an allocation.
This function performs the same optimizations as BytesMut::reserve.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::with_capacity(128);
let bytes = pool.share_bytes(&[0; 64][..]);
assert_eq!(pool.capacity(), 64);
pool.reserve(128);
assert_eq!(pool.capacity(), 128);§Panics
Panics if the new capacity overflows usize.
Sourcepub fn try_reclaim(&mut self, additional: usize) -> bool
pub fn try_reclaim(&mut self, additional: usize) -> bool
Attempts to cheaply reclaim already allocated capacity for at least additional more
bytes to be inserted into the given BytesPool and returns true if it succeeded.
try_reclaim behaves exactly like reserve, except that it never
allocates new storage and returns a bool indicating whether it was successful in doing
so:
try_reclaim returns false under these conditions:
- The spare capacity left is less than
additionalbytes AND - The existing allocation cannot be reclaimed cheaply or it was less than
additionalbytes in size
Reclaiming the allocation cheaply is possible if the BytesPool has no outstanding
references through Bytes or ByteStrings which point to its underlying storage.
§Examples
use bytes_pool::BytesPool;
let mut pool = BytesPool::with_capacity(64);
assert_eq!(true, pool.try_reclaim(64));
assert_eq!(64, pool.capacity());
let mut bytes = pool.share_bytes(b"abcd");
assert_eq!(60, pool.capacity());
assert_eq!(false, pool.try_reclaim(64));
// pool has capacity for 60 bytes
assert_eq!(true, pool.try_reclaim(60));
drop(bytes);
assert_eq!(true, pool.try_reclaim(64));