Crate si_trace_print

Expand description

Macros for printing stack-indented trace-like print statements.

Library users should use macros provided in printers (which are also listed here).

Basic Usage

use si_trace_print::{
    den, deo, dex, defn, defo, defx,
};

fn main() {
    den!("hello from main");
    deo!("main will be doing stuff...");
    func1(3);
    deo!("main is done doing stuff.");
    dex!("goodbye from main");
}

fn func1(_var: usize) {
    defn!("({:?})", _var);
    defo!("doing even more stuff...");
    defx!();
}

this should print to stderr

$ cargo run
→hello from main
 main will be doing stuff...
    →func1: (3)
     func1: doing even more stuff...
    ←func1:
 main is done doing stuff.
←goodbye from main

An example using a variety of the available println macros. These compile into debug and release builds and print to stdout.

extern crate si_trace_print;
use si_trace_print::{pf1n, pf2n, pfn, pn, po, px};

fn main() {
    pn!("hello from main");
    pfn!("hello again from main");
    pf1n!("hello again from main!");
    pf2n!("HELLO AGAIN FROM MAIN!!!");
    po!("main will be doing stuff...");
    mod1::mod2::func1(3);
    po!("main is done doing stuff...");
    px!("goodbye from main");
}

mod mod1 {
    pub mod mod2 {
        use si_trace_print::{
            pf1n, pf1o, pf1x, pf1ñ, pf2n, pf2o, pf2x, pf2ñ, pfn, pfo, pfx, pfñ, pñ,
        };
        pub fn func1(var: usize) {
            pf1n!("({:?})", var);
            pf1o!("func1 calling func2...");
            func2(var + 1);
            pf1x!("({:?})", var);
        }
        fn func2(var: usize) {
            pf2n!("({:?})", var);
            pf2o!("calling func3...");
            func3();
            pf2x!("({:?})", var);
        }
        fn func3() {
            pfn!();
            func4();
            pfo!("almost complete...");
            pfx!();
        }
        fn func4() {
            pñ!("func4 is a short function.");
            pfñ!("func4 is a short function.");
            pf1ñ!("func4 is a short function.");
            pf2ñ!("func4 is a short function.");
        }
    }
}

should print to stdout

→hello from main
→main: hello again from main
→main: hello again from main!
→main: HELLO AGAIN FROM MAIN!!!
 main will be doing stuff...
    →mod2::func1: (3)
     mod2::func1: func1 calling func2...
        →mod1::mod2::func2: (4)
         mod1::mod2::func2: calling func3...
            →func3:
                ↔func4 is a short function.
                ↔func4: func4 is a short function.
                ↔mod2::func4: func4 is a short function.
                ↔mod1::mod2::func4: func4 is a short function.
             func3: almost complete...
            ←func3:
        ←mod1::mod2::func2: (4)
    ←mod2::func1: (3)
 main is done doing stuff...
←goodbye from main

Multi-threaded printing and the global lock

To avoid interleaved printing among threads, surround your println! or eprintln! statements in the global lock guard GLOBAL_LOCK_PRINTER. Helper functions print_guard or debug_print_guard are provided.

use ::si_trace_print::{efn, efx};
use ::si_trace_print::printers::print_guard;

let mut handles: Vec<std::thread::JoinHandle<()>> = vec![];
for n in 0..10 {
    let h = std::thread::spawn(move || {
        efn!("time to do some work...");
        // ...do some work...
        let result = n;
        // ...a few moments later...
        // get the guard before printing
        let guard = print_guard();
        println!("{}", result);
        // drop the guard before calling another si_trace_print macro
        drop(guard);
        efx!("work complete");
    });
    handles.push(h);
}
for h in handles {
    h.join().unwrap();
}

If using si_trace_print debug macros (the recommended way to use this module) then call the debug_print_guard helper function.

In this code example, guard is a MutexGuard in debug builds and a () in non-debug release builds (which is likely optimized away).

use ::si_trace_print::{defn, defx};
use ::si_trace_print::printers::debug_print_guard;

let mut handles: Vec<std::thread::JoinHandle<()>> = vec![];
for n in 0..10 {
    let h = std::thread::spawn(move || {
        defn!("time to do some work...");
        // ...do some work...
        let result = n;
        // ...a little while later...
        // get the guard before printing
        let guard = debug_print_guard();
        println!("{}", result);
        // explicitly drop the guard before calling another si_trace_print macro
        drop(guard);
        defx!("work complete");
    });
    handles.push(h);
}
for h in handles {
    h.join().unwrap();
}

Modules

function_name
Macros to derive the current function name.
printers
Macros to print trace statements with stack offset indentation.
stack
Functions to store a stack offset for indented trace prints and return the appropriate preprint str.

Macros

de
debug eprintln!
def1n
debug eprintln! in a function plus one namespace level when entering.
def1o
debug eprintln! in a function plus one namespace level with offset.
def1x
debug eprintln! in a function plus one namespace level when exiting.
def1ñ
debug eprintln! in a function with one namespace levels when entering and exiting.
def2n
debug eprintln! in a function plus two namespace levels when entering.
def2o
debug eprintln! in a function plus two namespace levels with offset.
def2x
debug eprintln! in a function plus two namespace levels when exiting.
def2ñ
debug eprintln! in a function plus two namespace levels when entering and exiting.
defn
debug eprintln! in a function when entering.
defo
debug eprintln! in a function with offset.
defx
debug eprintln! in a function when exiting.
defñ
debug eprintln! in a function when entering and exiting.
den
debug eprintln! when entering.
deo
debug eprintln! with offset.
dex
debug eprintln! when exiting.
deñ
debug eprintln! when entering and exiting.
dp
debug println!
dpf1n
debug println! in a function plus one namespace level when entering.
dpf1o
debug println! in a function plus one namespace level with offset.
dpf1x
debug println! in a function plus one namespace level when exiting.
dpf1ñ
debug println! in a function plus one namespace level when entering and exiting.
dpf2n
debug println! in a function plus two namespace levels when entering.
dpf2o
debug println! in a function plus two namespace levels with offset
dpf2x
debug println! in a function plus two namespace levels when exiting.
dpf2ñ
debug println! in a function plus two namespace levels when entering and exiting.
dpfn
debug println! in a function when entering.
dpfo
debug println! in a function with offset.
dpfx
debug println! in a function when exiting.
dpfñ
debug println! in a function when entering and exiting.
dpn
debug println! when entering.
dpo
debug println! with offset.
dpx
debug println! when exiting.
dpñ
debug println! when entering and exiting.
e
eprintln!
ef1n
eprintln! in a function plus one namespace level when entering.
ef1o
eprintln! in a function with one namespace levels and offset.
ef1x
eprintln! in a function plus one namespace level when exiting.
ef1ñ
eprintln! in a function plus one namespace level when entering and exiting.
ef2n
eprintln! in a function plus two namespace levels when entering.
ef2o
eprintln! in a function with two namespace levels and offset.
ef2x
eprintln! in a function plus two namespace levels when exiting.
ef2ñ
eprintln! in a function plus two namespace levels when entering and exiting.
efn
eprintln! in a function when entering.
efo
eprintln! in a function with offset.
efx
eprintln! in a function when exiting.
efñ
eprintln! in a function when entering and exiting.
en
eprintln! when entering.
eo
eprintln! with offset.
ex
eprintln! when exiting.
eñ
eprintln! when entering and exiting.
function_name
Return the current function name as a &'static str, e.g. "my_func".
function_name_full
Return the current function name full path as a &'static str, e.g. "my_lib::my_mod::my_func".
function_name_plus
Return the current function name plus preceding namespaces as a &'static str.
p
println!
pf1n
println! in a function plus one namespace level when entering.
pf1o
println! in a function plus one namespace level with offset.
pf1x
println! in a function plus one namespace level when exiting.
pf1ñ
println! in a function plus one namespace level when entering and exiting.
pf2n
println! in a function plus two namespace levels when entering.
pf2o
println! in a function plus two namespace levels with offset.
pf2x
println! in a function plus two namespace levels when exiting.
pf2ñ
println! in a function plus two namespace levels when entering and exiting.
pfn
println! in a function when entering.
pfo
println! in a function with offset.
pfx
println! in a function when exiting.
pfñ
println! in a function when entering and exiting.
pn
println! when entering.
po
println! with offset.
px
println! when exiting.
pñ
println! when entering and exiting.