Trait succinct::SpaceUsage [−] [src]

pub trait SpaceUsage: Sized {
    fn is_stack_only() -> bool;

    fn total_bytes(&self) -> usize { ... }
    fn stack_bytes() -> usize { ... }
    fn heap_bytes(&self) -> usize { ... }
}

Types that know how to compute their space usage.

We calculate the space usage is split into two portions, the heap portion (returned by heap_bytes and the stack portion (returned by stack_bytes). The stack portion is the statically-known size for every object of its type as allocated on the stack; the dynamic portion is the additional heap allocation that may depend on run-time factors.

Examples:

  • Primitive types like u32 and usize are stack-only.

  • A tuple or struct type is stack-only when all its components are. Its heap portion is the sum of their heap portions, but its stack portion may exceed the sum of their stack portions because of alignment and padding.

  • The size of a vector includes a stack portion, the vector struct itself, and a heap portion, the array holding its elements. The heap portion of a vector includes the stack portions of its elements. (Should they be called something else for this reason? I considered static/dynamic, but Box shows why that doesn’t express exactly the right property.)

Required Methods

fn is_stack_only() -> bool

Is the size of this type known statically?

If this method returns true then heap_bytes should always return 0.

Provided Methods

fn total_bytes(&self) -> usize

Computes the size of the receiver in bytes.

This includes not just the immediate stack object, but any heap memory that it owns.

The default implementation returns Self::stack_bytes() + self.heap_bytes().

fn stack_bytes() -> usize

Calculates the stack portion of the size of this type.

This is the size of the immediate storage that all objects of this type occupy; it excludes storage that objects of the type might allocate dynamically.

The default implementation returns std::mem::size_of::<Self>().

fn heap_bytes(&self) -> usize

Calculates the heap portion of the size of an object.

This is the memory used by (or, rather, owned by) the object, not including any portion of its size that is included in stack_bytes. This is typically for containers that heap allocate varying amounts of memory.

The default implementation returns 0.

Implementors