# mem_dbg [![downloads](https://img.shields.io/crates/d/mem_dbg)](https://crates.io/crates/mem_dbg) [![dependents](https://img.shields.io/librariesio/dependents/cargo/mem_dbg)](https://crates.io/crates/mem_dbg/reverse_dependencies) ![GitHub CI](https://github.com/zommiommy/mem_dbg-rs/actions/workflows/rust.yml/badge.svg) ![license](https://img.shields.io/crates/l/mem_dbg) [![Latest version](https://img.shields.io/crates/v/mem_dbg.svg)](https://crates.io/crates/mem_dbg) [![Documentation](https://docs.rs/mem_dbg/badge.svg)](https://docs.rs/mem_dbg) [![Coverage Status](https://coveralls.io/repos/github/zommiommy/mem_dbg-rs/badge.svg?branch=main)](https://coveralls.io/github/zommiommy/mem_dbg-rs?branch=main) Traits and associated procedural macros to inspect recursively the memory usage and layout of a value. The trait [`MemSize`] can be used to compute the overall memory usage of a value in bytes; the standard library function [`std::mem::size_of`] returns the _stack_ size of a type in bytes, but it does not take into consideration heap memory. We provide implementations for most basic types, a derive macro for structs and enums whose fields implement [`MemSize`], and support for a few other crates via optional features. The trait [`MemDbg`], which depends on [`MemSize`], can be used to display the recursive layout of a value, together with the size of each part and the associated padding bytes. ## Why `MemSize` [`MemSize`] outperforms other similar traits by using the type system to avoid iterating over the content of a container (e.g., a vector of `Copy` types) when it is not necessary. This allows it to compute instantly the size of values occupying hundreds of gigabytes of heap memory. Moreover, while the size estimation of `BTreeMap`, `BTreeSet`, `HashMap`, and `HashSet` is heuristic in all libraries, `mem_dbg` is significantly more precise, and takes into account the load factor and the power-of-two size constraint of the hash map. The following table compares [`mem_dbg`] against [`deepsize`] and [`get-size`]. The true memory usage (0% error) is calculated using the allocator from the [`cap`] crate. | Type | Container | Crate | Error (%) | Time/Elem (ns) | |--------|-----------|----------|-----------------|----------------| | String | BTreeMap | deepsize | 21.53 ± 8.88 | 7.14 | | | | get-size | 16.04 ± 7.74 | **7.06** | | | | mem_dbg | **3.17 ± 1.45** | 7.90 | | | BTreeSet | deepsize | 18.58 ± 8.51 | 7.65 | | | | get-size | 17.54 ± 8.38 | **6.05** | | | | mem_dbg | **3.73 ± 2.65** | 8.35 | | | HashMap | deepsize | 6.12 ± 3.42 | **2.44** | | | | get-size | 6.12 ± 3.42 | 2.92 | | | | mem_dbg | **0.62 ± 1.30** | 2.49 | | | HashSet | deepsize | 6.91 ± 3.82 | **1.37** | | | | get-size | 6.91 ± 3.82 | 1.82 | | | | mem_dbg | **1.13 ± 2.32** | 1.38 | | usize | BTreeMap | deepsize | 36.51 ± 20.88 | 3.42 | | | | get-size | 42.01 ± 21.73 | 2.96 | | | | mem_dbg | **1.25 ± 2.59** | **0.46** | | | BTreeSet | deepsize | 28.18 ± 12.41 | 2.44 | | | | get-size | 46.91 ± 23.70 | 2.28 | | | | mem_dbg | **1.57 ± 2.97** | **0.32** | | | HashMap | deepsize | 15.64 ± 6.34 | 1.30 | | | | get-size | 15.64 ± 6.34 | **0.30** | | | | mem_dbg | **0.00 ± 0.00** | 0.32 | | | HashSet | deepsize | 19.57 ± 7.91 | 1.33 | | | | get-size | 19.57 ± 7.91 | **0.32** | | | | mem_dbg | **0.00 ± 0.00** | 0.33 | [`deepsize`] is about six orders of magnitude slower than our implementation for copy types, due to the necessity to iterate over all elements. ## References Two flags, [`SizeFlags::FOLLOW_REFS`] and [`DbgFlags::FOLLOW_REFS`], make it possible to follow references when computing the size or displaying the layout of a value. Analogously, [`SizeFlags::FOLLOW_RC`] and [`DbgFlags::FOLLOW_RC`] make it possible to follow [`Rc`]/[`Arc`] smart pointers. ## Padding The trait [`MemDbg`] is useful to display the layout of a value and understand how much memory is used by each part. In particular, it exploits the new stable macro [`std::mem::offset_of`] to display the padding of each field in square brackets; moreover, the flag [`DbgFlags::RUST_LAYOUT`] makes it possible to display structures in the layout used by the Rust compiler, rather than that given by declaration order. These features are also available for enums using the feature `offset_of_enum`, which however needs the nightly compiler, as it enables the unstable feature `offset_of_enum`. ## Features - `std`: enables the use of the standard library; this is enabled by default. - `derive`: enables the derive macros [`MemSize`] and [`MemDbg`]; this is enabled by default. - `offset_of_enum`: support for padding and for the [`DbgFlags::RUST_LAYOUT`] flag for enums. Requires the nightly compiler as it enables the unstable feature `offset_of_enum`. Calling `mem_dbg` with the flag [`DbgFlags::RUST_LAYOUT`] without this feature enabled will result in a panic. - `half`: support for the [`half`] crate. - `maligned`: support for the [`maligned`] crate. - `mmap-rs`: support for the [`mmap-rs`] crate. - `rand`: support for the [`rand`] crate. ## Examples This is an example program using [`MemSize`] and [`MemDbg`]. Note that we cannot visualize the effect of the useful [`DbgFlags::COLOR`] flag, which colorizes sizes depending on their magnitude. ```rust # fn main() -> Result<(), Box> { # #[cfg(all(feature = "std", feature = "derive"))] # #[cfg_attr(feature = "offset_of_enum", feature(offset_of_enum))] # { use mem_dbg::*; #[derive(MemSize, MemDbg)] struct Struct { a: A, b: B, test: isize, } #[derive(MemSize, MemDbg)] struct Data { a: A, b: Vec, c: (u8, String), } #[derive(MemSize, MemDbg)] union SingletonUnion { a: A } #[derive(MemSize, MemDbg)] enum TestEnum { Unit, Unit2(), Unit3 {}, Union(SingletonUnion), Unnamed(usize, u8), Named { first: usize, second: u8 }, } let b = Vec::with_capacity(100); let s = Struct { a: TestEnum::Unnamed(0, 16), b: Data { a: vec![0x42_u8; 700], b, c: (1, "foo".to_owned()), }, test: -0xbadf00d, }; println!("size: {}", s.mem_size(SizeFlags::default())); println!("capacity: {}", s.mem_size(SizeFlags::CAPACITY)); println!(); s.mem_dbg(DbgFlags::empty())?; println!(); println!("size: {}", s.mem_size(SizeFlags::default())); println!("capacity: {}", s.mem_size(SizeFlags::CAPACITY)); println!(); s.mem_dbg(DbgFlags::default() | DbgFlags::CAPACITY | DbgFlags::HUMANIZE)?; #[cfg(feature = "offset_of_enum")] { println!(); println!("size: {}", s.mem_size(SizeFlags::default())); println!("capacity: {}", s.mem_size(SizeFlags::CAPACITY)); println!(); s.mem_dbg(DbgFlags::empty() | DbgFlags::RUST_LAYOUT)?; } # } # Ok(()) # } ``` The previous program prints: ```test size: 807 capacity: 1207 807 B ⏺ 16 B ├╴a │ ├╴Variant: Unnamed 8 B │ ├╴0 1 B │ ╰╴1 783 B ├╴b 724 B │ ├╴a 24 B │ ├╴b 35 B │ ╰╴c 1 B │ ├╴0 [7B] 27 B │ ╰╴1 8 B ╰╴test size: 807 capacity: 1207 1.207 kB 100.00% ⏺: readme::main::Struct>> 16 B 1.33% ├╴a: readme::main::TestEnum │ ├╴Variant: Unnamed 8 B 0.66% │ ├╴0: usize 1 B 0.08% │ ╰╴1: u8 1.183 kB 98.01% ├╴b: readme::main::Data> 724 B 59.98% │ ├╴a: alloc::vec::Vec 424 B 35.13% │ ├╴b: alloc::vec::Vec 35 B 2.90% │ ╰╴c: (u8, alloc::string::String) 1 B 0.08% │ ├╴0: u8 [7B] 27 B 2.24% │ ╰╴1: alloc::string::String 8 B 0.66% ╰╴test: isize ``` If run with the feature `offset_of_enum`, it prints: ```text size: 807 capacity: 1207 807 B ⏺ 16 B ├╴a │ ├╴Variant: Unnamed 8 B │ ├╴0 1 B │ ╰╴1 [6B] 783 B ├╴b 724 B │ ├╴a 24 B │ ├╴b 35 B │ ╰╴c 1 B │ ├╴0 [7B] 27 B │ ╰╴1 8 B ╰╴test size: 807 capacity: 1207 1.207 kB 100.00% ⏺: readme::main::Struct>> 16 B 1.33% ├╴a: readme::main::TestEnum │ ├╴Variant: Unnamed 8 B 0.66% │ ├╴0: usize 1 B 0.08% │ ╰╴1: u8 [6B] 1.183 kB 98.01% ├╴b: readme::main::Data> 724 B 59.98% │ ├╴a: alloc::vec::Vec 424 B 35.13% │ ├╴b: alloc::vec::Vec 35 B 2.90% │ ╰╴c: (u8, alloc::string::String) 1 B 0.08% │ ├╴0: u8 [7B] 27 B 2.24% │ ╰╴1: alloc::string::String 8 B 0.66% ╰╴test: isize size: 807 capacity: 1207 807 B ⏺ 783 B ├╴b 724 B │ ├╴a 24 B │ ├╴b 35 B │ ╰╴c 1 B │ ├╴0 [7B] 27 B │ ╰╴1 16 B ├╴a │ ├╴Variant: Unnamed 1 B │ ├╴1 [6B] 8 B │ ╰╴0 8 B ╰╴test ``` ## Caveats - We support out-of-the-box most basic types, and tuples up to size ten. The derive macros `MemSize`/`MemDbg` will generate implementations for structs and enums whose fields implement the associated interface: if this is not the case (e.g., because of the orphan rule) one can implement the traits manually. - If you invoke the methods of this crate on a shared reference, the compiler will automatically dereference it, and the method will be invoked on the referenced type: ```rust # fn main() -> Result<(), Box> { use mem_dbg::*; let mut x: [i32; 4] = [0, 0, 0, 0]; assert_eq!( (&x).mem_size(SizeFlags::default()), std::mem::size_of::<[i32; 4]>() ); assert_eq!( (&mut x).mem_size(SizeFlags::default()), std::mem::size_of::<&mut [i32; 4]>() ); assert_eq!( <&[i32; 4] as MemSize>::mem_size(&&x, SizeFlags::default()), std::mem::size_of::<&[i32; 4]>() ); # Ok(()) # } ``` - Computation of the size of arrays, slices, and vectors will be performed by iterating over their elements unless the type is a copy type that does not contain non-`'static` references and it is declared as such using the attribute `#[copy_type]`. See [`CopyType`] for more details. - The content of vectors and slices is not expanded recursively as the output might be too complex; this might change in the future (e.g., via a flag) should interesting use cases arise. - Regarding `union`s, we only support completely the special case of the single field `union`, for which we implement both the derive macros `MemSize`/`MemDbg`. For the more complex cases of unions with multiple fields, we only provide the `MemSize` derive macro with partial support, excluding support for the `SizeFlags::FOLLOW_REFS` flag. If full support for derive macros `MemSize`/`MemDbg` in the case of an union with multiple fields, one can implement the traits manually. [`MemDbg`]: https://docs.rs/mem_dbg/latest/mem_dbg/trait.MemDbg.html [`MemSize`]: https://docs.rs/mem_dbg/latest/mem_dbg/trait.MemSize.html [`std::mem::size_of`]: https://doc.rust-lang.org/std/mem/fn.size_of.html [`DbgFlags::RUST_LAYOUT`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.DbgFlags.html#associatedconstant.RUST_LAYOUT [`DbgFlags::COLOR`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.DbgFlags.html#associatedconstant.COLOR [`CopyType`]: https://docs.rs/mem_dbg/latest/mem_dbg/trait.CopyType.html [`cap`]: https://crates.io/crates/cap [`get-size`]: https://crates.io/crates/get_size [`deepsize`]: https://crates.io/crates/deepsize [`maligned`]: https://crates.io/crates/maligned [`mmap-rs`]: https://crates.io/crates/mmap-rs [`half`]: https://crates.io/crates/half [`rand`]: https://crates.io/crates/rand [`Rc`]: https://doc.rust-lang.org/std/rc/struct.Rc.html [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html [`DbgFlags::FOLLOW_REFS`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.DbgFlags.html#associatedconstant.FOLLOW_REFS [`DbgFlags::FOLLOW_RC`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.DbgFlags.html#associatedconstant.FOLLOW_RC [`SizeFlags::FOLLOW_REFS`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.SizeFlags.html#associatedconstant.FOLLOW_REFS [`SizeFlags::FOLLOW_RC`]: https://docs.rs/mem_dbg/latest/mem_dbg/struct.SizeFlags.html#associatedconstant.FOLLOW_RC

Statistics

Details

Quality Indicators