Add examples directory to samply-markers

This commit adds an examples directory with instructions
on how to build, run, and profile the examples shown in
the main README file.

Author: nordzilla

Cargo.lock

@@ -23,3 +23,8 @@ exclude = ["etw-reader"] # Should not be compiled on non-Windows
 [profile.dist]
 inherits = "release"
 lto = "thin"
+
+# Profile for profiling with samply
+[profile.profiling]
+inherits = "release"
+debug = true

Cargo.toml

@@ -34,3 +34,9 @@ regex = "1.12.2"
 serial_test = "3.2.0"
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros", "time"] }
 futures = "0.3"
+
+[dev-dependencies]
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros"] }
+reqwest = "0.12"
+futures = "0.3"
+rayon = "1.10"

samply-markers/Cargo.toml

@@ -273,6 +273,9 @@ async fn load_config(path: &str) -> (u32, u32) {
 
 Here's a complete example demonstrating everything in context:
 
+> [!NOTE]
+> See the [examples directory] to build, run, and profile the examples in this README yourself.
+
 
 **[macOS] | [Ubuntu] | Windows (not yet supported)**
 

samply-markers/README.md

@@ -0,0 +1,18 @@
+use samply_markers::prelude::*;
+
+fn fib(n: u64) -> u64 {
+    samply_measure!({
+        match n {
+            0 | 1 => n,
+            _ => fib(n - 1) + fib(n - 2),
+        }
+    }, marker: {
+        name: format!("fib({n})"),
+    })
+}
+
+fn main() {
+    let n = 10;
+    let value = fib(n);
+    println!("fib({n}) = {}", value);
+}

samply-markers/examples/01_fibonacci.rs

@@ -0,0 +1,73 @@
+use samply_markers::prelude::*;
+
+async fn fetch_url(url: &str) -> (String, Option<String>) {
+    // Emit an interval marker for the time it takes to fetch.
+    let result = samply_measure!(async {
+        let response = reqwest::get(url).await?;
+        response.text().await
+    }, marker: {
+        name: format!("fetch {url}"),
+    })
+    .await;
+
+    match result {
+        Ok(content) => {
+            println!("  ✓ Fetched {url} ({} bytes)", content.len());
+            (String::from(url), Some(content))
+        }
+        Err(error) => {
+            // Emit an instant marker any time a fetch fails.
+            samply_marker!({ name: format!("fetch failed: {url}") });
+            println!("  ✗ Failed to fetch {url}: {error}");
+            (String::from(url), None)
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    // Create a timer that will span the entirety of main().
+    // The timer will emit an interval marker when it is dropped at the end of the scope.
+    let _main_timer = samply_timer!({ name: "main()" });
+
+    println!("\nStarting samply-markers demo...\n");
+
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    let urls = &[
+        "https://example.com",
+        "https://fail.invalid",
+        "https://fail.invalid",
+        "https://en.wikipedia.org/wiki/Firefox",
+        "https://fail.invalid",
+        "https://github.com/nordzilla",
+    ];
+
+    println!("\n=== Sequential Fetching ===\n");
+
+    // Emit an interval marker for the total time to fetch all URLs sequentially.
+    samply_measure!({
+        for url in urls {
+            fetch_url(url).await;
+        }
+    }, marker: {
+        name: "fetch all URLs sequentially",
+    });
+
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    println!("\n=== Concurrent Fetching ===\n");
+
+    // Emit an interval marker for the total time to fetch all URLs concurrently.
+    samply_measure!({
+        futures::future::join_all(
+            urls.iter().map(|url| fetch_url(url))
+        ).await;
+    }, marker: {
+        name: "fetch all URLs concurrently",
+    });
+
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    println!("\nDemo completed!\n");
+}

samply-markers/examples/02_network_requests.rs

@@ -0,0 +1,55 @@
+use samply_markers::prelude::*;
+use tokio::time::{Duration, sleep};
+
+async fn migrating_task(task_id: usize, iterations: usize) {
+    for i in 0..iterations {
+        samply_measure!(async {
+            samply_marker!({ name: format!("task({task_id}): iteration {i} start") });
+
+            sleep(Duration::from_micros(100)).await;
+
+            let mut sum = 0u64;
+            for j in 0..10_000 {
+                sum = sum.wrapping_add(j);
+            }
+
+            sleep(Duration::from_micros(100)).await;
+        }, marker: {
+            name: format!("task {task_id} iter {i}"),
+        })
+        .await;
+
+        // Yield to encourage task migration.
+        tokio::task::yield_now().await;
+    }
+}
+
+#[tokio::main(flavor = "multi_thread", worker_threads = 10)]
+async fn main() {
+    let _main_timer = samply_timer!({ name: "main()" });
+
+    println!("\n=== Tokio Task Migration Demo ===\n");
+    println!("This example spawns async tasks on a multi-threaded runtime.");
+    println!("Tasks will migrate between worker threads during execution.");
+
+    let num_tasks = 8;
+    let iterations_per_task = 20;
+
+    samply_marker!({ name: "spawning tasks" });
+
+    let handles = (0..num_tasks)
+        .map(|task_id| {
+            tokio::spawn(async move { migrating_task(task_id, iterations_per_task).await })
+        })
+        .collect::<Vec<_>>();
+
+    samply_marker!({ name: "all tasks spawned" });
+
+    samply_measure!({
+        futures::future::join_all(handles).await
+    }, marker: {
+        name: "waiting for all tasks",
+    });
+
+    println!("\nAll tasks completed!");
+}

samply-markers/examples/03_tokio_task_migration.rs

@@ -0,0 +1,151 @@
+use rayon::{ThreadPoolBuilder, prelude::*};
+use samply_markers::prelude::*;
+use std::{collections::HashSet, time::Duration};
+
+fn contains_digit(mut value: u32, digit: u32) -> bool {
+    if value == 0 {
+        return digit == 0;
+    }
+
+    while value > 0 {
+        if value % 10 == digit {
+            return true;
+        }
+        value /= 10;
+    }
+
+    false
+}
+
+fn filter_numbers_with_digit(
+    chunk_id: usize,
+    numbers: &[u32],
+    digit: u32,
+    parallel_filters: bool,
+) -> Vec<u32> {
+    let mode = if parallel_filters {
+        "parallel"
+    } else {
+        "sequential"
+    };
+
+    samply_measure!({
+        if parallel_filters {
+            numbers
+                .par_iter()
+                .filter(|&&n| contains_digit(n, digit))
+                .cloned()
+                .collect()
+        } else {
+            numbers
+                .iter()
+                .filter(|&&n| contains_digit(n, digit))
+                .cloned()
+                .collect()
+        }
+    }, marker: {
+        name: format!("chunk {chunk_id} filter digit {digit} ({mode})"),
+    })
+}
+
+fn symmetric_difference_sum(chunk_id: usize, twos: &[u32], fives: &[u32]) -> u64 {
+    samply_measure!({
+        let two_set: HashSet<u32> = twos.iter().copied().collect();
+        let five_set: HashSet<u32> = fives.iter().copied().collect();
+
+        let only_twos: u64 = two_set
+            .difference(&five_set)
+            .map(|&value| value as u64)
+            .sum();
+        let only_fives: u64 = five_set
+            .difference(&two_set)
+            .map(|&value| value as u64)
+            .sum();
+
+        only_twos + only_fives
+    }, marker: {
+        name: format!("chunk {chunk_id} symmetric diff"),
+    })
+}
+
+fn process_chunk_pipeline(chunk_id: usize, numbers: &[u32], parallel_filters: bool) -> u64 {
+    let _chunk_timer = samply_timer!({ name: format!("chunk {chunk_id} pipeline") });
+
+    let twos = filter_numbers_with_digit(chunk_id, numbers, 2, parallel_filters);
+    let fives = filter_numbers_with_digit(chunk_id, numbers, 5, parallel_filters);
+
+    symmetric_difference_sum(chunk_id, &twos, &fives)
+}
+
+fn generate_chunks(chunk_count: usize, chunk_len: usize) -> Vec<Vec<u32>> {
+    let mut seed = 0u64;
+
+    (0..chunk_count)
+        .map(|_| {
+            let mut values = Vec::with_capacity(chunk_len);
+            for _ in 0..chunk_len {
+                seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
+                values.push((seed % 1_000_000) as u32);
+            }
+            values
+        })
+        .collect()
+}
+
+fn main() {
+    let _main_timer = samply_timer!({ name: "main()" });
+
+    ThreadPoolBuilder::new()
+        .num_threads(8)
+        .build_global()
+        .expect("Failed to configure Rayon thread pool");
+
+    println!("\n=== Digit Symmetric Difference Demo ===\n");
+
+    let chunk_count = 32;
+    let chunk_len = 131072;
+    let chunks = generate_chunks(chunk_count, chunk_len);
+
+    println!(
+        "Generated {} chunks with {} numbers each ({} total)\n",
+        chunk_count,
+        chunk_len,
+        chunk_count * chunk_len
+    );
+
+    println!("=== Sequential Processing ===");
+    let sequential_results: Vec<_> = samply_measure!({
+        chunks
+            .iter()
+            .enumerate()
+            .map(|(i, chunk)| process_chunk_pipeline(i, chunk, false))
+            .collect()
+    }, marker: {
+        name: "sequential pass",
+    });
+    let sequential_total: u64 = sequential_results.iter().sum();
+    println!(
+        "Sequential: {} chunks processed | total symmetric diff sum {}\n",
+        sequential_results.len(),
+        sequential_total
+    );
+
+    std::thread::sleep(Duration::from_millis(20));
+
+    println!("=== Parallel Processing (Rayon) ===");
+    let parallel_results: Vec<_> = samply_measure!({
+        chunks
+            .par_iter()
+            .enumerate()
+            .map(|(i, chunk)| process_chunk_pipeline(i + chunk_count, chunk, true))
+            .collect()
+    }, marker: {
+        name: "parallel pass",
+    });
+    let parallel_total: u64 = parallel_results.iter().sum();
+    println!(
+        "Parallel: {} chunks processed | total symmetric diff sum {}\n",
+        parallel_results.len(),
+        parallel_total
+    );
+}