#heap #calculating #structure #data #time #heap-size

heapsz

A crate for calculating the heap usage of a data structure

2 unstable releases

new 0.1.0 May 14, 2024
0.0.1 Apr 25, 2024

#290 in Data structures

Download history 103/week @ 2024-04-24 3/week @ 2024-05-01

106 downloads per month

MIT license

34KB
769 lines

heapsz

A crate for calculating the heap usage of a data structure.

It's simple. Only one required method in the HeapSize trait, which can be generated by #[derive(HeapSize)].

It's fast. It estimates an approximate heap size in O(1) time.

Usage

Examples

Calculate heap_size() selectively

Example Expanded example
#[derive(HeapSize)]
struct Foo {
    a: usize,
    b: Option<u64>,
    #[heap_size]
    c: Box<[usize; 5]>,
    #[heap_size]
    d: Vec<usize>,
}
impl HeapSize for Foo {
    fn heap_size(&self) -> usize {
        self.c.heap_size() + self.d.heap_size()
    }
}
Calculate heap_size() of all fields
Example Expanded example
#[derive(HeapSize)]
#[heap_size]
struct Foo {
    a: usize,
    b: Option<u64>,
    c: Box<[usize; 5]>,
    d: Vec<usize>,
}
impl HeapSize for Foo {
    fn heap_size(&self) -> usize {
        self.a.heap_size()
            + self.b.heap_size()
            + self.c.heap_size()
            + self.d.heap_size()
    }
}
Skip irrelative fields
Example Expanded example
#[derive(HeapSize)]
#[heap_size]
struct Foo {
    a: usize,
    b: Option<u64>,
    #[heap_size(skip)]
    c: Arc<[usize; 5]>,
    d: Vec<usize>,
}
impl HeapSize for Foo {
    fn heap_size(&self) -> usize {
        self.a.heap_size()
            + self.b.heap_size()
            + self.d.heap_size()
    }
}
Implement HeapSize for third-party structs
Example Expanded example
mod bytes_heap_size {
    pub heap_size(
        b: &Bytes
    ) -> usize {
        b.len()
    }
}

#[derive(HeapSize)]
#[heap_size]
struct Foo {
    a: usize,
    b: Option<u64>,
    c: Box<[usize; 5]>,
    d: Bytes,
}
impl HeapSize for Foo {
    fn heap_size(&self) -> usize {
        self.a.heap_size()
            + self.b.heap_size()
            + bytes_heap_size::heap_size(&self.d)
    }
}

#[derive(HeapSize)]

Field attributes

Apply to one field in a struct or in an enum variant.

  • #[heap_size]

    By default, #[derive(HeapSize)] generates an empty implementation which always return 0. #[heap_size] needs to be added to fields that have a heap allocation.

    This is because of 1) most struct does not contain heap allocation at all, and 2) they often do not implement the HeapSize trait.

  • #[heap_size(skip)]

    Skip this field: do not calculate its heap size.

    Requires a struct has a container attribute #[heap_size].

  • #[heap_size(with = "module")]

    #[derive(HeapSize)] will use $module::heap_size as the function to obtain this field’s heap size.

Container attributes

Apply to a struct or enum declaration.

  • #[heap_size] By default, #[derive(HeapSize)] generates an empty implementation that always return 0. By adding #[heap_size], it sums up heap_size() of all fields in a struct or an enum.

Variant attributes

Apply to a variant of an enum.

  • #[heap_size]

    Generate By default, #[derive(HeapSize)] generates an empty implementation which always return 0. By adding #[heap_size], it sums up heap_size() of fields in a variant.

  • #[heap_size(skip)]

    Skip this variant: do not calculate its heap size.

    Requires an enum has a #[heap_size] container attribute.

License

This project is licensed under the MIT license.

Dependencies

~0–370KB