xtd::diagnostics::stack_trace Class Reference

#include <stack_trace.h>

Definition

Represents a stack trace, which is an ordered collection of one or more stack frames.

class core_export_ stack_trace : public xtd::object

Inheritance

xtd::object → xtd::diagnostics::stack_trace

Namespace

xtd::diagnostics

Library

xtd.core

Examples

The following console application demonstrates how to create a simple xtd::diagnostics::stack_trace and iterate through its frames to obtain debugging and diagnostic information.

#include <xtd/xtd>

using namespace xtd;
using namespace xtd::diagnostics;

class stack_trace_sample {
public:
  void my_public_method() {
    my_protected_method();
  }
  
protected:
  void my_protected_method() {
    my_internal_class mic;
    mic.throws_exception();
  }
  
private:
  class my_internal_class {
  public:
    void throws_exception() {
      try {
        throw system_exception("A problem was encountered.");
      } catch (const system_exception&) {
        // Create a StackTrace that captures filename, line number and column information.
        stack_trace st(true);
        ustring stack_indent = "";
        for (size_t i = 0; i < st.frame_count(); i++) {
          // Note that at this level, there are four stack frames, one for each method invocation.
          stack_frame sf = st.get_frame(i);
          console::write_line();
          console::write_line(stack_indent + " Method: {0}", sf.get_method());
          console::write_line(stack_indent + " File: {0}", sf.get_file_name());
          console::write_line(stack_indent + " Line Number: {0}", sf.get_file_line_number());
          stack_indent += "  ";
        }
        throw;
      }
    }
  };
};

auto main()->int {
  stack_trace_sample sample;
  try {
    sample.my_public_method();
  } catch (const system_exception&) {
    // Create a StackTrace that captures filename, line number, and column information for the current thread.
    stack_trace st(true);
    for (size_t i = 0; i < st.frame_count(); i++) {
      // Note that high up the call stack, there is only one stack frame.
      stack_frame sf = st.get_frame(i);
      console::write_line();
      console::write_line("High up the call stack, Method: {0}", sf.get_method());
      
      console::write_line("High up the call stack, Line Number: {0}", sf.get_file_line_number());
    }
  }
}

// This code produces the following output :
//
//  File: /!---OMITTED---!/stack_trace_simple
//  Line Number: 24
//
//    Method: stack_trace_sample::my_protected_method()
//    File: /!---OMITTED---!/stack_trace_simple
//    Line Number: 14
//
//      Method: stack_trace_sample::my_public_method()
//      File: /!---OMITTED---!/stack_trace_simple
//      Line Number: 9
//
//        Method: main
//        File: /!---OMITTED---!/stack_trace_simple
//        Line Number: 44
//
// High up the call stack, Method: main
// High up the call stack, Line Number: 0

Remarks

xtd::diagnostics::stack_trace information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing xtd::diagnostics::stack_frame and xtd::diagnostics::stack_trace objects.

xtd::diagnostics::stack_trace might not report as many method calls as expected, due to code transformations that occur during optimization.

Examples:

stack_frame.cpp, stack_trace.cpp, and stack_trace_simple.cpp.

Alias
using	stack_frame_collection = std::vector< xtd::diagnostics::stack_frame >
	Represents a stack_frame collection. More...

Constructors
	stack_trace ()
	Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame. More...
	stack_trace (bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, optionally capturing source information. More...
	stack_trace (const xtd::diagnostics::stack_frame &frame)
	Initializes a new instance of the xtd::diagnostics::stack_trace class that contains a single frame. More...
	stack_trace (const std::exception &exception)
	Initializes a new instance of the xtd::diagnostics::stack_trace class using the provided exception object. More...
	stack_trace (size_t skip_frames)
	Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, skipping the specified number of frames. More...
	stack_trace (const std::exception &exception, size_t skip_frames)
	Initializes a new instance of the StackTrace class using the provided exception object and skipping the specified number of frames. More...
	stack_trace (size_t skip_frames, bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, skipping the specified number of frames and optionally capturing source information. More...
	stack_trace (const std::exception &exception, size_t skip_frames, bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_trace class using the provided exception object, skipping the specified number of frames and optionally capturing source information. More...
	stack_trace (const std::exception &exception, bool need_file_info)
	Initializes a new instance of the xtd::diagnostics::stack_trace class, using the provided exception object and optionally capturing source information. More...

Fields
static constexpr size_t	METHODS_TO_SKIP = 0
	Defines the default for the number of methods to omit from the stack trace. This field is constant. More...

Properties
size_t	frame_count () const noexcept
	Gets the number of frames in the stack trace. More...

Methods
const xtd::diagnostics::stack_frame &	get_frame (size_t index) noexcept
	Gets the specified stack frame. More...
const stack_frame_collection &	get_frames () const noexcept
	Returns a copy of all stack frames in the current stack trace. More...
xtd::ustring	to_string () const noexcept override
	Builds a readable representation of the stack trace. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Gets the type of the current instance. More...
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Member Typedef Documentation

stack_frame_collection

using xtd::diagnostics::stack_trace::stack_frame_collection = std::vector<xtd::diagnostics::stack_frame>

Represents a stack_frame collection.

Constructor & Destructor Documentation

stack_trace() [1/9]

xtd::diagnostics::stack_trace::stack_trace

(

)

Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame.

Examples

The following code example displays the first and last function calls in a stack trace.

void Level_5_method() {
  try {
    class_level_6 nested_class;
    nested_class.level_6_method();
  } catch (const system_exception& e) {
    console::write_line(" Level_5_method exception handler");

    stack_trace st;

    // Display the most recent function call.
    stack_frame sf = st.get_frame(0);
    console::write_line();
    console::write_line("  Exception in method: ");
    console::write_line("      {}", sf.get_method());

    if (st.frame_count() >1) {
      // Display the highest-level function call
      // in the trace.
      sf = st.get_frame(st.frame_count() - 1);
      console::write_line("  Original function call at top of call stack):");
      console::write_line("      {}", sf.get_method());
    }

    console::write_line();
    console::write_line("   ... throwing exception to next level ...");
    console::write_line("-------------------------------------------------\n");
    throw;
  }
}

Remarks

The xtd::diagnostics::stack_trace is created with the caller's current thread, and does not contain file name, line number, or column information.

Use this parameterless constructor when you want a complete trace with only summary method information about the call stack.

stack_trace() [2/9]

xtd::diagnostics::stack_trace::stack_trace ( bool  need_file_info )

explicit

Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, optionally capturing source information.

Parameters

need_file_info

true to capture the file name, line number, and column number; otherwise, false.

Examples

The following code example displays the first and last function calls in a stack trace.

void Level_5_method() {
  try {
    class_level_6 nested_class;
    nested_class.level_6_method();
  } catch (const system_exception& e) {
    console::write_line(" Level_5_method exception handler");

    stack_trace st;

    // Display the most recent function call.
    stack_frame sf = st.get_frame(0);
    console::write_line();
    console::write_line("  Exception in method: ");
    console::write_line("      {}", sf.get_method());

    if (st.frame_count() >1) {
      // Display the highest-level function call
      // in the trace.
      sf = st.get_frame(st.frame_count() - 1);
      console::write_line("  Original function call at top of call stack):");
      console::write_line("      {}", sf.get_method());
    }

    console::write_line();
    console::write_line("   ... throwing exception to next level ...");
    console::write_line("-------------------------------------------------\n");
    throw;
  }
}

Remarks

The xtd::diagnostics::stack_trace is created with the caller's current thread.

stack_trace() [3/9]

xtd::diagnostics::stack_trace::stack_trace ( const xtd::diagnostics::stack_frame &  frame )

explicit

Initializes a new instance of the xtd::diagnostics::stack_trace class that contains a single frame.

Parameters

frame

The frame that the xtd::diagnostics::stack_trace object should contain.

Examples

The following code example writes stack trace information to an event log entry.

stack_frame fr(1, true);
stack_trace st(fr);
debug::write_line(ustring::format("{}\n{}", fr.get_method(), st.to_string());

Remarks

Use this constructor when you do not want the overhead of a full stack trace.

stack_trace() [4/9]

xtd::diagnostics::stack_trace::stack_trace ( const std::exception &  exception )

explicit

Initializes a new instance of the xtd::diagnostics::stack_trace class using the provided exception object.

Parameters

exception

The exception object from which to construct the stack trace.

Remarks

The xtd::diagnostics::stack_trace is created with the caller's current thread, and does not contain file name, line number, or column information.

The resulting stack trace describes the stack at the time of the exception.

stack_trace() [5/9]

xtd::diagnostics::stack_trace::stack_trace ( size_t  skip_frames )

explicit

Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, skipping the specified number of frames.

Parameters

skip_frames

The number of frames up the stack from which to start the trace.

Remarks

The xtd::diagnostics::stack_trace is created with the caller's current thread, and does not contain file name, line number, or column information.

If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the xtd::diagnostics::stack_trace will contain no frames.

stack_trace() [6/9]

xtd::diagnostics::stack_trace::stack_trace	(	const std::exception &	exception,
		size_t	skip_frames
	)

Initializes a new instance of the StackTrace class using the provided exception object and skipping the specified number of frames.

Parameters

exception	The exception object from which to construct the stack trace.
skip_framed	The number of frames up the stack from which to start the trace.

Remarks

The xtd::diagnostics::stack_trace does not contain file name, line number, or column information.

The resulting stack trace describes the stack at the time of the exception.

If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the xtd::diagnostics::stack_trace will contain no frames.

stack_trace() [7/9]

xtd::diagnostics::stack_trace::stack_trace	(	size_t	skip_frames,
		bool	need_file_info
	)

Initializes a new instance of the xtd::diagnostics::stack_trace class from the caller's frame, skipping the specified number of frames and optionally capturing source information.

Parameters

skip_frames	The number of frames up the stack from which to start the trace.
need_file_info	true to capture the file name, line number, and column number; otherwise, false.

Examples

The following code example displays the first and last function calls in a stack trace.

void Level_5_method() {
  try {
    class_level_6 nested_class;
    nested_class.level_6_method();
  } catch (const system_exception& e) {
    console::write_line(" Level_5_method exception handler");

    stack_trace st;

    // Display the most recent function call.
    stack_frame sf = st.get_frame(0);
    console::write_line();
    console::write_line("  Exception in method: ");
    console::write_line("      {}", sf.get_method());

    if (st.frame_count() >1) {
      // Display the highest-level function call
      // in the trace.
      sf = st.get_frame(st.frame_count() - 1);
      console::write_line("  Original function call at top of call stack):");
      console::write_line("      {}", sf.get_method());
    }

    console::write_line();
    console::write_line("   ... throwing exception to next level ...");
    console::write_line("-------------------------------------------------\n");
    throw;
  }
}

Remarks

If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the xtd::diagnostics::stack_trace will contain no frames.

stack_trace() [8/9]

xtd::diagnostics::stack_trace::stack_trace	(	const std::exception &	exception,
		size_t	skip_frames,
		bool	need_file_info
	)

Initializes a new instance of the xtd::diagnostics::stack_trace class using the provided exception object, skipping the specified number of frames and optionally capturing source information.

Parameters

exception	The exception object from which to construct the stack trace.
skip_frames	The number of frames up the stack from which to start the trace.
need_file_info	true to capture the file name, line number, and column number; otherwise, false.

Remarks

The resulting stack trace describes the stack at the time of the exception.

If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the xtd::diagnostics::stack_trace will contain no frames.

stack_trace() [9/9]

xtd::diagnostics::stack_trace::stack_trace	(	const std::exception &	exception,
		bool	need_file_info
	)

Initializes a new instance of the xtd::diagnostics::stack_trace class, using the provided exception object and optionally capturing source information.

Parameters

exception	The exception object from which to construct the stack trace.
need_file_info	true to capture the file name, line number, and column number; otherwise, false.

Remarks

The resulting stack trace describes the stack at the time of the exception.

Member Function Documentation

frame_count()

size_t xtd::diagnostics::stack_trace::frame_count ( ) const

noexcept

Gets the number of frames in the stack trace.

Returns

The number of frames in the stack trace.

Examples

The following code example displays the first and last function calls in a stack trace.

void Level_5_method() {
  try {
    class_level_6 nested_class;
    nested_class.level_6_method();
  } catch (const system_exception& e) {
    console::write_line(" Level_5_method exception handler");

    stack_trace st;

    // Display the most recent function call.
    stack_frame sf = st.get_frame(0);
    console::write_line();
    console::write_line("  Exception in method: ");
    console::write_line("      {}", sf.get_method());

    if (st.frame_count() >1) {
      // Display the highest-level function call
      // in the trace.
      sf = st.get_frame(st.frame_count() - 1);
      console::write_line("  Original function call at top of call stack):");
      console::write_line("      {}", sf.get_method());
    }

    console::write_line();
    console::write_line("   ... throwing exception to next level ...");
    console::write_line("-------------------------------------------------\n");
    throw;
  }
}

Examples:

stack_trace_simple.cpp.

get_frame()

const xtd::diagnostics::stack_frame& xtd::diagnostics::stack_trace::get_frame ( size_t  index )

noexcept

Gets the specified stack frame.

Parameters

index

The index of the stack frame requested.

Returns

The specified stack frame.

Examples

The following code example displays the first and last function calls in a stack trace.

void Level_5_method() {
  try {
    class_level_6 nested_class;
    nested_class.level_6_method();
  } catch (const system_exception& e) {
    console::write_line(" Level_5_method exception handler");

    stack_trace st;

    // Display the most recent function call.
    stack_frame sf = st.get_frame(0);
    console::write_line();
    console::write_line("  Exception in method: ");
    console::write_line("      {}", sf.get_method());

    if (st.frame_count() >1) {
      // Display the highest-level function call
      // in the trace.
      sf = st.get_frame(st.frame_count() - 1);
      console::write_line("  Original function call at top of call stack):");
      console::write_line("      {}", sf.get_method());
    }

    console::write_line();
    console::write_line("   ... throwing exception to next level ...");
    console::write_line("-------------------------------------------------\n");
    throw;
  }
}

Remarks

Stack frames are numbered starting at 0, which is the last stack frame pushed.

Examples:

stack_trace_simple.cpp.

get_frames()

const stack_frame_collection& xtd::diagnostics::stack_trace::get_frames ( ) const

noexcept

Returns a copy of all stack frames in the current stack trace.

Returns

An array of type xtd::diagnostics::stack_frame representing the function calls in the stack trace.

Examples

The following code example demonstrates enumerating the frames in a xtd::diagnostics::stack_trace.

stack_trace st(1, true);
stack_trace::stack_frame_collection st_frames = st.get_frames();

for(const stack_frame& sf : st_frames) {
  console::write_line("Method: {}", sf.get_method());
}

Remarks

Use the returned xtd::diagnostics::stack_frame array to enumerate and examine function calls in the xtd::diagnostics::stack_trace. The size of the returned array is equal to the frame_count() property value.

The xtd::diagnostics::stack_frame array elements are in reverse chronological order. The xtd::diagnostics::stack_frame at array index 0 represents the most recent function call in the stack trace and the last frame pushed onto the call stack. The xtd::diagnostics::stack_frame at array index frame_count() minus 1 represents the oldest function call in the stack trace and the first frame pushed onto the call stack.

Use the get_frames() method to obtain all stack frames in a stack trace; use the get_frame(size_t) method to obtain a specific stack frame in a stack trace. The xtd::diagnostics::stack_frame indexes are ordered alike by the two methods. For example, the xtd::diagnostics::stack_frame at index 0 in the array returned by get_frames() is equivalent to the xtd::diagnostics::stack_frame returned by get_frame(size_t) with an input index of 0.

to_string()

xtd::ustring xtd::diagnostics::stack_trace::to_string ( ) const

overridevirtualnoexcept

Builds a readable representation of the stack trace.

Returns

A readable representation of the stack trace.

Examples

The following code example writes stack trace information to an event log entry.

stack_frame fr(1, true);
stack_trace st(fr);
debug::write_line(ustring::format("{}\n{}", fr.get_method(), st.to_string());

Reimplemented from xtd::object.

Examples:

stack_frame.cpp.

Member Data Documentation

METHODS_TO_SKIP

constexpr size_t xtd::diagnostics::stack_trace::METHODS_TO_SKIP = 0

static

Defines the default for the number of methods to omit from the stack trace. This field is constant.

Remarks

The default value for the number of methods to skip at the beginning of the stack trace. The value of this constant is 0.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/diagnostics/stack_trace.h