Crate tracking_allocator

tracking-allocator

This crate provides a global allocator implementation (compatible with GlobalAlloc) that allows users to trace allocations and deallocations directly. Allocation tokens can also be registered, which allows users to get an identifier that has associated metadata, which when used, can enhance the overall tracking of allocations.

high-level usage

tracking-allocator has three main components:

• Allocator, a GlobalAlloc-compatible allocator that intercepts allocations and deallocations
• the AllocationTracker trait, which defines an interface for receiving allocation and deallocation events
• AllocationGroupToken which is used to associate allocation events with a logical group

These components all work in tandem together. Once the allocator is installed, an appropriate tracker implementation can also be installed to handle the allocation and deallocation events as desired, whether you’re simply tracking the frequency of allocations, or trying to track the real-time usage of different allocation groups. Allocation groups can be created on-demand, as well, which makes them suitable to tracking additional logical groups over the lifetime of the process.

Additionally, tracking can be enabled and disabled at runtime, allowing you to make the choice of when to incur the performance overhead of tracking.

examples

Two main examples are provided: stdout and tracing. Both examples demonstrate how to effectively to use the crate, but the tracing example is specific to using the tracing-compat feature.

The examples are considered the primary documentation for the “how” of using this crate effectively. They are extensively documented, and touch on the finer points of writing a tracker implementation, including how to avoid specific pitfalls related to deadlocking and reentrant code that could lead to stack overflows.

Structs

AllocationGroupId

The identifier that uniquely identifiers an allocation group.

AllocationGroupToken

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

AllocationGuard

Guard that updates the current thread to track allocations for the associated allocation group.

AllocationLayer

AllocationLayer is a tracing_subscriber::Layer that handles entering and exiting an allocation group as the span it is attached to is itself entered and exited.

AllocationRegistry

Handles registering tokens for tracking different allocation groups.

Allocator

Tracking allocator implementation.

SetTrackerError

Returned if trying to set the global tracker fails.

Traits

AllocationTracker

Tracks allocations and deallocations.