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 Member Functions | List of all members
xtd::diagnostics::trace_source Class Reference

#include <trace_source.h>

Definition

Provides a set of methods and properties that enable applications to trace the execution of code and associate trace messages with their source.

Namespace
xtd::diagnostics
Library
xtd.core
Remarks
The trace_source class is used by applications to produce traces that can be associated with the application. trace_source provides tracing methods that allow you to easily trace events, trace data, and issue informational traces.
The trace_source class is identified by the name of a source, typically the name of the application. The trace messages coming from a particular component can be initiated by a particular trace source, allowing all messages coming from that component to be easily identified.
trace_source defines tracing methods but does not actually provide any specific mechanism for generating and storing tracing data. The tracing data is produced by trace listeners, which are plug-ins that can be loaded by trace sources.
You can customize the tracing output's target by adding or removing trace_istener instances to or from the collection stored in the trace_source::listeners property. By default, trace output is produced using an instance of the default_trace_listener class.
Note
Adding a trace listener to the 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 trace_source methods in try/catch blocks to detect and handle any exceptions from trace listeners.
Remarks
The source_switch class provides the means to dynamically control the tracing output. You can modify the value of the source switch without recompiling your application.
The trace_event_type enumeration is used to define the event type of the trace message. Trace filters use the trace_event_type to determine if a trace listener should produce the trace message.
The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the should_trace method on that filter to determine whether or not to produce the trace information.
The trace listeners use the values of the trace class properties indent, indent_size, and auto_flush to format trace output.

Public Member Functions

 trace_source (const xtd::ustring &name)
 Initializes a new instance of the Trace_Source class, using the specified name for the source. More...
 
 trace_source (const xtd::ustring &name, xtd::diagnostics::source_levels default_levels)
 Initializes a new instance of the Trace_Source class, using the specified name for the source. More...
 
void close ()
 Closes all the trace listeners in the trace listener collection. More...
 
void flush ()
 Flushes all the trace listeners in the trace listener collection. More...
 
xtd::diagnostics::trace_listener_collectionlisteners ()
 Gets the collection of trace listeners for the trace source. More...
 
void listeners (const xtd::diagnostics::trace_listener_collection &listeners)
 Sets the collection of trace listeners for the trace source. More...
 
const xtd::ustringname () const
 Gets the name of the trace source. More...
 
const xtd::diagnostics::source_switchsource_switch () const
 Gets the source switch value. More...
 
void source_switch (const xtd::diagnostics::source_switch &source_switch)
 Sets the source switch value. More...
 
template<typename object_t >
void trace_data (const xtd::diagnostics::trace_event_type &event_type, int32_t id, const object_t &data)
 Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data. More...
 
template<typename object_t >
void trace_data (const xtd::diagnostics::trace_event_type &event_type, int32_t id, const std::vector< object_t > &data)
 Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data. More...
 
void trace_event (const xtd::diagnostics::trace_event_type &event_type, int32_t id)
 Writes a trace event message to the trace listeners in the listeners collection using the specified event type and event identifier. More...
 
void trace_event (const xtd::diagnostics::trace_event_type &event_type, int32_t id, const xtd::ustring &message)
 Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier adn message. More...
 
template<typename ... objects>
void trace_event (const xtd::diagnostics::trace_event_type &event_type, int32_t id, const xtd::ustring &format, const objects &... args)
 Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier, and argument array and format. More...
 
void trace_information (const xtd::ustring &message)
 Writes an informational message to the trace listeners in the listeners collection using the specified message. More...
 
template<typename ... objects_t>
void trace_information (const xtd::ustring &format, const objects_t &... args)
 Writes an informational message to the trace listeners in the listeners collection using the specified object array and formatting information. More...
 
template<typename guid_t >
void trace_transfer (int32_t id, const xtd::ustring &message, const guid_t &related_activity_id)
 Writes a trace transfer message to the trace listeners in the listeners collection using the specified numeric identifier, message, and related activity identifier. 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...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. 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...
 

Constructor & Destructor Documentation

◆ trace_source() [1/2]

xtd::diagnostics::trace_source::trace_source ( const xtd::ustring name)
explicit

Initializes a new instance of the Trace_Source class, using the specified name for the source.

Parameters
nameThe name of the source (typically, the name of the application).

◆ trace_source() [2/2]

xtd::diagnostics::trace_source::trace_source ( const xtd::ustring name,
xtd::diagnostics::source_levels  default_levels 
)
explicit

Initializes a new instance of the Trace_Source class, using the specified name for the source.

Parameters
nameThe name of the source (typically, the name of the application).
default_levelA bitwise combination of the enumeration values that specifies the default source level at which to trace

Member Function Documentation

◆ close()

void xtd::diagnostics::trace_source::close ( )

Closes all the trace listeners in the trace listener collection.

Remarks
The close method calls the close method of each trace listener in the listeners collection.

◆ flush()

void xtd::diagnostics::trace_source::flush ( )

Flushes all the trace listeners in the trace listener collection.

Remarks
The flush method calls the flush method of each trace listener in the listeners collection.

◆ listeners() [1/2]

xtd::diagnostics::trace_listener_collection& xtd::diagnostics::trace_source::listeners ( )

Gets the collection of trace listeners for the trace source.

Returns
A trace_listener_collection that contains the active trace listeners associated with the source.
Remarks
Use this property to access and perform operations on the trace listeners.

◆ listeners() [2/2]

void xtd::diagnostics::trace_source::listeners ( const xtd::diagnostics::trace_listener_collection listeners)

Sets the collection of trace listeners for the trace source.

Parameters
listenersA trace_listener_collection that contains the active trace listeners associated with the source.
Remarks
Use this property to access and perform operations on the trace listeners.

◆ name()

const xtd::ustring& xtd::diagnostics::trace_source::name ( ) const

Gets the name of the trace source.

Returns
The name of the trace source.

◆ source_switch() [1/2]

const xtd::diagnostics::source_switch& xtd::diagnostics::trace_source::source_switch ( ) const

Gets the source switch value.

Returns
A SourceSwitch object representing the source switch value.
Remarks
The source_switch property allows the filtering of messages before the trace source calls the listeners.
The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the should_trace method of the source_switch to determine whether to proceed with the trace. If the call returns true, the listeners are called.

◆ source_switch() [2/2]

void xtd::diagnostics::trace_source::source_switch ( const xtd::diagnostics::source_switch source_switch)

Sets the source switch value.

Parameters
source_switchA SourceSwitch object representing the source switch value.
Remarks
The source_switch property allows the filtering of messages before the trace source calls the listeners.
The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the should_trace method of the source_switch to determine whether to proceed with the trace. If the call returns true, the listeners are called.

◆ trace_data() [1/2]

template<typename object_t >
void xtd::diagnostics::trace_source::trace_data ( const xtd::diagnostics::trace_event_type event_type,
int32_t  id,
const object_t &  data 
)
inline

Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.

Parameters
event_typeOne of the enumeration values that specifies the event type of the trace data.
idA numeric identifier for the event.
dataThe trace data.
Remarks
The trace_data method, like the trace_event method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace.
The trace_data method calls the source_switch::should_trace method of the source_switch object returned by the source_switch property. If should_trace returns true, trace_data calls the corresponding trace_data method on all listeners. Otherwise, trace_data returns without calling the listeners' methods.

◆ trace_data() [2/2]

template<typename object_t >
void xtd::diagnostics::trace_source::trace_data ( const xtd::diagnostics::trace_event_type event_type,
int32_t  id,
const std::vector< object_t > &  data 
)
inline

Writes trace data to the trace listeners in the Listeners collection using the specified event type, event identifier, and trace data.

Parameters
event_typeOne of the enumeration values that specifies the event type of the trace data.
idA numeric identifier for the event.
dataThe trace data.
Remarks
The trace_data method, like the trace_event method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace.
The trace_data method calls the source_switch::should_trace method of the source_switch object returned by the source_switch property. If should_trace returns true, trace_data calls the corresponding trace_data method on all listeners. Otherwise, trace_data returns without calling the listeners' methods.

◆ trace_event() [1/3]

void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type event_type,
int32_t  id 
)
inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type and event identifier.

Parameters
event_typeOne of the enumeration values that specifies the event type of the trace data.
idA numeric identifier for the event.
Remarks
The trace_event method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source.

◆ trace_event() [2/3]

void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type event_type,
int32_t  id,
const xtd::ustring message 
)
inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier adn message.

Parameters
event_typeOne of the enumeration values that specifies the event type of the trace data.
idA numeric identifier for the event.
messageThe trace message to write.

◆ trace_event() [3/3]

template<typename ... objects>
void xtd::diagnostics::trace_source::trace_event ( const xtd::diagnostics::trace_event_type event_type,
int32_t  id,
const xtd::ustring format,
const objects &...  args 
)
inline

Writes a trace event message to the trace listeners in the listeners collection using the specified event type, event identifier, and argument array and format.

Parameters
event_typeOne of the enumeration values that specifies the event type of the trace data.
idA numeric identifier for the event.
formatA composite format string that contains text intermixed with zero or more format items, which correspond to objects in the args array.
args...An object array containing zero or more objects to format.

◆ trace_information() [1/2]

void xtd::diagnostics::trace_source::trace_information ( const xtd::ustring message)

Writes an informational message to the trace listeners in the listeners collection using the specified message.

Parameters
messageThe informative message to write.
Remarks
The trace_information method provides an informational message intended to be read by users and not by tools.
trace_information(const std::dtring&, calls the trace_event(const trace_eventType&, Int32_t, const xtd::ustring&, ...objects_t) method, setting event_type to trace_event_type.Information and passing the message content as an object array with formatting information. The trace_event(const trace_event_type, Int32_t, xtd::ustring&) method in turn calls the trace_event(const trace_event_cache&, const xtd::ustring&, trace_event_type, Int32_t, const xtd::ustring&) method of each trace listener.

◆ trace_information() [2/2]

template<typename ... objects_t>
void xtd::diagnostics::trace_source::trace_information ( const xtd::ustring format,
const objects_t &...  args 
)
inline

Writes an informational message to the trace listeners in the listeners collection using the specified object array and formatting information.

Parameters
formatA composite format string that contains text intermixed with zero or more format items, which correspond to objects in the args array.
args...An array containing zero or more objects to format.
Remarks
The trace_information method provides an informational message intended to be read by users and not by tools.
trace_information(const std::dtring&, const Objects_t) calls the trace_event(const trace_eventType&, Int32_t, const xtd::ustring&, ...objects_t) method, setting event_type to trace_event_type.Information and passing the message content as an object array with formatting information. The trace_event(const trace_event_type, Int32_t, xtd::ustring&, ...objects_t) method in turn calls the trace_event(const trace_event_cache&, const xtd::ustring&, trace_event_type, Int32_t, const xtd::ustring&, ...objects_t) method of each trace listener.

◆ trace_transfer()

template<typename guid_t >
void xtd::diagnostics::trace_source::trace_transfer ( int32_t  id,
const xtd::ustring message,
const guid_t &  related_activity_id 
)
inline

Writes a trace transfer message to the trace listeners in the listeners collection using the specified numeric identifier, message, and related activity identifier.

Parameters
idA numeric identifier for the event.
messageThe trace message to write.
related_activity_idA structure that identifies the related activity.
Remarks
The trace_transfer method calls the trace_transfer method of each trace listener in the listeners property to write the trace information. The default trace_transfer method in the base trace_listener class calls the trace_listener::trace_event(const trace_event_cache&, const xtd::ustring&, trace_svent_type, Int32_t, const xtd::ustring&) method to process the call, setting event_type to trace_event_type::transfer and appending a string representation of the related_activity_id GUID to message.
trace_transfer is intended to be used with the logical operations of a correlation_manager. The related_activity_id parameter relates to the activity_id property of a correlation_manager object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the trace_transfer method. The trace_transfer call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities.

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