Struct MemoryGrant 

pub struct MemoryGrant { /* private fields */ }

A memory grant.

Grants define a number of bytes which have been granted for use, with an accompanying “slop factor.”

Slop factor

There can be numerous sources of “slop” in terms of memory allocations, and limiting the memory usage of a process. Not all components can effectively track their true firm/hard limit, memory allocators have fragmentation that may be reduced over time but never fully eliminated, and so on.

In order to protect against this issue, we utilize a slop factor when calculating the effective limits that we should verify memory bounds again. For example, if we seek to use no more than 64MB of memory from the OS perspective (RSS), then intuitively we know that we might only be able to allocate 55-60MB of memory before allocator fragmentation causes us to reach 64MB RSS.

By specifying a slop factor, we can provide ourselves breathing room to ensure that we don’t try to allocate every last byte of the given global limit, inevitably leading to exceeding that limit and potentially causing out-of-memory crashes, etc.

Implementations

impl MemoryGrant

pub fn effective(effective_limit_bytes: usize) -> Result<Self, GrantError>

Creates a new memory grant based on the given effective limit.

This grant will have a slop factor of 0.0 to indicate that the effective limit is already inclusive of any necessary slop factor.

If the effective limit is greater than 9007199254740992 bytes (2^53 bytes, or roughly 9 petabytes), then None is returned. This is a hardcoded limit.

pub fn with_slop_factor( initial_limit_bytes: usize, slop_factor: f64, ) -> Result<Self, GrantError>

Creates a new memory grant based on the given initial limit and slop factor.

The slop factor accounts for the percentage of the initial limit that can effectively be used. For example, a slop factor of 0.1 would indicate that only 90% of the initial limit should be used, and a slop factor of 0.25 would indicate that only 75% of the initial limit should be used, and so on.

If the slop factor is not valid (must be 0.0 < slop_factor <= 1.0), then None is returned. If the effective limit is greater than 9007199254740992 bytes (2^53 bytes, or roughly 9 petabytes), then None is returned. This is a hardcoded limit.

pub fn initial_limit_bytes(&self) -> usize

Initial number of bytes granted.

This value is purely informational, and should not be used to calculating the memory available for use. For that value, see effective_limit_bytes.

pub fn slop_factor(&self) -> f64

The slop factor for the initial limit.

This value is purely informational.

pub fn effective_limit_bytes(&self) -> usize

Effective number of bytes granted.

This is the value which should be followed for memory usage purposes, as it accounts for the configured slop factor.

Trait Implementations

impl Clone for MemoryGrant

fn clone(&self) -> MemoryGrant

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MemoryGrant

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

Formats the value using the given formatter.

impl PartialEq for MemoryGrant

fn eq(&self, other: &MemoryGrant) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for MemoryGrant

impl Eq for MemoryGrant

impl StructuralPartialEq for MemoryGrant