Struct PooledBuffer 

pub struct PooledBuffer { /* private fields */ }

A buffer borrowed from a BufferPool.

On drop the buffer is burned (all bytes securely zeroed, positions reset) and then returned to the pool if space permits — otherwise it is securely dropped.

Use leak or drop_now to opt out of automatic return.

Implementations

impl PooledBuffer

pub fn leak(self) -> Buffer

Extracts the buffer from the pool wrapper without returning it.

The caller is responsible for cleanup; the buffer will still be zeroed when eventually dropped via #[zeroize(drop)].

pub fn drop_now(self)

Immediately and securely drops the buffer, bypassing pool return.

pub fn capacity(&self) -> usize

Capacity of the underlying buffer.

Methods from Deref<Target = Buffer>

pub fn capacity(&self) -> usize

Returns the total capacity of the buffer.

Examples

use secbuf::Buffer;

let buf = Buffer::new(1024);
assert_eq!(buf.capacity(), 1024);

pub fn len(&self) -> usize

Returns the length of valid data in the buffer.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
assert_eq!(buf.len(), 0);

buf.put_u32(42)?;
assert_eq!(buf.len(), 4);

pub fn is_empty(&self) -> bool

Returns true if the buffer contains no valid data.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
assert!(buf.is_empty());

buf.put_u32(42)?;
assert!(!buf.is_empty());

pub fn pos(&self) -> usize

Returns the current read/write position.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
assert_eq!(buf.pos(), 0);

buf.put_u32(42)?;
assert_eq!(buf.pos(), 4);

pub fn remaining(&self) -> usize

Returns the number of bytes available to read from current position.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_u32(42)?;
buf.put_u32(43)?;
buf.set_pos(0)?;

assert_eq!(buf.remaining(), 8);
buf.get_u32()?;
assert_eq!(buf.remaining(), 4);

pub fn has_remaining(&self, count: usize) -> bool

Checks if at least count bytes are available to read.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_u32(42)?;
buf.set_pos(0)?;

assert!(buf.has_remaining(4));
assert!(!buf.has_remaining(5));

pub fn set_pos(&mut self, pos: usize) -> Result<()>

Sets the read/write position.

Errors

Returns BufferError::PositionOutOfBounds if pos exceeds the buffer length.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_u32(42)?;
buf.set_pos(0)?;

assert_eq!(buf.get_u32()?, 42);

pub fn set_len(&mut self, len: usize) -> Result<()>

Sets the length of valid data.

When using with_capacity, this will grow the internal Vec if needed.

Errors

Returns BufferError::SizeTooBig if len exceeds BUF_MAX_SIZE.

Examples

use secbuf::Buffer;

let mut buf = Buffer::with_capacity(1024);
buf.set_len(100)?;
assert_eq!(buf.len(), 100);

pub fn incr_pos(&mut self, incr: usize) -> Result<()>

Increments the position by incr.

Errors

Returns BufferError::IncrementTooLarge if the increment is too large or would exceed the buffer length.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_bytes(b"hello")?;
buf.set_pos(0)?;

buf.incr_pos(2)?;
assert_eq!(buf.pos(), 2);

pub fn decr_pos(&mut self, decr: usize) -> Result<()>

Decrements the position by decr.

Errors

Returns BufferError::PositionOutOfBounds if decr exceeds the current position.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_u32(42)?;

buf.decr_pos(2)?;
assert_eq!(buf.pos(), 2);

pub fn incr_len(&mut self, incr: usize) -> Result<()>

Increments the length by incr.

When using with_capacity, this will grow the internal Vec if needed.

Errors

Returns BufferError::IncrementTooLarge if the increment is too large. Returns BufferError::SizeTooBig if the new length would exceed BUF_MAX_SIZE.

pub fn incr_write_pos(&mut self, incr: usize) -> Result<()>

Increments the write position and updates length if needed.

When using with_capacity, this will grow the internal Vec if needed.

Errors

Returns BufferError::IncrementTooLarge if the increment is too large or the new position would exceed BUF_MAX_SIZE.

pub fn reset(&mut self)

Resets the buffer for reuse by clearing position and length.

This does not free memory or zero the contents. Use burn for secure erasure.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_u32(42)?;
assert_eq!(buf.len(), 4);

buf.reset();
assert_eq!(buf.len(), 0);
assert_eq!(buf.pos(), 0);

pub fn burn(&mut self)

Securely zeros all buffer memory and resets position and length.

Uses compiler-resistant zeroing via the zeroize crate.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_bytes(b"sensitive data")?;
buf.burn();

pub fn as_slice(&self) -> &[u8]

Returns a slice of all valid data in the buffer.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_bytes(b"hello")?;
assert_eq!(buf.as_slice(), b"hello");

pub fn as_mut_slice(&mut self) -> &mut [u8]

Returns a mutable slice of all valid data.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_bytes(b"hello")?;
buf.as_mut_slice()[0] = b'H';
assert_eq!(buf.as_slice(), b"Hello");

pub fn resize(&mut self, new_size: usize) -> Result<()>

Resizes the buffer, preserving existing data.

Errors

Returns BufferError::SizeTooBig if new_size exceeds BUF_MAX_SIZE.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.resize(2048)?;
assert_eq!(buf.capacity(), 2048);

pub fn reserve(&mut self, additional: usize)

Ensures the buffer has at least the specified additional capacity.

Similar to Vec::reserve.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(100);
buf.reserve(1000);
assert!(buf.capacity() >= 1100);

pub fn shrink_to_fit(&mut self)

Shrinks the buffer capacity to fit the current length.

Frees unused memory.

Examples

use secbuf::Buffer;

let mut buf = Buffer::new(1024);
buf.put_bytes(b"hello")?;
buf.shrink_to_fit();
assert_eq!(buf.capacity(), 5);

pub fn put_u32(&mut self, val: u32) -> Result<()>

Writes a u32 in big-endian format with bounds checking.

pub fn get_u32(&mut self) -> Result<u32>

Reads a u32 in big-endian format with bounds checking.

pub fn put_u64(&mut self, val: u64) -> Result<()>

Writes a u64 in big-endian format with bounds checking.

pub fn get_u64(&mut self) -> Result<u64>

Reads a u64 in big-endian format with bounds checking.

pub fn put_bytes(&mut self, bytes: &[u8]) -> Result<()>

Writes bytes with a single bounds check.

pub fn get_bytes(&mut self, len: usize) -> Result<Vec<u8>>

Reads bytes, returning an owned Vec.

pub fn get_bytes_ref(&mut self, len: usize) -> Result<&[u8]>

Reads bytes as a slice reference (zero-copy).

pub fn get_ptr(&self, len: usize) -> Result<&[u8]>

Gets a reference to data at current position without advancing.

pub fn get_write_ptr(&mut self, len: usize) -> Result<&mut [u8]>

Gets a mutable reference to data at current position (for writing).

pub fn put_byte(&mut self, val: u8) -> Result<()>

Writes a single byte.

pub fn get_byte(&mut self) -> Result<u8>

Reads a single byte.

pub fn get_bool(&mut self) -> Result<bool>

Reads a boolean (0 = false, non-zero = true).

pub fn put_string(&mut self, s: &[u8]) -> Result<()>

Writes an SSH-style string (4-byte length prefix + data).

pub fn get_string(&mut self) -> Result<Vec<u8>>

Reads an SSH-style string (4-byte length prefix + data).

pub fn eat_string(&mut self) -> Result<()>

Skips over an SSH-style string without reading the data.

pub fn put_bytes_fast(&mut self, bytes: &[u8]) -> Result<()>

SIMD-accelerated bulk copy for large buffers (≥64 bytes).

pub unsafe fn put_u32_unchecked(&mut self, val: u32)

Writes a u32 in big-endian format without bounds checking.

Safety

Caller MUST guarantee: self.pos + 4 <= self.capacity().

pub unsafe fn get_u32_unchecked(&mut self) -> u32

Reads a u32 in big-endian format without bounds checking.

Safety

Caller MUST guarantee: self.pos + 4 <= self.len.

pub unsafe fn put_u64_unchecked(&mut self, val: u64)

Writes a u64 in big-endian format without bounds checking.

Safety

Caller MUST guarantee: self.pos + 8 <= self.capacity().

pub unsafe fn get_u64_unchecked(&mut self) -> u64

Reads a u64 in big-endian format without bounds checking.

Safety

Caller MUST guarantee: self.pos + 8 <= self.len.

pub unsafe fn put_bytes_unchecked(&mut self, bytes: &[u8])

Writes bytes without bounds checking.

Safety

Caller MUST guarantee: self.pos + bytes.len() <= self.capacity().

pub unsafe fn get_bytes_unchecked(&mut self, len: usize) -> &[u8]

Reads bytes without bounds checking, returning a slice.

Safety

Caller MUST guarantee: self.pos + len <= self.len.

Trait Implementations

impl Deref for PooledBuffer

type Target = Buffer

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for PooledBuffer

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for PooledBuffer

fn drop(&mut self)

Burns the buffer (secure zero of all bytes + metadata reset) and returns it to the pool if space is available.

Why burn() instead of reset()?

reset() only clears pos and len. The raw bytes in the backing allocation remain, and the next acquirer can expose them through resize(), set_len(), or get_write_ptr(). burn() calls vec.zeroize() first, so the next acquirer always receives a clean, zeroed buffer — consistent with this library’s security contract.