Crate malloc_size_of

A crate for measuring the heap usage of data structures in a way that integrates with Firefox’s memory reporting, particularly the use of mozjemalloc and DMD. In particular, it has the following features.

• It isn’t bound to a particular heap allocator.
• It provides traits for both “shallow” and “deep” measurement, which gives flexibility in the cases where the traits can’t be used.
• It allows for measuring blocks even when only an interior pointer can be obtained for heap allocations, e.g. HashSet and HashMap. (This relies on the heap allocator having suitable support, which mozjemalloc has.)
• It allows handling of types like Rc and Arc by providing traits that are different to the ones for non-graph structures.

Suggested uses are as follows.

• When possible, use the MallocSizeOf trait. (Deriving support is provided by the malloc_size_of_derive crate.)

• If you need an additional synchronization argument, provide a function that is like the standard trait method, but with the extra argument.

• If you need multiple measurements for a type, provide a function named add_size_of that takes a mutable reference to a struct that contains the multiple measurement fields.

• When deep measurement (via MallocSizeOf) cannot be implemented for a type, shallow measurement (via MallocShallowSizeOf) in combination with iteration can be a useful substitute.

• Rc and Arc are always tricky, which is why MallocSizeOf is not (and should not be) implemented for them.

• If an Rc or Arc is known to be a “primary” reference and can always be measured, it should be measured via the MallocUnconditionalSizeOf trait.

• If an Rc or Arc should be measured only if it hasn’t been seen before, it should be measured via the MallocConditionalSizeOf trait.

• Using universal function call syntax is a good idea when measuring boxed fields in structs, because it makes it clear that the Box is being measured as well as the thing it points to. E.g. <Box<_> as MallocSizeOf>::size_of(field, ops).

  Note: WebRender has a reduced fork of this crate, so that we can avoid publishing this crate on crates.io.

Macros

• malloc_size_of_hash_map 🔒
• malloc_size_of_hash_set 🔒
• malloc_size_of_is_0
  For use on types where size_of() returns 0.

Structs

• MallocSizeOfOps
  Operations used when measuring heap usage of data structures.
• Measurable
  Measurable that defers to inner value and used to verify MallocSizeOf implementation in a struct.

Traits

• MallocConditionalShallowSizeOf
  MallocConditionalSizeOf combined with MallocShallowSizeOf.
• MallocConditionalSizeOf
  Like MallocSizeOf, but only measures if the value hasn’t already been measured. For use with types like Rc and Arc when appropriate (e.g. when there is no “primary” reference).
• MallocShallowSizeOf
  Trait for measuring the “shallow” heap usage of a container.
• MallocSizeOf
  Trait for measuring the “deep” heap usage of a data structure. This is the most commonly-used of the traits.
• MallocUnconditionalShallowSizeOf
  MallocUnconditionalSizeOf combined with MallocShallowSizeOf.
• MallocUnconditionalSizeOf
  Like MallocSizeOf, but with a different name so it cannot be used accidentally with derive(MallocSizeOf). For use with types like Rc and Arc when appropriate (e.g. when measuring a “primary” reference).

Type Aliases

• VoidPtrToBoolFnMut 🔒
  A closure implementing a stateful predicate on pointers.
• VoidPtrToSizeFn 🔒
  A C function that takes a pointer to a heap allocation and returns its size.