Logging, the profiler and allocation hooks. More...

Classes
struct	tachyon::Diagnostics::LogCategory
	A subsystem's log category. More...
struct	tachyon::Diagnostics::LogArg
	One argument. More...
union	tachyon::Diagnostics::LogArg::[union].__unnamed0__
class	tachyon::TrackingAllocator
	Allocation hooks that count what is live, for finding leaks. More...
struct	tachyon::AllocationHooks
	Memory functions a host gives the library, for the allocations that can be routed: Vulkan objects, VMA, vk-bootstrap and SDL. More...
struct	tachyon::Diagnostics::ProfileSample
	One finalized node, depth-first. Durations are windowed averages (~4 updates/s). More...
class	tachyon::Diagnostics::ScopedTimer
	Times its own lifetime as a scope; a disabled profiler costs one branch. More...
struct	tachyon::Diagnostics::ScopeLocation
	Per-call-site descriptor, static at each TACHYON_PROFILE_SCOPE site. More...
struct	tachyon::Diagnostics::LogRecord
	One message as sinks and CopyRecentLogRecords see it. More...

Typedefs
using	tachyon::Diagnostics::LogSinkFn = void ()(const LogRecord& record, void context)
	A log sink. Sinks run on the emitting thread, under the logger's lock.

Enumerations
enum class	tachyon::Diagnostics::LogSeverity : uint8_t { tachyon::Diagnostics::LogSeverity::Trace = 0 , tachyon::Diagnostics::LogSeverity::Debug , tachyon::Diagnostics::LogSeverity::Info , tachyon::Diagnostics::LogSeverity::Warning , tachyon::Diagnostics::LogSeverity::Error , tachyon::Diagnostics::LogSeverity::Critical }

Functions
const char *	tachyon::Diagnostics::LogSeverityName (LogSeverity severity)
constexpr LogCategory	tachyon::Diagnostics::MakeLogCategory (std::string_view staticName)
	A category named staticName, which must be a static string.
template<typename T>
LogArg	tachyon::Diagnostics::MakeLogArg (const T &value)
std::string_view	tachyon::Diagnostics::LogArgText (const LogRecord &record, const LogArg &arg)
size_t	tachyon::Diagnostics::FormatLogMessage (const LogRecord &record, std::span< char > out)
	Writes the template with its arguments substituted, NUL-terminated and truncated to out.
void	tachyon::Diagnostics::SetLogConsoleOutput (bool enabled)
	Turns the built-in stdout/stderr/debugger sink on or off (on by default). [AnyThread].
bool	tachyon::Diagnostics::AddLogSink (LogSinkFn sink, void *context)
	Registers sink, called with every record and context.
void	tachyon::Diagnostics::RemoveLogSink (LogSinkFn sink, void *context)
	Unregisters a sink added with the same sink and context. [MainThread].
void	tachyon::Diagnostics::LogMessage (LogCategory category, LogSeverity severity, std::string_view messageTemplate, std::span< const LogArg > args, const char *file="", uint32_t line=0)
	Emits one record. Prefer the TACHYON_LOG_* macros, which add the source location. [AnyThread].
void	tachyon::Diagnostics::ReportMisuse (LogCategory category, const char *message)
	API misuse (an unbalanced Begin/End, a call outside its frame, ...) is reported, not fatal: the caller recovers and the app carries on.
void	tachyon::Diagnostics::ResetMisuseReports ()
	Lets every misuse be reported again (tests). [AnyThread].
uint64_t	tachyon::Diagnostics::LatestLogSequence ()
	Sequence number of the newest record (0 before the first). [AnyThread].
uint32_t	tachyon::Diagnostics::CopyRecentLogRecords (std::span< LogRecord > out)
	Copies up to out.size() of the most recent records, oldest first.
template<typename... Args>
void	tachyon::Diagnostics::Log (LogCategory category, LogSeverity severity, const char *file, uint32_t line, std::string_view messageTemplate, const Args &... args)
	Emits a record with args (at most kMaxLogArgs) for the {} in messageTemplate; what the TACHYON_LOG_* macros call.
ProfilerCollector &	tachyon::Diagnostics::MainThreadCollector ()
bool	tachyon::Diagnostics::IsProfilingEnabled ()
void	tachyon::Diagnostics::SetProfilingEnabled (bool enabled)
void	tachyon::Diagnostics::Reset (ProfilerCollector &collector)
	Discards all nodes and history; cached scope sites re-resolve.
void	tachyon::Diagnostics::EnterScope (ProfilerCollector &collector, uint64_t nameHash, const char name, bool isWait=false, const char file="", int line=0) noexcept
	Uncached scope entry, for direct use and tests; pair with ExitScope.
std::span< const ProfileSample >	tachyon::Diagnostics::LastFrameSamples (const ProfilerCollector &collector)
	The nodes of the last finalized frame, depth-first. Valid until the next EndFrame.
double	tachyon::Diagnostics::LastFrameTotalMs (const ProfilerCollector &collector)
	Smoothed total of the root scope(s): the frame total, in milliseconds.

Variables
constexpr int	tachyon::Diagnostics::kMaxLogArgs = 4
constexpr int	tachyon::Diagnostics::kLogTextCapacity = 384
	bytes shared by a record's text arguments
constexpr int	tachyon::Diagnostics::kLogRingCapacity = 1024
constexpr int	tachyon::Diagnostics::kMaxLogSinks = 8
void	tachyon::Diagnostics::SetMinimumLogSeverity (LogSeverity severity)
	Records below the minimum severity are dropped before any work is done.
LogSeverity	tachyon::Diagnostics::GetMinimumLogSeverity ()
	Records below the minimum severity are dropped before any work is done.
void	tachyon::Diagnostics::BeginFrame (ProfilerCollector &collector)
	Frame boundaries: call once each, around all scopes for the frame.
void	tachyon::Diagnostics::EndFrame (ProfilerCollector &collector)
	Frame boundaries: call once each, around all scopes for the frame.
void	tachyon::Diagnostics::EnterScope (ProfilerCollector &collector, ScopeLocation &loc) noexcept
	Cached scope entry / exit, as the macros use.
void	tachyon::Diagnostics::ExitScope (ProfilerCollector &collector) noexcept
	Cached scope entry / exit, as the macros use.

Detailed Description

Logging, the profiler and allocation hooks.

Typedef Documentation

◆ LogSinkFn

using tachyon::Diagnostics::LogSinkFn = void (*)(const LogRecord& record, void* context)

#include <gui_core/diagnostics/gui_logging.h>

A log sink. Sinks run on the emitting thread, under the logger's lock.

Enumeration Type Documentation

◆ LogSeverity

enum class tachyon::Diagnostics::LogSeverity : uint8_t

strong

#include <gui_core/diagnostics/gui_logging.h>

Enumerator
Trace
Debug
Info
Warning
Error
Critical

Function Documentation

◆ LogSeverityName()

const char * tachyon::Diagnostics::LogSeverityName ( LogSeverity severity )

#include <gui_core/diagnostics/gui_logging.h>

◆ MakeLogCategory()

LogCategory tachyon::Diagnostics::MakeLogCategory ( std::string_view staticName )

constexpr

#include <gui_core/diagnostics/gui_logging.h>

A category named staticName, which must be a static string.

◆ MakeLogArg()

template<typename T>

LogArg tachyon::Diagnostics::MakeLogArg ( const T & value )

#include <gui_core/diagnostics/gui_logging.h>

◆ LogArgText()

std::string_view tachyon::Diagnostics::LogArgText	(	const LogRecord &	record,
		const LogArg &	arg )

#include <gui_core/diagnostics/gui_logging.h>

◆ FormatLogMessage()

size_t tachyon::Diagnostics::FormatLogMessage	(	const LogRecord &	record,
		std::span< char >	out )

#include <gui_core/diagnostics/gui_logging.h>

Writes the template with its arguments substituted, NUL-terminated and truncated to out.

Returns the length written (excluding the NUL).

◆ SetMinimumLogSeverity()

void tachyon::Diagnostics::SetMinimumLogSeverity ( LogSeverity severity )

#include <gui_core/diagnostics/gui_logging.h>

Records below the minimum severity are dropped before any work is done.

[AnyThread]

◆ GetMinimumLogSeverity()

LogSeverity tachyon::Diagnostics::GetMinimumLogSeverity ( )

#include <gui_core/diagnostics/gui_logging.h>

Records below the minimum severity are dropped before any work is done.

[AnyThread]

◆ SetLogConsoleOutput()

void tachyon::Diagnostics::SetLogConsoleOutput ( bool enabled )

#include <gui_core/diagnostics/gui_logging.h>

Turns the built-in stdout/stderr/debugger sink on or off (on by default). [AnyThread].

◆ AddLogSink()

bool tachyon::Diagnostics::AddLogSink	(	LogSinkFn	sink,
		void *	context )

#include <gui_core/diagnostics/gui_logging.h>

Registers sink, called with every record and context.

False when this sink and context are already registered or kMaxLogSinks are in use. [MainThread]

◆ RemoveLogSink()

void tachyon::Diagnostics::RemoveLogSink	(	LogSinkFn	sink,
		void *	context )

#include <gui_core/diagnostics/gui_logging.h>

Unregisters a sink added with the same sink and context. [MainThread].

◆ LogMessage()

void tachyon::Diagnostics::LogMessage	(	LogCategory	category,
		LogSeverity	severity,
		std::string_view	messageTemplate,
		std::span< const LogArg >	args,
		const char *	file = "",
		uint32_t	line = 0 )

#include <gui_core/diagnostics/gui_logging.h>

Emits one record. Prefer the TACHYON_LOG_* macros, which add the source location. [AnyThread].

◆ ReportMisuse()

void tachyon::Diagnostics::ReportMisuse	(	LogCategory	category,
		const char *	message )

#include <gui_core/diagnostics/gui_logging.h>

API misuse (an unbalanced Begin/End, a call outside its frame, ...) is reported, not fatal: the caller recovers and the app carries on.

Logged as an error once per message, keyed by its address (pass a string literal), as a mistake in GUI code likely repeats every frame. [AnyThread]

◆ ResetMisuseReports()

void tachyon::Diagnostics::ResetMisuseReports ( )

#include <gui_core/diagnostics/gui_logging.h>

Lets every misuse be reported again (tests). [AnyThread].

◆ LatestLogSequence()

uint64_t tachyon::Diagnostics::LatestLogSequence ( )

#include <gui_core/diagnostics/gui_logging.h>

Sequence number of the newest record (0 before the first). [AnyThread].

◆ CopyRecentLogRecords()

uint32_t tachyon::Diagnostics::CopyRecentLogRecords ( std::span< LogRecord > out )

#include <gui_core/diagnostics/gui_logging.h>

Copies up to out.size() of the most recent records, oldest first.

Returns the number copied. [AnyThread]

◆ Log()

template<typename... Args>

void tachyon::Diagnostics::Log	(	LogCategory	category,
		LogSeverity	severity,
		const char *	file,
		uint32_t	line,
		std::string_view	messageTemplate,
		const Args &...	args )

#include <gui_core/diagnostics/gui_logging.h>

Emits a record with args (at most kMaxLogArgs) for the {} in messageTemplate; what the TACHYON_LOG_* macros call.

[AnyThread]

◆ MainThreadCollector()

ProfilerCollector & tachyon::Diagnostics::MainThreadCollector ( )

#include <gui_core/diagnostics/gui_profiler.h>

◆ IsProfilingEnabled()

bool tachyon::Diagnostics::IsProfilingEnabled ( )

#include <gui_core/diagnostics/gui_profiler.h>

◆ SetProfilingEnabled()

void tachyon::Diagnostics::SetProfilingEnabled ( bool enabled )

#include <gui_core/diagnostics/gui_profiler.h>

◆ BeginFrame()

void tachyon::Diagnostics::BeginFrame ( ProfilerCollector & collector )

#include <gui_core/diagnostics/gui_profiler.h>

Frame boundaries: call once each, around all scopes for the frame.

◆ EndFrame()

void tachyon::Diagnostics::EndFrame ( ProfilerCollector & collector )

#include <gui_core/diagnostics/gui_profiler.h>

Frame boundaries: call once each, around all scopes for the frame.

◆ Reset()

void tachyon::Diagnostics::Reset ( ProfilerCollector & collector )

#include <gui_core/diagnostics/gui_profiler.h>

Discards all nodes and history; cached scope sites re-resolve.

◆ EnterScope() [1/2]

void tachyon::Diagnostics::EnterScope	(	ProfilerCollector &	collector,
		ScopeLocation &	loc )

noexcept

#include <gui_core/diagnostics/gui_profiler.h>

Cached scope entry / exit, as the macros use.

loc is normally a static ScopeLocation; its strings must outlive the collector.

◆ ExitScope()

void tachyon::Diagnostics::ExitScope ( ProfilerCollector & collector )

noexcept

#include <gui_core/diagnostics/gui_profiler.h>

Cached scope entry / exit, as the macros use.

loc is normally a static ScopeLocation; its strings must outlive the collector.

◆ EnterScope() [2/2]

void tachyon::Diagnostics::EnterScope	(	ProfilerCollector &	collector,
		uint64_t	nameHash,
		const char *	name,
		bool	isWait = false,
		const char *	file = "",
		int	line = 0 )

noexcept

#include <gui_core/diagnostics/gui_profiler.h>

Uncached scope entry, for direct use and tests; pair with ExitScope.

◆ LastFrameSamples()

std::span< const ProfileSample > tachyon::Diagnostics::LastFrameSamples ( const ProfilerCollector & collector )

#include <gui_core/diagnostics/gui_profiler.h>

The nodes of the last finalized frame, depth-first. Valid until the next EndFrame.

◆ LastFrameTotalMs()

double tachyon::Diagnostics::LastFrameTotalMs ( const ProfilerCollector & collector )

#include <gui_core/diagnostics/gui_profiler.h>

Smoothed total of the root scope(s): the frame total, in milliseconds.

Variable Documentation

◆ kMaxLogArgs

int tachyon::Diagnostics::kMaxLogArgs = 4

inlineconstexpr

#include <gui_core/diagnostics/gui_logging.h>

◆ kLogTextCapacity

int tachyon::Diagnostics::kLogTextCapacity = 384

inlineconstexpr

#include <gui_core/diagnostics/gui_logging.h>

bytes shared by a record's text arguments

◆ kLogRingCapacity

int tachyon::Diagnostics::kLogRingCapacity = 1024

inlineconstexpr

#include <gui_core/diagnostics/gui_logging.h>

◆ kMaxLogSinks

int tachyon::Diagnostics::kMaxLogSinks = 8

inlineconstexpr

#include <gui_core/diagnostics/gui_logging.h>

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ LogSinkFn

Enumeration Type Documentation

◆ LogSeverity

Function Documentation

◆ LogSeverityName()

◆ MakeLogCategory()

◆ MakeLogArg()

◆ LogArgText()

◆ FormatLogMessage()

◆ SetMinimumLogSeverity()

◆ GetMinimumLogSeverity()

◆ SetLogConsoleOutput()

◆ AddLogSink()

◆ RemoveLogSink()

◆ LogMessage()

◆ ReportMisuse()

◆ ResetMisuseReports()

◆ LatestLogSequence()

◆ CopyRecentLogRecords()

◆ Log()

◆ MainThreadCollector()

◆ IsProfilingEnabled()

◆ SetProfilingEnabled()

◆ BeginFrame()

◆ EndFrame()

◆ Reset()

◆ EnterScope() [1/2]

◆ ExitScope()

◆ EnterScope() [2/2]

◆ LastFrameSamples()

◆ LastFrameTotalMs()

Variable Documentation

◆ kMaxLogArgs

◆ kLogTextCapacity

◆ kLogRingCapacity

◆ kMaxLogSinks