## heapsz

A crate for calculating the heap usage of a data structure

### 2 unstable releases

 new 0.1.0 May 14, 2024 Apr 25, 2024

#290 in Data structures

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.

~0–370KB