|| 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`
- 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.