NAME

Parse::StackTrace::Thread - A single thread (or the only thread) of a stack trace.

SYNOPSIS

 my $thread = $trace->thread_number(1);
 
 my $frames = $thread->frames;
 my $thread_number = $thread->number;
 my $thread_description = $thread->description;
 
 my $first_frame = $thread->frame_number(0);
 my @print_frames = $thread->frames_with_function('print');
 my $print_frame = $thread->frames_with_function('print');
 my $crash_frame = $thread->frame_with_crash;

DESCRIPTION

Represents a single thread of a stack trace (or, for traces that have only one thread, the one thread of a stack trace). Generally, you access a thread by calling "threads" in Parse::StackTrace or "thread_number" in Parse::StackTrace.

SIMPLE ACCESSOR METHODS

These are methods that take no arguments and just return information about the thread.

frames

An arrayref of Parse::StackTrace::Frame objects. All the frames of this thread. There should always be at least one frame.

Frames are always ordered from most recent to oldest. So the last function that was called is always first, in this array.

number

Some stack traces number their threads. If this particular stack trace has numbered threads, then this is an integer representing the number of the thread. If this stack trace doesn't have numbered threads, then this is undef.

description

Some stack traces give their threads descriptions--some more information about the thread--sometimes including a unique identifier. If this stack trace has thread descriptions, then this is a string representing the description of the thread. If this stack trace doesn't have thread descriptions, then this is undef

frame_with_crash

In some types of traces, the frame where we crashed may not be the most recent frame. In fact, this thread may not contain the crash at all.

This method returns the Parse::StackTrace::Frame where we crashed, or undef if there is no crash in this thread.

ACCESSOR METHODS THAT TAKE ARGUMENTS

These are methods that take arguments and return information about this thread.

frame_number

Takes a single integer argument. Returns the frame with the specified number. If you are working with a particular type stack trace that doesn't have numbered frames (like Python), this just returns the nth frame from "frames".

If you are looking for a frame with a particular number, it is more reliable to use this method than to directly dereference "frames", because theoretically a trace could have a partial stack, missing some frames, and the 1st item in "frames" could be frame 4, or something like that. (There are no known ways of producing a stack like that, but it's still theoretically possible.)

Frames are numbered from 0 (because that's how GDB does it, and GDB was our first implementation).

frames_with_function

Takes a single string argument. Returns all the frames where the named function is called. The search is case-sensitive.

When called in array context, this returns an the array of Parse::StackTrace::Frame objects, or an empty array if no frames were found.

In scalar context, this returns the first frame found (as a Parse::StackTrace::Frame object), or undef if no frames were found.

SEE ALSO

You may also want to read the documentation for the specific implementations of Thread for the various types of traces, which may have more methods than the basic Thread:

Parse::StackTrace::Type::GDB::Thread

Parse::StackTrace::Type::Python::Thread

cpanm Parse::StackTrace

perl -MCPAN -e shell
install Parse::StackTrace