debug

Definition

Provides a set of methods and properties that help you debug the execution of your code.

Remarks

You can use the properties and methods in the xtd_diagnostics_debug to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system.

This class provides methods to display an assert dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: xtd_diagnostics_debug_write, xtd_diagnostics_debug_write_line, xtd_diagnostics_debug_write_if, and xtd_diagnostics_debug_write_line_if.

The xtd_boolean_switch and xtd_trace_switch classes provide means to dynamically control the tracing output. You can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch, see the xtd_switch class and the xtd_trace_switches topic.

You can customize the tracing output's target by adding xtd_trace_listener instances to or removing instances from the xtd_diagnostics_debug_listeners collection. The xtd_diagnostics_debug_listeners collection is shared by both the xtd_diagnostics_debug and the xtd_trace; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the xtd_default_trace_listener class.

Note

Adding a trace listener to the xtd_diagnostics_debug_listeners collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the debug methods in try/catch blocks to detect and handle any exceptions from trace listeners.

Remarks

You can modify the level of indentation using the xtd_diagnostics_debug_indent method or the xtd_diagnostics_debug_indent_level property. To modify the indent spacing, use the xtd_diagnostics_debug_indent_size property. You can specify whether to automatically flush the output buffer after each write by setting the xtd_diagnostics_debug_auto_flush property to true.

The debug class provides properties to get or set the level of indent, the xtd_diagnostics_debug_indent_size, and whether to xtd_diagnostics_debug_auto_flush after each write.

You must enable debug mode to use a trace listener. The syntax is compiler specific. If you use other than cmake to manage your build, refer to the documentation of your build manager. To enable debug mode with cmake, add the add_definitions(-DDEBUG) command line in the CMakeLists.txt of your project, or you can add #define DEBUG to the top of your file.

To activate your code if DEBUG is defined, you must enclose calls to the methods of Debug in an #if defined(DEBUG) ... #endif block, and add the /DDEBUG option to the compiler command line or add #define DEBUG to the file.

Examples

The following example uses debug to indicate the beginning and the end of a program's execution. The example also uses the debug::indent and debug::unindent methods to distinguish the tracing output.

Properties
bool	xtd_diagnostics_debug_get_auto_flush ()
	Gets whether xtd_diagnostics_debug_flush should be called on the xtd_diagnostics_debug_Listeners after every write. More...
void	xtd_diagnostics_debug_set_auto_flush (bool value)
	Sets whether xtd_diagnostics_debug_flush should be called on the xtd_diagnostics_debug_Listeners after every write. More...
uint32_t	xtd_diagnostics_debug_get_indent_level ()
	Gets the indent level. More...
void	xtd_diagnostics_debug_set_indent_level (uint32_t indent_level)
	Sets the indent level. More...
uint32_t	xtd_diagnostics_debug_get_indent_size ()
	Gets the number of spaces in an indent. More...
void	xtd_diagnostics_debug_set_indent_size (uint32_t indent_size)
	Sets the number of spaces in an indent. More...

Methods
inline_ void	xtd_diagnostics_debug_write (const char *message, const char *category)
	Writes a category name and message to the trace listeners in the listeners collection. More...
inline_ void	xtd_diagnostics_debug_write_if (bool condition, const char *message, const char *category)
	Writes a category name and message to the trace listeners in the Listeners collection if a condition is true. More...
inline_ void	xtd_diagnostics_debug_write_line (const char *message, const char *category)
	Writes a category name and message followed by a line terminator to the trace listeners in the listeners collection. More...
inline_ void	xtd_diagnostics_debug_write_line_if (bool condition, const char *message, const char *category)
	Writes a category name and message followed by a line terminator to the trace listeners in the Listeners collection if a condition is true. More...

Function Documentation

xtd_diagnostics_debug_get_auto_flush()

bool xtd_diagnostics_debug_get_auto_flush

(

)

Gets whether xtd_diagnostics_debug_flush should be called on the xtd_diagnostics_debug_Listeners after every write.

Returns

true if xtd_diagnostics_debug_flush is called on the xtd_diagnostics_debug_listeners after every write; otherwise, false.

Library

xtdc.core

Remarks

The default is false.

Flushing the stream will not flush its underlying encoder unless you explicitly call xtd_diagnostics_debug_flush or xtd_diagnostics_debug_close. Setting xtd_diagnostics_debug_auto_flush to true means that data will be flushed from the buffer to the stream.

xtd_diagnostics_debug_get_indent_level()

uint32_t xtd_diagnostics_debug_get_indent_level

(

)

Gets the indent level.

Returns

The indent level. The default is zero.

Remarks

The xtd::diagnostics::debug::indent_level property represents the number of times the indent of size xtd::diagnostics::debug::indent_size is applied. This property is stored on per-thread/per-request basis.

xtd_diagnostics_debug_get_indent_size()

uint32_t xtd_diagnostics_debug_get_indent_size

(

)

Gets the number of spaces in an indent.

Returns

The number of spaces in an indent. The default is four.

Remarks

A xtd::diagnostics::ostream_trace_listener interprets this number as spaces. An xtd::diagnostics::event_log_trace_listener ignores this value.

xtd_diagnostics_debug_set_auto_flush()

void xtd_diagnostics_debug_set_auto_flush

(

bool

value

)

Sets whether xtd_diagnostics_debug_flush should be called on the xtd_diagnostics_debug_Listeners after every write.

Parameters

auto_flush

true if xtd_diagnostics_debug_flush is called on the xtd_diagnostics_debug_listeners after every write; otherwise, false.

Library

xtdc.core

Remarks

The default is false.

Flushing the stream will not flush its underlying encoder unless you explicitly call xtd_diagnostics_debug_flush or xtd_diagnostics_debug_close. Setting xtd_diagnostics_debug_auto_flush to true means that data will be flushed from the buffer to the stream.

xtd_diagnostics_debug_set_indent_level()

void xtd_diagnostics_debug_set_indent_level

(

uint32_t

indent_level

)

Sets the indent level.

Parameters

indent_level

The indent level. The default is zero.

Remarks

The xtd::diagnostics::debug::indent_level property represents the number of times the indent of size xtd::diagnostics::debug::indent_size is applied. This property is stored on per-thread/per-request basis.

xtd_diagnostics_debug_set_indent_size()

void xtd_diagnostics_debug_set_indent_size

(

uint32_t

indent_size

)

Sets the number of spaces in an indent.

Parameters

indent_size

The number of spaces in an indent. The default is four.

Remarks

A xtd::diagnostics::ostream_trace_listener interprets this number as spaces. An xtd::diagnostics::event_log_trace_listener ignores this value.

xtd_diagnostics_debug_write()

inline_ void xtd_diagnostics_debug_write	(	const char *	message,
		const char *	category
	)

Writes a category name and message to the trace listeners in the listeners collection.

Parameters

message	A message to write.
category	A category name used to organize the output. If the value is NULL, this is equivalent to no category.

Library

xtdc.core

Remarks

By default, the output is written to an instance of default_trace_listener.

Use the category parameter to group output messages.

This method calls the write method of the trace listener.

xtd_diagnostics_debug_write_if()

inline_ void xtd_diagnostics_debug_write_if	(	bool	condition,
		const char *	message,
		const char *	category
	)

Writes a category name and message to the trace listeners in the Listeners collection if a condition is true.

Parameters

condition	true to cause a message to be written; otherwise, false.
message	A message to write.
category	A category name used to organize the output. If the value is NULL, this is equivalent to no category.

Library

xtdc.core

Remarks

By default, the output is written to an instance of default_trace_listener.

This method calls the write method of the trace listener.

xtd_diagnostics_debug_write_line()

inline_ void xtd_diagnostics_debug_write_line	(	const char *	message,
		const char *	category
	)

Writes a category name and message followed by a line terminator to the trace listeners in the listeners collection.

Parameters

message	A message to write.
category	A category name used to organize the output. If the value is NULL, this is equivalent to no category.

Library

xtdc.core

Remarks

By default, the output is written to an instance of default_trace_listener.

Use the category parameter to group output messages.

This method calls the write method of the trace listener.

xtd_diagnostics_debug_write_line_if()

inline_ void xtd_diagnostics_debug_write_line_if	(	bool	condition,
		const char *	message,
		const char *	category
	)

Writes a category name and message followed by a line terminator to the trace listeners in the Listeners collection if a condition is true.

Parameters

condition	true to cause a message to be written; otherwise, false.
message	A message to write.
category	A category name used to organize the output. If the value is NULL, this is equivalent to no category.

Library

xtdc.core

Remarks

By default, the output is written to an instance of default_trace_listener.

This method calls the write method of the trace listener.