refactor(esp-alloc): Remove get_info!() macro in favour of document…

…ing `HEAP.stats()`

esp-alloc/CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `esp_alloc::get_info!()` can now be used to get heap usage informations (#2137)
+- `esp_alloc::HEAP.stats()` can now be used to get heap usage informations (#2137)
 
 ### Changed
 

esp-alloc/Cargo.toml

@@ -27,14 +27,16 @@ cfg-if = "1.0.0"
 critical-section = "1.1.3"
 enumset = "1.1.5"
 linked_list_allocator = { version = "0.10.5", default-features = false, features = ["const_mut_refs"] }
+document-features = "0.2.10"
 
 [features]
 default = []
 nightly = []
 
-# Enable this feature if you want to keep stats about the internal heap usage such as:
-# - Max memory usage since initialization of the heap
-# - Total allocated memory since initialization of the heap
-# - Total freed memory since initialization of the heap
-# Note: Enabling this feature will require extra computation every time alloc/dealloc is called.
+## Enable this feature if you want to keep stats about the internal heap usage such as:
+## - Max memory usage since initialization of the heap
+## - Total allocated memory since initialization of the heap
+## - Total freed memory since initialization of the heap
+##
+## ⚠️ Note: Enabling this feature will require extra computation every time alloc/dealloc is called.
 internal-heap-stats = []

esp-alloc/src/lib.rs

@@ -51,7 +51,28 @@
 //! ```rust
 //! let large_buffer: Vec<u8, _> = Vec::with_capacity_in(1048576, &PSRAM_ALLOCATOR);
 //! ```
-
+//!
+//! You can also gets stats about the heap usage at anytime with:
+//! ```rust
+//! let stats: HeapStats = esp_alloc::HEAP.stats();
+//! // HeapStats implements the Display trait, so you can pretty print the heap stats.
+//! println!("{}", stats);
+//! ```
+//!
+//! ```txt
+//! HEAP INFO
+//! Size: 2097152
+//! Current usage: 512028
+//! Max usage: 512028
+//! Total freed: 0
+//! Total allocated: 512028
+//! Memory Layout:
+//! External | ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░ | Used: 512028 / Total: 2097152 (Free: 1585124)
+//! Unused | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
+//! Unused | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
+//! ```
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
 #![no_std]
 #![cfg_attr(feature = "nightly", feature(allocator_api))]
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
@@ -63,6 +84,7 @@ use core::alloc::{AllocError, Allocator};
 use core::{
  alloc::{GlobalAlloc, Layout},
  cell::RefCell,
+ fmt::Display,
  ptr::{self, NonNull},
 };
 
@@ -104,7 +126,7 @@ pub struct RegionStats {
  capabilities: EnumSet<MemoryCapability>,
 }
 
-impl core::fmt::Display for RegionStats {
+impl Display for RegionStats {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
  let used_blocks = BAR_WIDTH * self.used / self.size;
  let free_blocks = BAR_WIDTH - used_blocks;
@@ -174,6 +196,10 @@ impl HeapRegion {
  }
 }
 
+/// Stats for a heap allocator
+///
+/// Enable the "internal-heap-stats" feature if you want collect additional heap informations at
+/// the cost of extra cpu time during every alloc/dealloc.
 #[derive(Debug)]
 pub struct HeapStats {
  /// Granular stats for all the configured memory regions.
@@ -198,7 +224,7 @@ pub struct HeapStats {
  total_freed: usize,
 }
 
-impl core::fmt::Display for HeapStats {
+impl Display for HeapStats {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
  writeln!(f, "HEAP INFO")?;
  writeln!(f, "Size: {}", self.size)?;

esp-alloc/src/macros.rs

@@ -41,16 +41,3 @@ macro_rules! psram_allocator {
  }
  }};
 }
-
-/// Gets the usage stats for the current memory heap
-///
-/// # Usage
-/// ```rust, no_run
-/// esp_alloc::get_info!();
-/// ```
-#[macro_export]
-macro_rules! get_info {
- () => {{
- $crate::HEAP.stats()
- }};
-}

examples/src/bin/psram_quad.rs

@@ -51,7 +51,7 @@ fn main() -> ! {
  let string = String::from("A string allocated in PSRAM");
  println!("'{}' allocated at {:p}", &string, string.as_ptr());
 
- println!("{}", esp_alloc::get_info!());
+ println!("{}", esp_alloc::HEAP.stats());
 
  println!("done");