docs: Add more canbench-rs documentation (#86)

* Add `Debugging` section.
* Add `Preventing Compiler Optimizations` section.
* Use `black_box` in examples.
* Other minor changes.

---------

Co-authored-by: Dimitris Sarlis <[email protected]>

canbench-rs/src/lib.rs

@@ -96,14 +96,14 @@
 //!
 //!     #[bench]
 //!     fn fibonacci_20() {
-//!         // NOTE: the result is printed to prevent the compiler from optimizing the call away.
-//!         println!("{:?}", fibonacci(20));
+//!         // Prevent the compiler from optimizing the call and propagating constants.
+//!         std::hint::black_box(fibonacci(std::hint::black_box(20)));
 //!     }
 //!
 //!     #[bench]
 //!     fn fibonacci_45() {
-//!         // NOTE: the result is printed to prevent the compiler from optimizing the call away.
-//!         println!("{:?}", fibonacci(45));
+//!         // Prevent the compiler from optimizing the call and propagating constants.
+//!         std::hint::black_box(fibonacci(std::hint::black_box(45)));
 //!     }
 //! }
 //! ```
@@ -402,6 +402,66 @@
 //!
 //! Executed 1 of 1 benchmarks.
 //! ```
+//!
+//! ### Debugging
+//!
+//! The `ic_cdk::eprintln!()` macro facilitates tracing canister and benchmark execution.
+//! Output is displayed on the console when `canbench` is executed with
+//! the `--show-canister-output` option.
+//!
+//! ```rust
+//! # #[cfg(feature = "canbench-rs")]
+//! # mod benches {
+//! #     use super::*;
+//! #     use canbench_rs::bench;
+//! #
+//!     #[bench]
+//!     fn bench_with_debug_print() {
+//!         // Run `canbench --show-canister-output` to see the output.
+//!         ic_cdk::eprintln!("Hello from {}!", env!("CARGO_PKG_NAME"));
+//!     }
+//! # }
+//! ```
+//!
+//! Example output:
+//!
+//! ```bash
+//! $ canbench bench_with_debug_print --show-canister-output
+//! [...]
+//! 2021-05-06 19:17:10.000000003 UTC: [Canister lxzze-o7777-77777-aaaaa-cai] Hello from example!
+//! [...]
+//! ```
+//!
+//! Refer to the [Internet Computer specification](https://internetcomputer.org/docs/references/ic-interface-spec#debugging-aids) for more details.
+//!
+//! ### Preventing Compiler Optimizations
+//!
+//! If benchmark results appear suspiciously low and remain consistent
+//! despite increased benchmarked function complexity, the `std::hint::black_box`
+//! function helps prevent compiler optimizations.
+//!
+//! ```rust
+//! # #[cfg(feature = "canbench-rs")]
+//! # mod benches {
+//! #     use super::*;
+//! #     use canbench_rs::bench;
+//! #
+//!     #[bench]
+//!     fn fibonacci_20() {
+//!         // Prevent the compiler from optimizing the call and propagating constants.
+//!         std::hint::black_box(fibonacci(std::hint::black_box(20)));
+//!     }
+//! # }
+//! ```
+//!
+//! Note that passing constant values as function arguments can also
+//! trigger compiler optimizations. If the actual code uses
+//! variables (not constants), both the arguments and the result
+//! of the benchmarked function must be wrapped in `black_box` calls.
+//!
+//! Refer to the [Rust documentation](https://doc.rust-lang.org/std/hint/fn.black_box.html)
+//! for more details.
+//!
 pub use canbench_rs_macros::bench;
 use candid::CandidType;
 use serde::{Deserialize, Serialize};

examples/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
+edition = "2021"
 name = "example"
 version = "0.1.0"
-edition = "2021"
 
 [[bin]]
 name = "fibonacci"
@@ -14,5 +14,5 @@ path = "btreemap_vs_hashmap/src/main.rs"
 [dependencies]
 canbench-rs = { path = "../canbench-rs", optional = true }
 candid.workspace = true
-ic-cdk.workspace= true
+ic-cdk.workspace = true
 ic-cdk-macros.workspace = true

examples/btreemap_vs_hashmap/canbench_results.yml

@@ -7,12 +7,12 @@ benches:
     scopes: {}
   pre_upgrade_bench:
     total:
-      instructions: 807868600
+      instructions: 807869264
       heap_increase: 519
       stable_memory_increase: 184
     scopes:
       serialize_state:
-        instructions: 792936247
+        instructions: 792936911
         heap_increase: 519
         stable_memory_increase: 0
       writing_to_stable_memory:

examples/fibonacci/canbench_results.yml

@@ -1,13 +1,31 @@
 benches:
   fibonacci_20:
     total:
-      instructions: 2187
+      instructions: 730
       heap_increase: 0
       stable_memory_increase: 0
     scopes: {}
   fibonacci_45:
     total:
-      instructions: 2925
+      instructions: 1305
+      heap_increase: 0
+      stable_memory_increase: 0
+    scopes: {}
+  fibonacci_8a:
+    total:
+      instructions: 454
+      heap_increase: 0
+      stable_memory_increase: 0
+    scopes: {}
+  fibonacci_8b:
+    total:
+      instructions: 207
+      heap_increase: 0
+      stable_memory_increase: 0
+    scopes: {}
+  fibonacci_8c:
+    total:
+      instructions: 395
       heap_increase: 0
       stable_memory_increase: 0
     scopes: {}

examples/fibonacci/src/main.rs

@@ -39,14 +39,31 @@ mod benches {
 
     #[bench]
     fn fibonacci_20() {
-        // NOTE: the result is printed to prevent the compiler from optimizing the call away.
-        println!("{:?}", fibonacci(20));
+        // Prevent the compiler from optimizing the call and propagating constants.
+        std::hint::black_box(fibonacci(std::hint::black_box(20)));
+    }
+
+    // Note how the results of the following three functions differ:
+    #[bench]
+    fn fibonacci_8a() {
+        // this takes 454 instructions,
+        std::hint::black_box(fibonacci(std::hint::black_box(8)));
+    }
+    #[bench]
+    fn fibonacci_8b() {
+        // this takes 207 instructions,
+        std::hint::black_box(fibonacci(8));
+    }
+    #[bench]
+    fn fibonacci_8c() {
+        // and this takes 395 instructions.
+        fibonacci(std::hint::black_box(8));
     }
 
     #[bench]
     fn fibonacci_45() {
-        // NOTE: the result is printed to prevent the compiler from optimizing the call away.
-        println!("{:?}", fibonacci(45));
+        // Prevent the compiler from optimizing the call and propagating constants.
+        std::hint::black_box(fibonacci(std::hint::black_box(45)));
     }
 }