TfDiagnosticTrap Class Reference

A scoped, stack-based mechanism for intercepting and examining diagnostics issued on the current thread. More...

#include <diagnosticTrap.h>

Public Member Functions
	TfDiagnosticTrap (const TfDiagnosticTrap &)=delete
TfDiagnosticTrap &	operator= (const TfDiagnosticTrap &)=delete
TF_API	TfDiagnosticTrap ()
	Construct a trap and install it as the active interceptor on the current thread.
TF_API	~TfDiagnosticTrap ()
	Destroy the trap, re-posting any diagnostics not explicitly discarded by calls to the Clear or Erase families of member functions.
TF_API void	Dismiss ()
	Re-post any uncleared diagnostics and deactivate the trap; called automatically on destruction if not called explicitly.
TF_API void	Clear ()
	Discard all captured diagnostics. They will not be re-posted.
TF_API void	ClearErrors ()
	Discard all captured errors. They will not be re-posted.
TF_API void	ClearWarnings ()
	Discard all captured warnings. They will not be re-posted.
TF_API void	ClearStatuses ()
	Discard all captured status messages. They will not be re-posted.
template<class Predicate >
size_t	EraseMatching (Predicate &&pred)
	Erase all captured diagnostics for which pred returns true, preserving the relative order of the remaining diagnostics.
TF_API bool	IsClean () const
	Return true if no diagnostics have been captured.
TF_API bool	HasErrors () const
	Return true if any errors have been captured.
TF_API bool	HasWarnings () const
	Return true if any warnings have been captured.
TF_API bool	HasStatuses () const
	Return true if any status messages have been captured.
template<class Predicate >
bool	HasAnyMatching (Predicate &&pred) const
	Invoke pred on the captured diagnostics in order, returning true as soon as pred returns true for any of them.
template<class Predicate >
bool	HasAllMatching (Predicate &&pred) const
	Invoke pred on the captured diagnostics in order, returning false as soon as pred returns false for any of them.
template<class Predicate >
size_t	CountMatching (Predicate &&pred) const
	Return the number of captured diagnostics for which pred returns true.
TF_API std::vector< TfError > const &	GetErrors () const
	Return the captured errors.
TF_API std::vector< TfWarning > const &	GetWarnings () const
	Return the captured warnings.
TF_API std::vector< TfStatus > const &	GetStatuses () const
	Return the captured status messages.
template<class Fn >
void	ForEach (Fn &&fn) const
	Invoke fn for each captured diagnostic in the order they were received.
TF_API TfDiagnosticTransport	Transport ()
	Move all accumulated diagnostics into a TfDiagnosticTransport, leaving this trap active but empty.

Friends
class	TfDiagnosticMgr

Detailed Description

A scoped, stack-based mechanism for intercepting and examining diagnostics issued on the current thread.

When a TfDiagnosticTrap is active, any TfError, TfWarning, or TfStatus reported on the current thread is captured by the trap rather than being forwarded to registered TfDiagnosticMgr delegates or reported. Traps nest: if multiple traps are active on the same thread, the innermost trap captures all diagnostics.

Captured diagnostics may be inspected at any time during the trap's lifetime. On destruction, any diagnostics not explicitly cleared are re-posted, letting them propagate to the next enclosing trap or to diagnostic delegates.

To discard captured diagnostics, call Clear(), ClearErrors(), ClearWarnings(), ClearStatuses(), or EraseMatching() before the trap is destroyed.

Example usage in a unit test:

TfDiagnosticTrap trap;
DoSomethingExpectedToWarn();
TF_AXIOM(trap.HasWarnings());
trap.ClearWarnings();
// warnings are discarded; other diagnostics (if any) will re-report on
// destruction

Note

TfDiagnosticTrap operates at report time, not at raise time. When no TfErrorMark is active, errors are reported immediately and will be captured by the active trap. However, when a TfErrorMark is active on the current thread, errors are accumulated in the mark rather than immediately reported, and will not be captured by the trap. Warnings and status messages are always reported immediately and therefore are not affected by this distinction.

Definition at line 60 of file diagnosticTrap.h.

Constructor & Destructor Documentation

TfDiagnosticTrap()

TF_API TfDiagnosticTrap

(

)

Construct a trap and install it as the active interceptor on the current thread.

~TfDiagnosticTrap()

TF_API ~TfDiagnosticTrap

(

)

Destroy the trap, re-posting any diagnostics not explicitly discarded by calls to the Clear or Erase families of member functions.

Member Function Documentation

Clear()

TF_API void Clear

(

)

Discard all captured diagnostics. They will not be re-posted.

ClearErrors()

TF_API void ClearErrors

(

)

Discard all captured errors. They will not be re-posted.

ClearStatuses()

TF_API void ClearStatuses

(

)

Discard all captured status messages. They will not be re-posted.

ClearWarnings()

TF_API void ClearWarnings

(

)

Discard all captured warnings. They will not be re-posted.

CountMatching()

size_t CountMatching ( Predicate &&  pred ) const

inline

Return the number of captured diagnostics for which pred returns true.

pred may accept any subset of TfError, TfWarning, and TfStatus, or TfDiagnosticBase const& to test all types uniformly. Diagnostics whose type pred cannot accept are not counted.

Definition at line 191 of file diagnosticTrap.h.

Dismiss()

TF_API void Dismiss

(

)

Re-post any uncleared diagnostics and deactivate the trap; called automatically on destruction if not called explicitly.

EraseMatching()

size_t EraseMatching ( Predicate &&  pred )

inline

Erase all captured diagnostics for which pred returns true, preserving the relative order of the remaining diagnostics.

Return the number of diagnostics erased. Erased diagnostics will not be re-posted. The passed pred may accept any subset of TfError, TfWarning, and TfStatus. Diagnostics whose type pred cannot accept are left untouched. The pred may also accept TfDiagnosticBase const & to match against all types uniformly. This is safe to call during ForEach iteration.

Definition at line 98 of file diagnosticTrap.h.

ForEach()

void ForEach ( Fn &&  fn ) const

inline

Invoke fn for each captured diagnostic in the order they were received.

fn may be a callable taking TfDiagnosticBase const & to handle all diagnostic types uniformly, or a TfOverloads visitor with overloads for any subset of TfError, TfWarning, and TfStatus - diagnostics whose type fn cannot accept are silently skipped. A snapshot of the current diagnostics is taken before iteration so it is safe to call mutators like EraseMatching or Clear() from within fn.

Definition at line 220 of file diagnosticTrap.h.

GetErrors()

TF_API std::vector< TfError > const & GetErrors

(

)

const

Return the captured errors.

GetStatuses()

TF_API std::vector< TfStatus > const & GetStatuses

(

)

const

Return the captured status messages.

GetWarnings()

TF_API std::vector< TfWarning > const & GetWarnings

(

)

const

Return the captured warnings.

HasAllMatching()

bool HasAllMatching ( Predicate &&  pred ) const

inline

Invoke pred on the captured diagnostics in order, returning false as soon as pred returns false for any of them.

pred may accept any subset of TfError, TfWarning, and TfStatus, or TfDiagnosticBase const & to test all types uniformly. The diagnostic types that pred accepts defines the domain that HasAllMatching() operates on. For example, a call like:

bool hasOnlyDeprecationWarnings =
    trap.HasAllMatching([](TfWarning const &w) {
        return TfStringContains(w.GetCommentary(), "deprecated");
    });

Returns true if all the trapped warnings contain "deprecated" in their commentaries regardless of whether or not the trap contains errors or status messages. Pass a predicate that accepts all diagnostic types to consider their presence not-matching:

bool hasOnlyWarningsOfDeprecation =
    trap.HasAllMatching(TfOverloads {
        [](TfWarning const &w) {
            return TfStringContains(w.GetCommentary(), "deprecated");
        },
        [](TfDiagnosticBase const &) {
            return false;
        }
    });

Return true vacuously if pred is not invoked.

Definition at line 176 of file diagnosticTrap.h.

HasAnyMatching()

bool HasAnyMatching ( Predicate &&  pred ) const

inline

Invoke pred on the captured diagnostics in order, returning true as soon as pred returns true for any of them.

pred may accept any subset of TfError, TfWarning, and TfStatus, or TfDiagnosticBase const & to test all types uniformly. Diagnostics whose type pred cannot accept are considered not matching.

Definition at line 136 of file diagnosticTrap.h.

HasErrors()

TF_API bool HasErrors

(

)

const

Return true if any errors have been captured.

HasStatuses()

TF_API bool HasStatuses

(

)

const

Return true if any status messages have been captured.

HasWarnings()

TF_API bool HasWarnings

(

)

const

Return true if any warnings have been captured.

IsClean()

TF_API bool IsClean

(

)

const

Return true if no diagnostics have been captured.

Transport()

TF_API TfDiagnosticTransport Transport

(

)

Move all accumulated diagnostics into a TfDiagnosticTransport, leaving this trap active but empty.

The transport can be used to re-post the diagnostics on another thread. This is analogous to TfErrorMark::Transport().

Friends And Related Function Documentation

TfDiagnosticMgr

friend class TfDiagnosticMgr

friend

Definition at line 233 of file diagnosticTrap.h.

---

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

• pxr/base/tf/diagnosticTrap.h