callback_boundary.hpp

Go to the documentation of this file.

#pragma once
 
// aria::CallbackBoundary — the single, framework-wide reporting channel for
// exceptions that escape a synchronous user callback at a boundary the
// framework MUST keep moving past.
//
// Why this exists
// ---------------
// Several locations inside the framework run user code in contexts where an
// exception cannot be propagated to a meaningful caller:
//
//   * worker threads inside a thread-pool executor;
//   * the main-thread executor / dispatcher's drain / pump loops;
//   * the ABI slot trampoline that backs `abi::SignalErased::emit`;
//   * the virtual-time executor's pump (test-side scheduler);
//   * detached coroutines (already routed through `aria::async`).
//
// Historically each site ended in a bare `catch (...) { /* swallow */ }`,
// which made production failures invisible. This header defines a single
// reporting primitive that those sites all funnel into:
//
//   aria::report_callback_failure("executor.thread_pool.worker",
//                                 std::current_exception());
//
// The host application installs ONE sink with `set_callback_failure_sink`
// (typically routed into the logger). Until then the default sink prints a
// single line to `stderr` so production failures are never invisible.
//
// Lifetime / threading
// --------------------
// * The sink is a function-pointer-based registration stored in an atomic
//   variable. Installation, replacement, and read use atomic operations.
// * The reporter is `noexcept`: a sink that throws is itself caught and
//   degraded to a `stderr` fallback so the framework's noexcept boundaries
//   stay honest.
// * `std::current_exception()` is captured at the boundary, so each report
//   carries a structured exception_ptr the sink can rethrow if it wants
//   typed inspection — ABI / type-erased payloads are not required.
//
// Layering
// --------
// This lives in `core` because both `async` (`async_error_sink`) and the
// concrete dispatcher / executor implementations need it. `runtime` injects
// a default sink that routes into `aria::Logger`. Adapters and binding
// layers may, but need not, install their own sinks.
 
#include "aria/abi/export.hpp"
#include "aria/function_ref.hpp"
 
#include <atomic>
#include <cstdio>
#include <exception>
#include <string>
#include <string_view>
#include <utility>
 
namespace aria {

struct CallbackFailure {
    std::string_view   category;
    std::exception_ptr exception;
    std::string_view   message;
};

using CallbackFailureSink = void (*)(const CallbackFailure&);
 
namespace detail::callback_boundary {
 
// Shared builds store this slot in libaria_abi. Static builds link one
// copy into the host executable; independently linked plugins should use the
// shared build if they need process-wide diagnostic registration.
ARIA_ABI_API std::atomic<CallbackFailureSink>& sink_storage() noexcept;
 
inline std::string render_message_(const CallbackFailure& f) {
    if (!f.message.empty()) return std::string{f.message};
    if (f.exception) {
        try {
            std::rethrow_exception(f.exception);
        } catch (const std::exception& e) {
            return std::string{e.what()};
        } catch (...) {
            return "non-std::exception";
        }
    }
    return "(no payload)";
}
 
inline void default_sink_(const CallbackFailure& f) noexcept {
    // Fallback: a single, parseable line on stderr. Host apps that want
    // structured logging install their own sink during runtime startup.
    try {
        const std::string msg = render_message_(f);
        std::fprintf(stderr, "[aria.callback_failure] %.*s: %s\n",
                     static_cast<int>(f.category.size()), f.category.data(),
                     msg.c_str());
        std::fflush(stderr);
    } catch (...) {
        // We are already a noexcept boundary of last resort. Even formatting
        // can fail under OOM; in that case we simply give up — the framework
        // contract is to never raise from a noexcept boundary.
    }
}
 
}  // namespace detail::callback_boundary

inline CallbackFailureSink set_callback_failure_sink(CallbackFailureSink sink) noexcept {
    return detail::callback_boundary::sink_storage().exchange(sink, std::memory_order_acq_rel);
}

[[nodiscard]] inline CallbackFailureSink current_callback_failure_sink() noexcept {
    return detail::callback_boundary::sink_storage().load(std::memory_order_acquire);
}

ARIA_ABI_API void report_callback_failure(std::string_view category,
                                            std::exception_ptr exception,
                                            std::string_view message = {}) noexcept;

inline void report_callback_failure(std::string_view category,
                                    std::string_view message) noexcept {
    report_callback_failure(category, std::exception_ptr{}, message);
}
 
}  // namespace aria