From e58ee54ce6043fe671d41b09a876eb752ff6004c Mon Sep 17 00:00:00 2001
From: Anthony Grondin <104731965+AnthonyGrondin@users.noreply.github.com>
Date: Tue, 17 Sep 2024 12:24:12 -0400
Subject: [PATCH] refactor(esp-alloc): Remove `get_info!()` macro in favour of
 documenting `HEAP.stats()`

---
 esp-alloc/CHANGELOG.md         |  2 +-
 esp-alloc/Cargo.toml           | 12 +++++++-----
 esp-alloc/src/lib.rs           | 32 +++++++++++++++++++++++++++++---
 esp-alloc/src/macros.rs        | 13 -------------
 examples/src/bin/psram_quad.rs |  2 +-
 5 files changed, 38 insertions(+), 23 deletions(-)

diff --git a/esp-alloc/CHANGELOG.md b/esp-alloc/CHANGELOG.md
index 662b9e8351..cc7c7d6979 100644
--- a/esp-alloc/CHANGELOG.md
+++ b/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
 
diff --git a/esp-alloc/Cargo.toml b/esp-alloc/Cargo.toml
index 53961cf827..edad1dcfe6 100644
--- a/esp-alloc/Cargo.toml
+++ b/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 = []
diff --git a/esp-alloc/src/lib.rs b/esp-alloc/src/lib.rs
index 31c84ed83b..ba9a964bc7 100644
--- a/esp-alloc/src/lib.rs
+++ b/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)?;
diff --git a/esp-alloc/src/macros.rs b/esp-alloc/src/macros.rs
index 254c403023..47d9c454fa 100644
--- a/esp-alloc/src/macros.rs
+++ b/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()
-    }};
-}
diff --git a/examples/src/bin/psram_quad.rs b/examples/src/bin/psram_quad.rs
index 1e9ff49f55..36e05bc8db 100644
--- a/examples/src/bin/psram_quad.rs
+++ b/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");