xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Types | Static Public Attributes | Public Member Functions | List of all members
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.

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& e) {
// 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(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 e;
}
}
};
};
int main() {
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("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.

Public Types

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

Static Public Attributes

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

Public Member Functions

 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...
 
size_t frame_count () const
 Gets the number of frames in the stack trace. More...
 
const xtd::diagnostics::stack_frameget_frame (size_t index)
 Gets the specified stack frame. More...
 
const stack_frame_collectionget_frames () const
 Returns a copy of all stack frames in the current stack trace. More...
 
xtd::ustring to_string () const noexcept
 Builds a readable representation of the stack trace. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual 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
 Gets the type of the current instance. More...
 

Additional Inherited Members

- 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

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");
// Display the most recent function call.
stack_frame sf = st.get_frame(0);
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(" ... throwing exception to next level ...");
console::write_line("-------------------------------------------------\n");
throw e;
}
}
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_infotrue 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");
// Display the most recent function call.
stack_frame sf = st.get_frame(0);
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(" ... throwing exception to next level ...");
console::write_line("-------------------------------------------------\n");
throw e;
}
}
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
frameThe 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)

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

Parameters
exceptionThe 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_framesThe 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
exceptionThe exception object from which to construct the stack trace.
skip_framedThe 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_framesThe number of frames up the stack from which to start the trace.
need_file_infotrue 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");
// Display the most recent function call.
stack_frame sf = st.get_frame(0);
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(" ... throwing exception to next level ...");
console::write_line("-------------------------------------------------\n");
throw e;
}
}
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
exceptionThe exception object from which to construct the stack trace.
skip_framesThe number of frames up the stack from which to start the trace.
need_file_infotrue 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
exceptionThe exception object from which to construct the stack trace.
need_file_infotrue 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

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");
// Display the most recent function call.
stack_frame sf = st.get_frame(0);
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(" ... throwing exception to next level ...");
console::write_line("-------------------------------------------------\n");
throw e;
}
}

◆ get_frame()

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

Gets the specified stack frame.

Parameters
indexThe 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");
// Display the most recent function call.
stack_frame sf = st.get_frame(0);
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(" ... throwing exception to next level ...");
console::write_line("-------------------------------------------------\n");
throw e;
}
}
Remarks
Stack frames are numbered starting at 0, which is the last stack frame pushed.

◆ get_frames()

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

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
virtualnoexcept

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.

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: