Struct pretty_trace::PrettyTrace

pub struct PrettyTrace {
    pub full_file: Option<String>,
    pub fd: Option<i32>,
    pub exit_message: Option<String>,
    pub message: Option<&'static CHashMap<ThreadId, String>>,
    pub profile: bool,
    pub count: Option<usize>,
    pub sep: f32,
    pub whitelist: Option<Vec<String>>,
    pub ctrlc: bool,
    pub ctrlc_debug: bool,
    pub noexit: bool,
    pub function_to_run: Option<fn(_: &str)>,
}

A PrettyTrace is the working structure for this crate. See also the top-level crate documentation.

Fields

full_file: Option<String>

fd: Option<i32>

exit_message: Option<String>

message: Option<&'static CHashMap<ThreadId, String>>

profile: bool

count: Option<usize>

sep: f32

whitelist: Option<Vec<String>>

ctrlc: bool

ctrlc_debug: bool

noexit: bool

function_to_run: Option<fn(_: &str)>

Implementations

impl PrettyTrace

Normal usage of PrettyTrace is to call

PrettyTrace::new().< set some things >.on();

once near the begining of your main program. The ‘things’ are all the functions shown below other than new and on.

pub fn new() -> PrettyTrace

Initialize a PrettyTrace object. This does nothing in and of itself.

pub fn on(&mut self)

Cause a PrettyTrace object to do something: change the behavior of response to panic! to produce a prettified traceback and perform profiling, if profile() has been called. Calling of on is mandatory. It must be called exactly once at the end of a chain of operations on a PrettyTrace object. But this is not enforced.

pub fn ctrlc(&mut self) -> &mut PrettyTrace

Cause a Ctrl-C interrupt to be turned into a panic, and thence produce a traceback for the main thread. This does not allow you to see what other threads are doing. If you Ctrl-C twice in rapid succession, you may elide the traceback, but this is unreliable. Occasionally single interrupts are also incorrectly handled.

pub fn ctrlc_debug(&mut self) -> &mut PrettyTrace

Same as ctrlc, but generates some debugging information. For development purposes.

pub fn noexit(&mut self) -> &mut PrettyTrace

Turn off call to std::process::exit(101), which is normally triggered after printing a traceback (on panic). This could be useful if you want to run a bunch of tests, some of which fail, but you want to see the outcome of all of them. Note that 101 is the standard exit status for rust panics.

The downside of noexit is that you may get multiple tracebacks if your code fails in a parallel loop.

pub fn run_this(&mut self, f: fn(_: &str)) -> &mut PrettyTrace

After print a traceback, pass the traceback contents to the given function. For example, this could be used to send a bug report.

pub fn full_file(&mut self, full_file: &str) -> &mut PrettyTrace

Define a file, that in the event that a traceback is triggered by a panic, will be used to dump a full traceback to. The raison d’etre for this is that an abbreviated pretty traceback might in some cases elide useful information (although this has not been observed).

This may only be set from the main thread of a process. We disallow setting it from other threads because PrettyTrace works by setting the panic hook, which is global, and a value for full_file set by one thread might not be valid for another.

You can also force PrettyTrace to emit full tracebacks by setting the environment variable RUST_FULL_TRACE.

pub fn fd(&mut self, fd: i32) -> &mut PrettyTrace

Define a file descriptor, that in the event a traceback is triggered by a panic, will be used to dump a second copy of the traceback to.

pub fn exit_message(&mut self, message: &str) -> &mut PrettyTrace

Define a message that is to be omitted after a traceback and before exiting.

Example

fn main() {
    let message = "Dang it, you found a bug!  Please call us at (999) 123-4567.";
    PrettyTrace::new().exit_message(&message).on();

pub fn message(
    &mut self,
    message: &'static CHashMap<ThreadId, String>
) -> &mut PrettyTrace

Define a message object that will be used by threads to store their status. This is printed if a traceback is triggered by a panic, and where code is traversing data in a loop, can be used to determine not only where execution is in the code, but also where it is in the data.

This may only be set from the main thread of a process. We disallow setting it from other threads because PrettyTrace works by setting the panic hook, which is global, and a value for message set by one thread might not be valid for another.

Example

use std::thread;
fn main() {
    let message = new_thread_message();
    PrettyTrace::new().message(&message).on();
    ...
    // do this whenever thread status changes enough to care
    message.insert( thread::current().id(), "here is what I'm doing now" );
    ...
}

Trait Implementations

impl Default for PrettyTrace

fn default() -> PrettyTrace

Returns the “default value” for a type.