Struct NumaBuffer 

pub struct NumaBuffer { /* private fields */ }

An owned buffer allocated with VirtualAllocExNuma, freed with VirtualFree on drop.

The allocation is page-granular: VirtualAllocExNuma rounds a request up to the system page size, so a caller asking for a small buffer gets at least a page. NumaBuffer::len reports the length that was requested, which is the length a kernel call should be told about.

Buffer traits

This type implements io-buffers’ IoBuf and IoBufMut, so a ring takes it as a buffer. This crate defines no trait of its own: the traits belong to io-buffers, which is portable and so cannot depend on this allocator, and the orphan rule lets only the crate that owns the trait or the type implement it. A crate that owns a buffer trait of its own implements it for this type the same way, over NumaBuffer::as_ptr, NumaBuffer::as_mut_ptr and NumaBuffer::len.

Implementations

impl NumaBuffer

pub fn new(len: usize, node: Option<NumaNode>) -> Result<NumaBuffer, Error>

Allocate len bytes, preferring node if given.

Passing None requests no NUMA preference, which is the same choice the default allocator makes implicitly.

What a successful return does and does not mean

A valid node is a preference, not an instruction – nndPreferred says so in its name – so success means the request was accepted and memory was obtained, never that the pages came from the node asked for.

An invalid node is a different matter and is genuinely refused: this crate’s tests assert that u32::MAX - 1 fails. Note that u32::MAX itself is not a test of that, because it is the API’s own no-preference sentinel and is accepted by design – a measurement that reads it as an out-of-range node being tolerated has measured the sentinel instead.

Errors

The error from VirtualAllocExNuma, which includes a len of zero and a node number the machine does not have.

pub fn as_ptr(&self) -> *const u8

The allocation’s base address, fixed for this value’s life.

pub fn as_mut_ptr(&mut self) -> *mut u8

The allocation’s base address for writing.

Takes &mut self because this value uniquely owns the allocation, so exclusive access to the value is exclusive access to the bytes.

pub fn len(&self) -> usize

The length that was requested.

Not the length that was reserved: VirtualAllocExNuma rounds up to a page, so the mapping is at least this large and usually larger. This is the number a kernel call should be told, because it is the number the caller asked to use.

pub fn is_empty(&self) -> bool

Whether the requested length was zero.

Present because clippy asks for it beside Self::len, and because a zero-length request is rejected by VirtualAllocExNuma rather than producing an empty buffer – so on any value that exists, this is false.

Trait Implementations

impl Debug for NumaBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Shows the address and requested length, never the contents: a registered buffer routinely holds someone’s data, and a Debug that printed it would put that data anywhere a caller logs.

impl Drop for NumaBuffer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl IoBuf for NumaBuffer

fn stable_ptr(&self) -> *const u8

The address of the first byte. Must not change for the value’s life.

fn bytes_len(&self) -> usize

How many bytes from IoBuf::stable_ptr may be read.

impl IoBufMut for NumaBuffer

fn stable_mut_ptr(&mut self) -> *mut u8

The mutable address of the first byte. Must equal IoBuf::stable_ptr and must not change for the value’s life.

impl Send for NumaBuffer