Devel::Chitin::Stack - An object representing the current execution stack


  # Get the stack
  my $stack = Devel::Chitin::Stack->new();
  my $depth = $stack->depth();

  # Get one particular stack frame
  my $frame = $stack->frame(3);

  # Iterate through the frames from most recent to oldest
  my $iter = $stack->iterator();
  while ($frame = $iter->()) {
      print "Level "        . $frame->level
          . " stopped in "  . $frame->subname
          . " of package "  . $frame->package . "\n";


The Stack object represents the current execution stack in the debugged program. It encapsulates the information from the caller() function, but differs from the raw caller data in that the stack frame locations reflect the currently executing line in each frame. The difference is subtle, but tailored for what a debugger is likely interested in.

The Stack object is composed of several Devel::Chitin::StackFrame objects, one for each call frame.


The "top" of the stack refers to the most recent call frame in the debugged program. The "bottom" of the stack is the oldest frame, usually the main program not part of any function call.

For example:

  foo();                # bottom is here, frame 2

  sub foo {
      my @a = bar();    # Frame 1

  sub bar {
      $answer = 1 + 2;  # <-- debugger is stopped here, frame 0

If the debugger is stopped before executing the indicated line, the top of the stack would report line 8 in subroutine main::bar in array context.

The call frame for the main program will look like this: 'hasargs' 1 subroutine main::MAIN package main args @ARGV as it looks in a BEGIN block when the program starts wantarray undef


  my $stack = Devel::Chitin::Stack->new();

Returns an instance of Devel::Chitin::stack. The call frames it contains does not include any stack frames within the debugger.



Returns the number of stack frames in the call stack


Return the $i-th call frame. 0 is the top of the stack.


Return a list of all the call frames.


Returns a coderef to iterate through the call frames. The top of the stack will be the first frame returned. After the bottom frame is returned, the iterator will return undef.


Returns a string representation of the call stack. Useful for showing the user.

StackFrame METHODS

These methods may be called on Devel::Chitin::StackFrame instances:


The package this frame is in


The filename this frame is in. For string evals, this will be a string like "(eval 23)[/some/file/path:125]"


The line within the file for this frame.


The full name of the subroutine for this frame. It will include the package. For the main program's stack frame, subroutine will be "main::MAIN".

For an eval frame, subroutine will be "(eval)"


If the optional module Devel::Callsite is installed, this will be the opcode address. callsite for the bottom-level stack frame will always be undef.


True if this frame has its own instance of @_. In practice, this will be 0 for eval frames, empty string for subroutines called as &subname;, and true otherwise.


The wantarray context for this frame. True if in array context, defined but false for scalar context, and undef for void context. Even though perls before 5.12 returned numeric 0 for scalar context, it is normalized to an empty string.


For an eval frame, and it was a string eval, this will be the string that is eval-ed. Non-string eval and other frames will have the value undef.


For an eval frame, this will be true if the frame is part of a "require" or "use".


For a string eval frame, this is the file name the original string appeared in. Other frames have the value undef.


For a string eval frame, this is the line the original string appeared in. Other frames have the value undef.


The hints value returned be caller for this frame


The bitmask value returned be caller for this frame


The subroutine name without the package name prepended to it.


If this call frame was entered because it was handled by an AUTOLOAD function, the 'autoload' attribute will be the function name that was actually called. The value is unreliable if called outside of the debugger system.


The number indicating how deep this call frame actually is. This number is not relative to the program being debugged, and so reflects the real number of frames between the caller and the bottom of the stack, including any frames within the debugger.


Each instance of a subroutine call gets a unique identifier as an integer, including the initial frame for MAIN.

eval frames also get serial numbers that are distinct between different function call frames. eval frames within the same function call frame on the same line (such as inside a loop) will, unfortunately, have the same serial number. This bug will hopefully be fixed in the future.


Devel::Chitin, Devel::StackTrace


Anthony Brummett <>


Copyright 2017, Anthony Brummett. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.