unwind_hint.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Jarosław Pelczar <jarek@jpelczar.com>
//
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#include "register_context.hpp"
#include <cstddef>
#include <cstdint>
#include <type_traits>
#include <utility>
 
namespace microfmt {
 
template <typename Tag> struct unwind_hint_registry_traits;
template <size_t MaxHints> class unwind_hint_registry_context;
template <size_t MaxHints = 32> struct fixed_unwind_hint_registry_tag {};
 
// ============================================================================
// Unwind Hint Definition
// ============================================================================
 
struct unwind_hint {
  uintptr_t pc_start{0};
  uintptr_t pc_end{0};
 
  using unwind_routine_t = bool (*)(address_space_ref space, register_context_ref reg_ctx, uintptr_t &next_fp,
                                    uintptr_t &next_pc) noexcept;
 
  unwind_routine_t routine{nullptr};
 
  [[nodiscard]] constexpr bool contains(uintptr_t pc) const noexcept { return pc >= pc_start && pc < pc_end; }
};
 
// ============================================================================
// Type-Erased Unwind Hint Registry Handle
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER unwind_hint_registry_ref {
public:
  struct vtable {
    bool (*find_hint)(const void *ctx, uintptr_t pc, unwind_hint &out_hint) noexcept;
  };
 
  constexpr unwind_hint_registry_ref() noexcept = default;
 
  template <typename Tag, typename Context, typename Traits = unwind_hint_registry_traits<Tag>,
            std::enable_if_t<std::is_convertible_v<const Context *, const typename Traits::context_type *>, int> = 0>
  constexpr unwind_hint_registry_ref(Tag,
                                     const Context &ctx RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS) noexcept
      : ctx_(&ctx), vtbl_(&s_vtbl<Tag>) {}
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  constexpr unwind_hint_registry_ref(Tag, Context &&) = delete;
 
  template <typename Tag, typename Context, typename Traits = unwind_hint_registry_traits<Tag>>
  [[nodiscard]] static constexpr unwind_hint_registry_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return unwind_hint_registry_ref(Tag{}, ctx);
  }
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static unwind_hint_registry_ref make(Context &&) = delete;
 
  [[nodiscard]] bool find_hint(uintptr_t pc, unwind_hint &out_hint) const noexcept {
    if (!vtbl_)
      return false;
    return vtbl_->find_hint(ctx_.get(), pc, out_hint);
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
private:
  template <typename Tag>
  static constexpr vtable s_vtbl{[](const void *context, uintptr_t pc, unwind_hint &hint) noexcept {
    using context_type = typename unwind_hint_registry_traits<Tag>::context_type;
    const auto &typed_context = *static_cast<const context_type *>(context);
    return unwind_hint_registry_traits<Tag>::find_hint(value_ref<const context_type>(typed_context), pc, hint);
  }};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag> class RELOCO_OWNER unwind_hint_registry {
public:
  using traits_type = unwind_hint_registry_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit unwind_hint_registry(context_type context) noexcept : context_(std::move(context)) {}
 
  [[nodiscard]] constexpr value_ref<context_type> context() & noexcept RELOCO_LIFETIMEBOUND {
    return value_ref<context_type>(context_);
  }
 
  [[nodiscard]] constexpr value_ref<const context_type> context() const & noexcept RELOCO_LIFETIMEBOUND {
    return value_ref<const context_type>(context_);
  }
 
  [[nodiscard]] constexpr unwind_hint_registry_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return unwind_hint_registry_ref(Tag{}, context_);
  }
 
  [[nodiscard]] constexpr operator unwind_hint_registry_ref() const & noexcept RELOCO_LIFETIMEBOUND { return ref(); }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  unwind_hint_registry_ref ref() const && = delete;
  operator unwind_hint_registry_ref() const && = delete;
 
private:
  context_type context_;
};
 
// ============================================================================
// Concrete Zero-Allocation Fixed-Capacity Registry Context
// ============================================================================
 
template <size_t MaxHints> class RELOCO_OWNER unwind_hint_registry_context {
public:
  constexpr unwind_hint_registry_context() noexcept = default;
 
  constexpr bool add_hint(const unwind_hint &hint) noexcept {
    if (hint_count_ >= MaxHints)
      return false;
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
    hints_[hint_count_++] = hint;
 
    RELOCO_END_UNSAFE_BUFFER_USAGE;
 
    return true;
  }
 
  [[nodiscard]] constexpr bool find_hint(uintptr_t pc, unwind_hint &out_hint) const noexcept {
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
    for (size_t i = 0; i < hint_count_; ++i) {
      if (hints_[i].contains(pc)) {
        out_hint = hints_[i];
        return true;
      }
    }
 
    RELOCO_END_UNSAFE_BUFFER_USAGE;
 
    return false;
  }
 
  [[nodiscard]] constexpr size_t size() const noexcept { return hint_count_; }
 
private:
  unwind_hint hints_[MaxHints]{};
  size_t hint_count_{0};
};
 
template <size_t MaxHints> struct unwind_hint_registry_traits<fixed_unwind_hint_registry_tag<MaxHints>> {
  using context_type = unwind_hint_registry_context<MaxHints>;
 
  static bool find_hint(value_ref<const context_type> context, uintptr_t pc, unwind_hint &out_hint) noexcept {
    return context->find_hint(pc, out_hint);
  }
};
 
using unwind_hint_registry_tag = fixed_unwind_hint_registry_tag<32>;
 
} // namespace microfmt