profiler.hpp File Reference

Compile-time profiler instrumentation: Tracy zones, plots, messages and thread names, behind morph's own macro names. More...

Go to the source code of this file.

Macros
#define	MORPH_ZONE(name)
	Opens a profiler zone named name that ends with the enclosing scope. At most one per scope.
#define	MORPH_ZONE_TEXT(text)
	Attaches text to the enclosing scope's MORPH_ZONE; an empty text attaches nothing.
#define	MORPH_PLOT(name, value)
	Records value on the plot named name.
#define	MORPH_THREAD_NAME(name)
	Names the calling thread in the capture.
#define	MORPH_MESSAGE(text)
	Sends text to the capture's timeline as a message.

Detailed Description

Compile-time profiler instrumentation: Tracy zones, plots, messages and thread names, behind morph's own macro names.

Configure with -DMORPH_ENABLE_TRACY=ON and the macros below forward to Tracy (MORPH_TRACY_ENABLED is then defined on every target that links morph::morph). Otherwise each macro is a stub that names its arguments only inside decltype, an unevaluated operand: a disabled build evaluates nothing, warns about no unused argument, and needs no Tracy headers.

Why morph's names and not Tracy's

Lightweight defines stubs under Tracy's own names (ZoneScoped, ZoneScopedN, TracyPlot, ...) when its own Tracy option is off, and an application may include Lightweight and morph in one translation unit. Were morph to do the same, a build with one library's Tracy on and the other's off would have one header's stubs redefine the other's real macros. Every macro here is spelled MORPH_* and none of Tracy's names is defined.

One zone, one phase, one thread

A Tracy zone must begin and end on the same thread. A dispatch crosses threads – the caller, the model's strand, the callback executor – so each phase is its own zone on the thread that runs it, and the phases of one call are linked by writing session::Context::requestId as zone text (MORPH_ZONE_TEXT). No zone spans a hand-off, and none stays open across a co_await: a suspended coroutine's thread goes on to run other work, whose zones would then close out of order with the open one.

Every translation unit must agree

morph is header-only, so these macros change the bodies of inline functions. A program in which one translation unit sees MORPH_TRACY_ENABLED and another does not holds two different definitions of the same inline function, which is an ODR violation: the linker keeps one of them, silently. CMake consumers get agreement by construction, because the definition is an INTERFACE property of morph::morph. A build that does not use morph's CMake package must define MORPH_TRACY_ENABLED for all of its translation units or for none, and link exactly one TracyClient. MSVC and clang-cl turn a mismatch into a link error (detect_mismatch below); other toolchains do not detect it.

Definition in file profiler.hpp.

Macro Definition Documentation

MORPH_ZONE

#define MORPH_ZONE

(

name

)

Value:

static_cast<void>(::morph::profiler::detail::Unevaluated<decltype(name)>{})

Opens a profiler zone named name that ends with the enclosing scope. At most one per scope.

Parameters

name	A string literal: Tracy keeps a pointer to it for the life of the process.

Definition at line 118 of file profiler.hpp.

MORPH_ZONE_TEXT

#define MORPH_ZONE_TEXT

(

text

)

Value:

static_cast<void>(::morph::profiler::detail::Unevaluated<decltype(text)>{})

Attaches text to the enclosing scope's MORPH_ZONE; an empty text attaches nothing.

Only valid after a MORPH_ZONE in the same or an enclosing scope.

Parameters

text	Anything convertible to std::string_view; Tracy copies it. Not evaluated in a build without Tracy.

Definition at line 126 of file profiler.hpp.

MORPH_PLOT

#define MORPH_PLOT	(		name,
			value )

Value:

static_cast<void>(::morph::profiler::detail::Unevaluated<decltype(name), decltype(value)>{})

Records value on the plot named name.

Parameters

name	A string literal, the plot's identity in the capture.
value	An arithmetic value, recorded as a double. Not evaluated in a build without Tracy.

Definition at line 132 of file profiler.hpp.

MORPH_THREAD_NAME

#define MORPH_THREAD_NAME

(

name

)

Value:

static_cast<void>(::morph::profiler::detail::Unevaluated<decltype(name)>{})

Names the calling thread in the capture.

Parameters

name	A NUL-terminated string; Tracy copies it.

Definition at line 137 of file profiler.hpp.

MORPH_MESSAGE

#define MORPH_MESSAGE

(

text

)

Value:

static_cast<void>(::morph::profiler::detail::Unevaluated<decltype(text)>{})

Sends text to the capture's timeline as a message.

Parameters

text	Anything convertible to std::string_view; Tracy copies it. Not evaluated in a build without Tracy.

Definition at line 142 of file profiler.hpp.