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 whitelist: Option<Vec<String>>,
    pub ctrlc: bool,
    pub ctrlc_debug: bool,
    pub haps_debug: bool,
    pub noexit: bool,
}

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>

whitelist: Option<Vec<String>>

ctrlc: bool

ctrlc_debug: bool

haps_debug: bool

noexit: bool

Methods

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 haps_debug(&mut self) -> &mut PrettyTrace

Turn on some debugging for profiling. For development purposes.

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

Turn off call to std::process::exit(1), 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.

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).

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.

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" );
    ...
}

pub fn profile(&mut self, count: usize) -> &mut PrettyTrace

Request that a profile consisting of count traces be generated. If you use this, consider calling whitelist too.

pub fn whitelist(&mut self, whitelist: &[&str]) -> &mut PrettyTrace

Define the whitelist for profile mode. It is a list of strings that profile traces are matched against. Only traces matching at least one of the strings are shown. This allows tracebacks to be focused on a fixed set of crates that you're trying to optimize. Setting this option can greatly increase the utility of profile mode.

Example

   PrettyTrace::new()
       .profile(100)
       .whitelist( &vec![ "gerbilizer", "creampuff" ] )
       .on();

Trait Implementations

impl Default for PrettyTrace

fn default() -> PrettyTrace

Returns the "default value" for a type.