Struct tracking_allocator::AllocationGroupToken

pub struct AllocationGroupToken(_);

A token that uniquely identifies an allocation group.

Allocation groups are the core grouping mechanism of tracking-allocator and drive much of its behavior. While the allocator must be overridden, and a global track provided, no allocations are tracked unless a group is associated with the current thread making the allocation.

Practically speaking, allocation groups are simply an internal identifier that is used to identify the “owner” of an allocation. Additional tags can be provided when acquire an allocation group token, which is provided to AllocationTracker whenever an allocation occurs.

Usage

In order for an allocation group to be attached to an allocation, its must be “entered.” AllocationGroupToken functions similarly to something like a mutex, where “entering” the token conumes the token and provides a guard: AllocationGuard. This guard is tied to the allocation group being active: if the guard is dropped, or if it is exited manually, the allocation group is no longer active.

AllocationGuard also tracks if another allocation group was active prior to entering, and ensures it is set back as the active allocation group when the guard is dropped. This allows allocation groups to be nested within each other.

Implementations

impl AllocationGroupToken

pub fn acquire() -> AllocationGroupToken

Acquires an allocation group token.

pub fn acquire_with_tags<K, V>(tags: &[(K, V)]) -> AllocationGroupToken where
    K: Into<Cow<'static, str>> + Clone,
    V: Into<Cow<'static, str>> + Clone, 

Acquires an allocation group token, with tags.

While allocation groups are primarily represented by their AllocationGroupToken, users can use this method to attach specific tags – or key/value string pairs – to the group. These tags will be provided to the global tracker whenever an allocation event is associated with the allocation group.

Memory usage

In order to minimize any allocations while in the process of tracking normal allocations, we rely on utilizing only static references to data. If the tags given are not already 'static references, they will be leaked in order to make them 'static. Thus, callers should take care to avoid registering tokens on an ongoing basis when utilizing owned tags as this could create a persistent and ever-growing memory leak over the life of the process.

pub fn enter(self) -> AllocationGuard

Marks the associated allocation group as the active allocation group on this thread.

If another allocation group is currently active, it is replaced, and restored either when this allocation guard is dropped, or when AllocationGuard::exit is called.

impl AllocationGroupToken

pub fn attach_to_span(self, span: &Span)

This is supported on crate feature tracing-compat only.

Attaches this allocation group to a tracing Span.

When the span is entered or exited, the allocation group will also transition from idle to active, or active to idle. In effect, all allocations that occur while the span is entered will be associated with the allocation group.