Struct AllocationGroupToken

pub struct AllocationGroupToken(/* private fields */);

A token that allows controlling when an allocation group is active or inactive.

Allocation groups represent the core mechanism for categorizing allocation activity, where the group must be active for (de)allocation events to be attributed to it. Practically speaking, allocation groups are simply an internal identifier that is used to identify the “owner” of an allocation.

Usage

In order for an allocation group to be attached to an allocation, it 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 register() -> Option<AllocationGroupToken>

Registers an allocation group token.

Allocation groups use an internal identifier that is incremented atomically, and monotonically, when registration occurs. This identifier, thus, has a limit based on the pointer size of the architecture. In other words, on 32-bit systems, a limit of 2^32 allocation groups can be registered before this identifier space is exhausted. On 64-bit systems, this limit is 2^64.

If the number of registered allocation groups exceeds the limit, None is returned. This is a permanent state until the application exits. Otherwise, Some is returned.

pub fn id(&self) -> AllocationGroupId

Gets the ID associated with this allocation group.

pub fn enter(&mut self) -> AllocationGuard<'_>

Enters the allocation group, marking it 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)

Available 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 inactive to active, and vise versa. In effect, all allocations that occur while the span is entered will be associated with the allocation group.