uni20::TaskRegistryDebug Class Reference

Tracks coroutine and epoch-context lifecycle events in debug builds. More...

#include <task_registry_debug.hpp>

Classes
struct	CoroutineExceptionDiagnosticsOptions
	Runtime policy for diagnostics captured when an exception escapes a coroutine. More...
struct	DiagnosticsServiceOptions
	Options for the opt-in background DAG diagnostics service. More...
struct	GraphvizDumpOptions
	File-output options for Graphviz DAG dumps. More...

Public Types
enum class	DumpMode { None , Basic , Full }
	Verbosity levels for registry dump output. More...
enum class	EpochTaskRole { Reader , Writer }
	Role of a coroutine relative to an epoch context. More...
using	GraphDiagnostics = TaskRegistryGraphDiagnostics
	Structured async DAG diagnostic result type.
using	GraphSnapshot = TaskRegistryGraphSnapshot
	Structured async DAG snapshot type.
using	StacktraceOptions = TaskRegistryStacktraceOptions
	Runtime controls for stacktrace formatting in debug output.
enum class	TaskState {   Constructed , Running , Suspended , Failed ,   Leaked }
	Logical lifecycle states tracked for each coroutine handle. More...

Static Public Member Functions
static void	bind_epoch_task (async::EpochContext const *epoch_context, std::coroutine_handle<> h, EpochTaskRole role)
	Associates a coroutine with an epoch context as reader or writer.
static CoroutineExceptionDiagnosticsOptions	coroutine_exception_diagnostics_options ()
	Returns the active automatic coroutine-exception diagnostics policy.
static CoroutineExceptionDiagnosticsOptions	default_coroutine_exception_diagnostics_options ()
	Returns the environment-derived automatic coroutine-exception diagnostics policy.
static DiagnosticsServiceOptions	default_diagnostics_service_options ()
	Returns default diagnostics-service options.
static GraphvizDumpOptions	default_graphviz_dump_options ()
	Returns default Graphviz file-output options.
static std::string	default_graphviz_dump_path ()
	Creates a default DOT output path for the current process.
static std::string	default_graphviz_dump_path (GraphvizDumpOptions const &options)
	Creates a default DOT output path for the current process.
static StacktraceOptions	default_stacktrace_options ()
	Returns default stacktrace formatting options.
static void	destroy_epoch_context (async::EpochContext const *epoch_context)
	Removes an epoch context from debug tracking.
static void	destroy_task (std::coroutine_handle<> h)
	Marks a coroutine handle as destroyed.
static GraphDiagnostics	diagnose_snapshot (GraphSnapshot const &snapshot)
	Diagnoses blocked tasks, missing writers, and dependency cycles in a graph snapshot.
static void	dump ()
	Prints global task-registry diagnostics.
static void	dump_epoch_context (async::EpochContext const *epoch_context, char const *reason=nullptr)
	Prints diagnostics for a specific epoch context.
static void	dump_graphviz (std::FILE *stream=stderr)
	Prints a Graphviz DOT snapshot to a C stream.
static bool	dump_graphviz_file (std::string const &path)
	Writes a Graphviz DOT snapshot to a file.
static bool	dump_graphviz_file_best_effort (std::string const &path)
	Writes a best-effort Graphviz DOT snapshot to a file.
static DumpMode	dump_mode () noexcept
	Reports the current debug dump mode.
static std::vector< std::coroutine_handle<> >	epoch_reader_tasks (async::EpochContext const *epoch_context)
	Returns coroutine handles currently bound as readers.
static std::vector< std::coroutine_handle<> >	epoch_writer_tasks (async::EpochContext const *epoch_context)
	Returns coroutine handles currently bound as writers.
static std::string	graphviz_dot ()
	Returns a Graphviz DOT snapshot of the currently tracked async DAG.
static std::string	graphviz_dot (GraphSnapshot const &snapshot)
	Renders a graph snapshot as Graphviz DOT.
static std::string	graphviz_dot (GraphSnapshot const &snapshot, GraphDiagnostics const &diagnostics)
	Renders a graph snapshot and diagnostics as Graphviz DOT.
static std::string	graphviz_dot_best_effort ()
	Returns a best-effort Graphviz DOT snapshot without waiting indefinitely for locks.
static void	leak_task (std::coroutine_handle<> h)
	Marks a coroutine handle as leaked.
static void	mark_running (std::coroutine_handle<> h)
	Marks a coroutine handle as currently running.
static void	mark_suspended (std::coroutine_handle<> h)
	Marks a coroutine handle as suspended.
static void	name_async_value (async::NodeInfo const *node, std::string const &label)
	Assigns an optional human-readable label to an async value node.
static void	name_task (std::coroutine_handle<> h, std::string const &label)
	Assigns an optional human-readable label to a coroutine task.
static void	record_await_dependency (std::coroutine_handle<> h, async::NodeInfo const *node, EpochTaskRole role)
	Records a buffer dependency discovered at a concrete co_await site.
static void	record_task_dependencies (std::coroutine_handle<> h, std::vector< async::NodeInfo const * > const &read_dependencies, std::vector< async::NodeInfo const * > const &write_dependencies)
	Records constructor-discovered coarse DAG dependencies for a coroutine.
static void	record_task_scheduled (std::coroutine_handle<> h)
	Records the call stack where a coroutine was submitted to a scheduler.
static void	record_unhandled_exception (std::coroutine_handle<> h, std::exception_ptr exception, bool originating_failure) noexcept
	Records an exception escaping a coroutine and optionally captures its live DAG.
static void	register_epoch_context (async::EpochContext const *epoch_context)
	Registers an epoch context for debug tracking.
static void	register_task (std::coroutine_handle<> h)
	Registers a newly-created coroutine handle.
static void	request_graphviz_dump () noexcept
	Queues one Graphviz dump request for scheduler or service processing.
static void	reset_coroutine_exception_diagnostics_options ()
	Resets the automatic coroutine-exception diagnostics policy from the environment.
static void	reset_stacktrace_options ()
	Resets active stacktrace formatting options from environment defaults.
static bool	service_debug_requests ()
	Processes pending dump requests on the calling thread.
static bool	service_debug_requests (GraphvizDumpOptions const &options)
	Processes pending dump requests on the calling thread.
static void	set_coroutine_exception_diagnostics_options (CoroutineExceptionDiagnosticsOptions const &options)
	Replaces the process-wide automatic coroutine-exception diagnostics policy.
static void	set_stacktrace_options (StacktraceOptions const &options)
	Replaces active stacktrace formatting options.
static GraphSnapshot	snapshot ()
	Captures the current task/epoch/value DAG as structured data.
static GraphSnapshot	snapshot_best_effort ()
	Captures a best-effort task/epoch/value DAG snapshot without indefinite lock waits.
static StacktraceOptions	stacktrace_options ()
	Returns active stacktrace formatting options.
static bool	start_diagnostics_service ()
	Starts the optional background DAG diagnostics service.
static bool	start_diagnostics_service (DiagnosticsServiceOptions const &options)
	Starts the optional background DAG diagnostics service.
static void	stop_diagnostics_service () noexcept
	Stops the background DAG diagnostics service if it is running.
static void	unbind_epoch_task (async::EpochContext const *epoch_context, std::coroutine_handle<> h, EpochTaskRole role)
	Removes a coroutine-role binding from an epoch context.

Detailed Description

Tracks coroutine and epoch-context lifecycle events in debug builds.

Member Typedef Documentation

GraphDiagnostics

using uni20::TaskRegistryDebug::GraphDiagnostics = TaskRegistryGraphDiagnostics

Structured async DAG diagnostic result type.

GraphSnapshot

using uni20::TaskRegistryDebug::GraphSnapshot = TaskRegistryGraphSnapshot

Structured async DAG snapshot type.

StacktraceOptions

using uni20::TaskRegistryDebug::StacktraceOptions = TaskRegistryStacktraceOptions

Runtime controls for stacktrace formatting in debug output.

Member Enumeration Documentation

DumpMode

enum class uni20::TaskRegistryDebug::DumpMode

strong

Verbosity levels for registry dump output.

Enumerator
None
Basic
Full

EpochTaskRole

enum class uni20::TaskRegistryDebug::EpochTaskRole

strong

Role of a coroutine relative to an epoch context.

Enumerator
Reader
Writer

TaskState

enum class uni20::TaskRegistryDebug::TaskState

strong

Logical lifecycle states tracked for each coroutine handle.

Enumerator
Constructed
Running
Suspended
Failed
Leaked

Member Function Documentation

bind_epoch_task()

static void uni20::TaskRegistryDebug::bind_epoch_task ( async::EpochContext const *  epoch_context, std::coroutine_handle<>  h, EpochTaskRole  role  )

static

Associates a coroutine with an epoch context as reader or writer.

Parameters

epoch_context	Epoch context being accessed.
h	Coroutine handle to bind.
role	Reader or writer role for the binding.

coroutine_exception_diagnostics_options()

static CoroutineExceptionDiagnosticsOptions uni20::TaskRegistryDebug::coroutine_exception_diagnostics_options ( )

static

Returns the active automatic coroutine-exception diagnostics policy.

Returns

Process-wide runtime policy.

default_coroutine_exception_diagnostics_options()

static CoroutineExceptionDiagnosticsOptions uni20::TaskRegistryDebug::default_coroutine_exception_diagnostics_options ( )

static

Returns the environment-derived automatic coroutine-exception diagnostics policy.

Returns

Policy using UNI20_DEBUG_DAG_DUMP_ON_EXCEPTION and the default Graphviz output settings.

default_diagnostics_service_options()

static DiagnosticsServiceOptions uni20::TaskRegistryDebug::default_diagnostics_service_options ( )

static

Returns default diagnostics-service options.

Returns

Service options derived from environment variables when present.

default_graphviz_dump_options()

static GraphvizDumpOptions uni20::TaskRegistryDebug::default_graphviz_dump_options ( )

static

Returns default Graphviz file-output options.

Returns

Options derived from environment variables when present.

default_graphviz_dump_path() [1/2]

static std::string uni20::TaskRegistryDebug::default_graphviz_dump_path ( )

static

Creates a default DOT output path for the current process.

Returns

Path containing output directory, prefix, process id, and sequence number.

default_graphviz_dump_path() [2/2]

static std::string uni20::TaskRegistryDebug::default_graphviz_dump_path ( GraphvizDumpOptions const &  options )

static

Creates a default DOT output path for the current process.

Parameters

options

File-output options.

Returns

Path containing output directory, prefix, process id, and sequence number.

default_stacktrace_options()

static StacktraceOptions uni20::TaskRegistryDebug::default_stacktrace_options ( )

static

Returns default stacktrace formatting options.

Returns

Stacktrace options derived from environment variables when present.

destroy_epoch_context()

static void uni20::TaskRegistryDebug::destroy_epoch_context ( async::EpochContext const *  epoch_context )

static

Removes an epoch context from debug tracking.

Parameters

epoch_context

Epoch context pointer to remove.

destroy_task()

static void uni20::TaskRegistryDebug::destroy_task ( std::coroutine_handle<>  h )

static

Marks a coroutine handle as destroyed.

Parameters

h	Coroutine handle being destroyed.

diagnose_snapshot()

static GraphDiagnostics uni20::TaskRegistryDebug::diagnose_snapshot ( GraphSnapshot const &  snapshot )

static

Diagnoses blocked tasks, missing writers, and dependency cycles in a graph snapshot.

Parameters

snapshot

Structured graph snapshot to inspect.

Returns

Diagnostic annotations for the snapshot.

dump()

static void uni20::TaskRegistryDebug::dump ( )

static

Prints global task-registry diagnostics.

dump_epoch_context()

static void uni20::TaskRegistryDebug::dump_epoch_context ( async::EpochContext const *  epoch_context, char const *  reason = nullptr  )

static

Prints diagnostics for a specific epoch context.

Parameters

epoch_context	Epoch context to print.
reason	Optional label for the dump trigger.

dump_graphviz()

static void uni20::TaskRegistryDebug::dump_graphviz ( std::FILE *  stream = stderr )

static

Prints a Graphviz DOT snapshot to a C stream.

Parameters

stream

Destination stream. Defaults to stderr.

dump_graphviz_file()

static bool uni20::TaskRegistryDebug::dump_graphviz_file ( std::string const &  path )

static

Writes a Graphviz DOT snapshot to a file.

Parameters

path	Destination path.

Returns

true if the file was written successfully.

dump_graphviz_file_best_effort()

static bool uni20::TaskRegistryDebug::dump_graphviz_file_best_effort ( std::string const &  path )

static

Writes a best-effort Graphviz DOT snapshot to a file.

Parameters

path	Destination path.

Returns

true if the file was written successfully.

dump_mode()

static DumpMode uni20::TaskRegistryDebug::dump_mode ( )

staticnoexcept

Reports the current debug dump mode.

Returns

Active dump-mode setting.

epoch_reader_tasks()

static std::vector< std::coroutine_handle<> > uni20::TaskRegistryDebug::epoch_reader_tasks ( async::EpochContext const *  epoch_context )

static

Returns coroutine handles currently bound as readers.

Parameters

epoch_context

Epoch context to inspect.

Returns

Reader coroutine handles for the requested epoch context.

epoch_writer_tasks()

static std::vector< std::coroutine_handle<> > uni20::TaskRegistryDebug::epoch_writer_tasks ( async::EpochContext const *  epoch_context )

static

Returns coroutine handles currently bound as writers.

Parameters

epoch_context

Epoch context to inspect.

Returns

Writer coroutine handles for the requested epoch context.

graphviz_dot() [1/3]

static std::string uni20::TaskRegistryDebug::graphviz_dot ( )

static

Returns a Graphviz DOT snapshot of the currently tracked async DAG.

Returns

Graphviz DOT document describing tasks, epochs, and tracked dependencies.

graphviz_dot() [2/3]

static std::string uni20::TaskRegistryDebug::graphviz_dot ( GraphSnapshot const &  snapshot )

static

Renders a graph snapshot as Graphviz DOT.

Parameters

snapshot

Structured graph snapshot to render.

Returns

Graphviz DOT document.

graphviz_dot() [3/3]

static std::string uni20::TaskRegistryDebug::graphviz_dot ( GraphSnapshot const &  snapshot, GraphDiagnostics const &  diagnostics  )

static

Renders a graph snapshot and diagnostics as Graphviz DOT.

Parameters

snapshot	Structured graph snapshot to render.
diagnostics	Diagnostic annotations for the snapshot.

Returns

Graphviz DOT document.

graphviz_dot_best_effort()

static std::string uni20::TaskRegistryDebug::graphviz_dot_best_effort ( )

static

Returns a best-effort Graphviz DOT snapshot without waiting indefinitely for locks.

Returns

Graphviz DOT document, possibly partial if debug locks are currently held.

leak_task()

static void uni20::TaskRegistryDebug::leak_task ( std::coroutine_handle<>  h )

static

Marks a coroutine handle as leaked.

Parameters

h	Coroutine handle intentionally leaked.

mark_running()

static void uni20::TaskRegistryDebug::mark_running ( std::coroutine_handle<>  h )

static

Marks a coroutine handle as currently running.

Parameters

h	Coroutine handle that resumed execution.

mark_suspended()

static void uni20::TaskRegistryDebug::mark_suspended ( std::coroutine_handle<>  h )

static

Marks a coroutine handle as suspended.

Parameters

h	Coroutine handle that suspended execution.

name_async_value()

static void uni20::TaskRegistryDebug::name_async_value ( async::NodeInfo const *  node, std::string const &  label  )

static

Assigns an optional human-readable label to an async value node.

Parameters

node	Async value node to label.
label	Label to show in diagnostic graph output.

name_task()

static void uni20::TaskRegistryDebug::name_task ( std::coroutine_handle<>  h, std::string const &  label  )

static

Assigns an optional human-readable label to a coroutine task.

Parameters

h	Coroutine handle to label.
label	Label to show in diagnostic graph output.

record_await_dependency()

static void uni20::TaskRegistryDebug::record_await_dependency ( std::coroutine_handle<>  h, async::NodeInfo const *  node, EpochTaskRole  role  )

static

Records a buffer dependency discovered at a concrete co_await site.

Parameters

h	Coroutine handle that is awaiting the dependency.
node	Async value node being awaited.
role	Reader or writer role for the await dependency.

record_task_dependencies()

static void uni20::TaskRegistryDebug::record_task_dependencies ( std::coroutine_handle<>  h, std::vector< async::NodeInfo const * > const &  read_dependencies, std::vector< async::NodeInfo const * > const &  write_dependencies  )

static

Records constructor-discovered coarse DAG dependencies for a coroutine.

Parameters

h	Coroutine handle whose promise collected the dependencies.
read_dependencies	Async value nodes read by the coroutine.
write_dependencies	Async value nodes written by the coroutine.

record_task_scheduled()

static void uni20::TaskRegistryDebug::record_task_scheduled ( std::coroutine_handle<>  h )

static

Records the call stack where a coroutine was submitted to a scheduler.

Parameters

h	Coroutine handle being scheduled.

record_unhandled_exception()

static void uni20::TaskRegistryDebug::record_unhandled_exception ( std::coroutine_handle<>  h, std::exception_ptr  exception, bool  originating_failure  )

staticnoexcept

Records an exception escaping a coroutine and optionally captures its live DAG.

Parameters

h	Failing coroutine handle.
exception	Exception escaping the coroutine body.
originating_failure	Whether this coroutine originated rather than propagated the exception.

register_epoch_context()

static void uni20::TaskRegistryDebug::register_epoch_context ( async::EpochContext const *  epoch_context )

static

Registers an epoch context for debug tracking.

Parameters

epoch_context

Epoch context pointer to register.

register_task()

static void uni20::TaskRegistryDebug::register_task ( std::coroutine_handle<>  h )

static

Registers a newly-created coroutine handle.

Parameters

h	Coroutine handle to register.

request_graphviz_dump()

static void uni20::TaskRegistryDebug::request_graphviz_dump ( )

staticnoexcept

Queues one Graphviz dump request for scheduler or service processing.

reset_coroutine_exception_diagnostics_options()

static void uni20::TaskRegistryDebug::reset_coroutine_exception_diagnostics_options ( )

static

Resets the automatic coroutine-exception diagnostics policy from the environment.

reset_stacktrace_options()

static void uni20::TaskRegistryDebug::reset_stacktrace_options ( )

static

Resets active stacktrace formatting options from environment defaults.

service_debug_requests() [1/2]

static bool uni20::TaskRegistryDebug::service_debug_requests ( )

static

Processes pending dump requests on the calling thread.

Returns

true if at least one request was serviced.

service_debug_requests() [2/2]

static bool uni20::TaskRegistryDebug::service_debug_requests ( GraphvizDumpOptions const &  options )

static

Processes pending dump requests on the calling thread.

Parameters

options

File-output options for generated DOT files.

Returns

true if at least one request was serviced.

set_coroutine_exception_diagnostics_options()

static void uni20::TaskRegistryDebug::set_coroutine_exception_diagnostics_options ( CoroutineExceptionDiagnosticsOptions const &  options )

static

Replaces the process-wide automatic coroutine-exception diagnostics policy.

Parameters

options

New runtime policy.

set_stacktrace_options()

static void uni20::TaskRegistryDebug::set_stacktrace_options ( StacktraceOptions const &  options )

static

Replaces active stacktrace formatting options.

Parameters

options

New stacktrace formatting options.

snapshot()

static GraphSnapshot uni20::TaskRegistryDebug::snapshot ( )

static

Captures the current task/epoch/value DAG as structured data.

Returns

Structured graph snapshot.

snapshot_best_effort()

static GraphSnapshot uni20::TaskRegistryDebug::snapshot_best_effort ( )

static

Captures a best-effort task/epoch/value DAG snapshot without indefinite lock waits.

Returns

Structured graph snapshot, possibly marked unavailable or partial.

stacktrace_options()

static StacktraceOptions uni20::TaskRegistryDebug::stacktrace_options ( )

static

Returns active stacktrace formatting options.

Returns

Active stacktrace formatting options.

start_diagnostics_service() [1/2]

static bool uni20::TaskRegistryDebug::start_diagnostics_service ( )

static

Starts the optional background DAG diagnostics service.

Returns

true if a service was started or was already running.

start_diagnostics_service() [2/2]

static bool uni20::TaskRegistryDebug::start_diagnostics_service ( DiagnosticsServiceOptions const &  options )

static

Starts the optional background DAG diagnostics service.

Parameters

options

Signal/control-file and output configuration.

Returns

true if a service was started or was already running.

stop_diagnostics_service()

static void uni20::TaskRegistryDebug::stop_diagnostics_service ( )

staticnoexcept

Stops the background DAG diagnostics service if it is running.

unbind_epoch_task()

static void uni20::TaskRegistryDebug::unbind_epoch_task ( async::EpochContext const *  epoch_context, std::coroutine_handle<>  h, EpochTaskRole  role  )

static

Removes a coroutine-role binding from an epoch context.

Parameters

epoch_context	Epoch context that owns the binding.
h	Coroutine handle to unbind.
role	Reader or writer role being removed.

---

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

• task_registry_debug.hpp