Crate graphannis_malloc_size_of
source ·Expand description
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
andHashMap
. (This relies on the heap allocator having suitable support, which mozjemalloc has.) - It allows handling of types like
Rc
andArc
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 themalloc_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 (viaMallocShallowSizeOf
) in combination with iteration can be a useful substitute. Rc
andArc
are always tricky, which is whyMallocSizeOf
is not (and should not be) implemented for them.- If an
Rc
orArc
is known to be a “primary” reference and can always be measured, it should be measured via theMallocUnconditionalSizeOf
trait. - If an
Rc
orArc
should be measured only if it hasn’t been seen before, it should be measured via theMallocConditionalSizeOf
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)
.
Macros
For use on types where size_of() returns 0.
Structs
Operations used when measuring heap usage of data structures.
Measurable that defers to inner value and used to verify MallocSizeOf implementation in a
struct.
Traits
MallocConditionalSizeOf
combined with MallocShallowSizeOf
.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).Trait for measuring the “shallow” heap usage of a container.
Trait for measuring the “deep” heap usage of a data structure. This is the
most commonly-used of the traits.
MallocUnconditionalSizeOf
combined with MallocShallowSizeOf
.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).