task_registry_debug.hpp

Go to the documentation of this file.

#pragma once
 
#include "task_registry_snapshot.hpp"
 
#include <uni20/common/nifty_counter.hpp>
 
#include <coroutine>
#include <cstdio>
#include <exception>
#include <string>
#include <vector>
 
namespace uni20::async
{
class EpochContext;
class NodeInfo;
} // namespace uni20::async
 
namespace uni20
{
 
class TaskRegistryDebug;
 
using TaskRegistry = TaskRegistryDebug;
 
class TaskRegistryDebug {
  public:
    enum class DumpMode
    {
      None,
      Basic,
      Full,
    };
 
    enum class TaskState
    {
      Constructed,
      Running,
      Suspended,
      Failed,
      Leaked,
    };
 
    enum class EpochTaskRole
    {
      Reader,
      Writer,
    };
 
    struct GraphvizDumpOptions
    {
        std::string output_dir{"/tmp"};
        std::string file_prefix{"uni20-dag"};
    };
 
    struct CoroutineExceptionDiagnosticsOptions
    {
        bool enabled{false};
        bool write_graphviz{true};
        GraphvizDumpOptions dump_options{};
    };
 
    struct DiagnosticsServiceOptions
    {
        GraphvizDumpOptions dump_options{};
        int signal_number{0};
        std::string request_file{};
        int poll_interval_ms{250};
        bool block_signal_in_calling_thread{true};
    };
 
    using StacktraceOptions = TaskRegistryStacktraceOptions;
 
    using GraphSnapshot = TaskRegistryGraphSnapshot;
 
    using GraphDiagnostics = TaskRegistryGraphDiagnostics;
 
    static void register_task(std::coroutine_handle<> h);
    static void destroy_task(std::coroutine_handle<> h);
    static void leak_task(std::coroutine_handle<> h);
    static void mark_running(std::coroutine_handle<> h);
    static void mark_suspended(std::coroutine_handle<> h);
    static void record_unhandled_exception(std::coroutine_handle<> h, std::exception_ptr exception,
                                           bool originating_failure) noexcept;
    static void record_task_scheduled(std::coroutine_handle<> h);
    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);
    static void record_await_dependency(std::coroutine_handle<> h, async::NodeInfo const* node, EpochTaskRole role);
    static void name_task(std::coroutine_handle<> h, std::string const& label);
    static void name_async_value(async::NodeInfo const* node, std::string const& label);
    static void register_epoch_context(async::EpochContext const* epoch_context);
    static void destroy_epoch_context(async::EpochContext const* epoch_context);
    static void bind_epoch_task(async::EpochContext const* epoch_context, std::coroutine_handle<> h,
                                EpochTaskRole role);
    static void unbind_epoch_task(async::EpochContext const* epoch_context, std::coroutine_handle<> h,
                                  EpochTaskRole role);
    static std::vector<std::coroutine_handle<>> epoch_reader_tasks(async::EpochContext const* epoch_context);
    static std::vector<std::coroutine_handle<>> epoch_writer_tasks(async::EpochContext const* epoch_context);
    static DumpMode dump_mode() noexcept;
    static void dump_epoch_context(async::EpochContext const* epoch_context, char const* reason = nullptr);
    static GraphSnapshot snapshot();
    static GraphSnapshot snapshot_best_effort();
    static GraphDiagnostics diagnose_snapshot(GraphSnapshot const& snapshot);
    static std::string graphviz_dot();
    static std::string graphviz_dot_best_effort();
    static std::string graphviz_dot(GraphSnapshot const& snapshot);
    static std::string graphviz_dot(GraphSnapshot const& snapshot, GraphDiagnostics const& diagnostics);
    static void dump_graphviz(std::FILE* stream = stderr);
    static bool dump_graphviz_file(std::string const& path);
    static bool dump_graphviz_file_best_effort(std::string const& path);
    static GraphvizDumpOptions default_graphviz_dump_options();
    static CoroutineExceptionDiagnosticsOptions default_coroutine_exception_diagnostics_options();
    static CoroutineExceptionDiagnosticsOptions coroutine_exception_diagnostics_options();
    static void set_coroutine_exception_diagnostics_options(CoroutineExceptionDiagnosticsOptions const& options);
    static void reset_coroutine_exception_diagnostics_options();
    static DiagnosticsServiceOptions default_diagnostics_service_options();
    static StacktraceOptions default_stacktrace_options();
    static StacktraceOptions stacktrace_options();
    static void set_stacktrace_options(StacktraceOptions const& options);
    static void reset_stacktrace_options();
    static std::string default_graphviz_dump_path();
    static std::string default_graphviz_dump_path(GraphvizDumpOptions const& options);
    static void request_graphviz_dump() noexcept;
    static bool service_debug_requests();
    static bool service_debug_requests(GraphvizDumpOptions const& options);
    static bool start_diagnostics_service();
    static bool start_diagnostics_service(DiagnosticsServiceOptions const& options);
    static void stop_diagnostics_service() noexcept;
    static void dump();
};
 
} // namespace uni20
 
namespace uni20::detail
{
 
void initialize_task_registry_diagnostics_from_environment() noexcept;
void finalize_task_registry_diagnostics_from_environment() noexcept;
 
namespace
{
// One guard per translation unit gives later namespace-scope users ordered access to the diagnostics runtime.
[[maybe_unused]] nifty_counter<initialize_task_registry_diagnostics_from_environment,
                               finalize_task_registry_diagnostics_from_environment> task_registry_diagnostics_lifetime;
} // namespace
 
} // namespace uni20::detail