address_space.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 "../microfmt.hpp"
#include "../reloco.hpp"
#include "../scratch_allocator.hpp"
 
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <string_view>
#include <type_traits>
#include <utility>
namespace microfmt {
 
enum class address_space_error {
  invalid_handle,
  invalid_address,
  invalid_buffer,
  empty_buffer,
  read_failed,
  write_unsupported,
  write_failed,
};
 
struct MICROFMT_API_CLASS string_chunk {
  size_t length{};
  bool null_terminated{};
};
 
template <typename Tag> struct address_space_traits;
 
enum class remote_load_error {
  null_address,
  scratch_too_small,
  scratch_misaligned,
  invalid_address_space,
  read_failed,
};
 
namespace detail {
 
// decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths checked
// here.
RELOCO_BEGIN_UNSAFE_CODE
constexpr uintptr_t add_address_offset(uintptr_t address, ptrdiff_t offset) noexcept {
  if (offset >= 0)
    return address + static_cast<uintptr_t>(offset);
 
  const auto magnitude = static_cast<uintptr_t>(-(offset + 1)) + uintptr_t{1};
  return address - magnitude;
}
RELOCO_END_UNSAFE_CODE
 
template <typename Tag, typename = void> struct has_address_space_write_bytes : std::false_type {};
 
template <typename Tag>
struct has_address_space_write_bytes<
    Tag, std::void_t<decltype(address_space_traits<Tag>::write_bytes(
             std::declval<value_ref<const typename address_space_traits<Tag>::context_type>>(),
             std::declval<uintptr_t>(), std::declval<const void *>(), std::declval<size_t>()))>>
    : std::is_same<decltype(address_space_traits<Tag>::write_bytes(
                       std::declval<value_ref<const typename address_space_traits<Tag>::context_type>>(),
                       std::declval<uintptr_t>(), std::declval<const void *>(), std::declval<size_t>())),
                   bool> {};
 
template <typename Tag, typename = void> struct has_stateless_address_space_write_bytes : std::false_type {};
 
template <typename Tag>
struct has_stateless_address_space_write_bytes<
    Tag, std::void_t<decltype(address_space_traits<Tag>::write_bytes(
             std::declval<uintptr_t>(), std::declval<const void *>(), std::declval<size_t>()))>>
    : std::is_same<decltype(address_space_traits<Tag>::write_bytes(
                       std::declval<uintptr_t>(), std::declval<const void *>(), std::declval<size_t>())),
                   bool> {};
 
} // namespace detail
 
// ============================================================================
// Static Customization Point
// ============================================================================
 
struct local_space_tag {};
 
template <> struct address_space_traits<local_space_tag> {
  using context_type = void;
 
  // decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths
  // checked here.
  RELOCO_BEGIN_UNSAFE_CODE
  static bool read_bytes(uintptr_t addr, void *dest, size_t size) noexcept {
    if (addr == 0)
      return false;
    if (size == 0)
      return true;
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
    std::memcpy(dest, reinterpret_cast<const void *>(addr), size);
    RELOCO_END_UNSAFE_BUFFER_USAGE;
    return true;
  }
  RELOCO_END_UNSAFE_CODE
 
  // decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths
  // checked here.
  RELOCO_BEGIN_UNSAFE_CODE
  static bool write_bytes(uintptr_t addr, const void *src, size_t size) noexcept {
    if (addr == 0)
      return false;
    if (size == 0)
      return true;
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
    std::memcpy(reinterpret_cast<void *>(addr), src, size);
    RELOCO_END_UNSAFE_BUFFER_USAGE;
    return true;
  }
  RELOCO_END_UNSAFE_CODE
 
  // decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths
  // checked here.
  RELOCO_BEGIN_UNSAFE_CODE
  static bool read_string(uintptr_t addr, char *dest, size_t max_len, size_t &out_len, bool &null_term) noexcept {
    if (addr == 0)
      return false;
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
    const auto *src = reinterpret_cast<const char *>(addr);
    size_t i = 0;
    while (i < max_len) {
      dest[i] = src[i];
      if (dest[i] == '\0') {
        out_len = i;
        null_term = true;
        return true;
      }
      ++i;
    }
    RELOCO_END_UNSAFE_BUFFER_USAGE;
 
    out_len = max_len;
    null_term = false;
    return true;
  }
  RELOCO_END_UNSAFE_CODE
};
 
// ============================================================================
// Minimal-Stack Type-Erased Transport (2 Words: ctx_ + vtbl_)
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER address_space_ref {
public:
  struct vtable {
    bool (*read_bytes)(const void *ctx, uintptr_t addr, void *dest, size_t size) noexcept = nullptr;
    bool (*write_bytes)(const void *ctx, uintptr_t addr, const void *src, size_t size) noexcept = nullptr;
    bool (*read_string)(const void *ctx, uintptr_t addr, char *dest, size_t max_len, size_t &out_len,
                        bool &null_term) noexcept = nullptr;
  };
 
  constexpr address_space_ref() noexcept = default;
 
  template <typename Tag, typename Traits = address_space_traits<Tag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  constexpr explicit address_space_ref(Tag) noexcept : ctx_(nullptr), vtbl_(&s_vtbl<Tag>) {}
 
  template <typename Tag, typename Context, typename Traits = address_space_traits<Tag>,
            std::enable_if_t<!std::is_void_v<typename Traits::context_type> &&
                                 std::is_convertible_v<const Context *, const typename Traits::context_type *>,
                             int> = 0>
  constexpr address_space_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 address_space_ref(Tag, Context &&) = delete;
 
  template <typename Tag, typename Traits = address_space_traits<Tag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr address_space_ref make() noexcept {
    return address_space_ref(Tag{});
  }
 
  template <typename Tag, typename Context, typename Traits = address_space_traits<Tag>,
            std::enable_if_t<!std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr address_space_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return address_space_ref(Tag{}, ctx);
  }
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static address_space_ref make(Context &&) = delete;
 
  [[nodiscard]] expected<void, address_space_error> read_bytes(uintptr_t addr, void *dest, size_t size) const noexcept {
    if (vtbl_ == nullptr)
      return unexpected(address_space_error::invalid_handle);
    if (addr == 0)
      return unexpected(address_space_error::invalid_address);
    if (dest == nullptr && size != 0)
      return unexpected(address_space_error::invalid_buffer);
    if (!vtbl_->read_bytes(ctx_.get(), addr, dest, size))
      return unexpected(address_space_error::read_failed);
    return {};
  }
 
  template <typename T>
  [[nodiscard]] expected<void, address_space_error> read(uintptr_t addr, T &out_obj) const noexcept {
    static_assert(std::is_trivially_copyable_v<T>, "Target type T must be trivially copyable");
    return read_bytes(addr, &out_obj, sizeof(T));
  }
 
  template <typename T> [[nodiscard]] expected<T, address_space_error> read(uintptr_t addr) const noexcept {
    static_assert(std::is_trivially_copyable_v<T>, "Target type T must be trivially copyable");
    static_assert(std::is_nothrow_default_constructible_v<T>, "Target type T must be nothrow default constructible");
    static_assert(std::is_nothrow_move_constructible_v<T>, "Target type T must be nothrow move constructible");
    T object{};
    auto result = read_bytes(addr, &object, sizeof(T));
    if (!result)
      return unexpected(result.error());
    return object;
  }
 
  [[nodiscard]] expected<void, address_space_error> write_bytes(uintptr_t addr, const void *src,
                                                                size_t size) const noexcept {
    if (vtbl_ == nullptr)
      return unexpected(address_space_error::invalid_handle);
    if (addr == 0)
      return unexpected(address_space_error::invalid_address);
    if (src == nullptr && size != 0)
      return unexpected(address_space_error::invalid_buffer);
    if (vtbl_->write_bytes == nullptr)
      return unexpected(address_space_error::write_unsupported);
    if (!vtbl_->write_bytes(ctx_.get(), addr, src, size))
      return unexpected(address_space_error::write_failed);
    return {};
  }
 
  template <typename T>
  [[nodiscard]] expected<void, address_space_error> write(uintptr_t addr, const T &object) const noexcept {
    static_assert(std::is_trivially_copyable_v<T>, "Target type T must be trivially copyable");
    return write_bytes(addr, &object, sizeof(T));
  }
 
  [[nodiscard]] expected<string_chunk, address_space_error> read_string_chunk(uintptr_t addr,
                                                                              span<char> buffer) const noexcept {
    if (vtbl_ == nullptr)
      return unexpected(address_space_error::invalid_handle);
    if (addr == 0)
      return unexpected(address_space_error::invalid_address);
    if (buffer.empty())
      return unexpected(address_space_error::empty_buffer);
 
    string_chunk chunk{};
    if (!vtbl_->read_string(ctx_.get(), addr, buffer.data(), buffer.size(), chunk.length, chunk.null_terminated)) {
      return unexpected(address_space_error::read_failed);
    }
    return chunk;
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
  [[nodiscard]] constexpr bool can_write() const noexcept { return vtbl_ != nullptr && vtbl_->write_bytes != nullptr; }
 
private:
  template <typename Tag> [[nodiscard]] static constexpr auto write_bytes_entry() noexcept {
    using context_type = typename address_space_traits<Tag>::context_type;
    if constexpr (std::is_void_v<context_type>) {
      if constexpr (detail::has_stateless_address_space_write_bytes<Tag>::value) {
        return +[](const void *, uintptr_t address, const void *source, size_t size) noexcept {
          return address_space_traits<Tag>::write_bytes(address, source, size);
        };
      } else {
        return static_cast<bool (*)(const void *, uintptr_t, const void *, size_t) noexcept>(nullptr);
      }
    } else if constexpr (detail::has_address_space_write_bytes<Tag>::value) {
      return +[](const void *context, uintptr_t address, const void *source, size_t size) noexcept {
        const auto &typed_context = *static_cast<const context_type *>(context);
        return address_space_traits<Tag>::write_bytes(value_ref<const context_type>(typed_context), address, source,
                                                      size);
      };
    } else {
      return static_cast<bool (*)(const void *, uintptr_t, const void *, size_t) noexcept>(nullptr);
    }
  }
 
  template <typename Tag>
  static bool read_bytes_entry(const void *context, uintptr_t address, void *destination, size_t size) noexcept {
    using context_type = typename address_space_traits<Tag>::context_type;
    if constexpr (std::is_void_v<context_type>) {
      return address_space_traits<Tag>::read_bytes(address, destination, size);
    } else {
      const auto &typed_context = *static_cast<const context_type *>(context);
      return address_space_traits<Tag>::read_bytes(value_ref<const context_type>(typed_context), address, destination,
                                                   size);
    }
  }
 
  template <typename Tag>
  static bool read_string_entry(const void *context, uintptr_t address, char *destination, size_t capacity,
                                size_t &length, bool &terminated) noexcept {
    using context_type = typename address_space_traits<Tag>::context_type;
    if constexpr (std::is_void_v<context_type>) {
      return address_space_traits<Tag>::read_string(address, destination, capacity, length, terminated);
    } else {
      const auto &typed_context = *static_cast<const context_type *>(context);
      return address_space_traits<Tag>::read_string(value_ref<const context_type>(typed_context), address, destination,
                                                    capacity, length, terminated);
    }
  }
 
  template <typename Tag>
  static constexpr vtable s_vtbl{&read_bytes_entry<Tag>, write_bytes_entry<Tag>(), &read_string_entry<Tag>};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag, bool Stateless = std::is_void_v<typename address_space_traits<Tag>::context_type>>
class address_space;
 
template <typename Tag> class RELOCO_OWNER address_space<Tag, false> {
public:
  using traits_type = address_space_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit address_space(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 address_space_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return address_space_ref(Tag{}, context_);
  }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  address_space_ref ref() const && = delete;
 
private:
  context_type context_;
};
 
template <typename Tag> class address_space<Tag, true> {
public:
  [[nodiscard]] static constexpr address_space_ref ref() noexcept { return address_space_ref(Tag{}); }
};
 
// ============================================================================
// Compact Views
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER remote_string_view {
public:
  constexpr remote_string_view() noexcept = default;
 
  constexpr remote_string_view(uintptr_t addr, address_space_ref space,
                               span<char> scratch RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS,
                               size_t max_limit = 4096) noexcept
      : addr_(addr), space_(space), scratch_(scratch), max_limit_(max_limit) {}
 
  template <size_t N>
  constexpr remote_string_view(uintptr_t addr, address_space_ref space,
                               char (&scratch RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS)[N],
                               size_t max_limit = 4096) noexcept
      : addr_(addr), space_(space), scratch_(scratch, N), max_limit_(max_limit) {}
 
  [[nodiscard]] constexpr uintptr_t address() const noexcept { return addr_; }
  [[nodiscard]] constexpr address_space_ref space() const noexcept { return space_; }
  [[nodiscard]] constexpr span<char> scratch() const noexcept RELOCO_LIFETIMEBOUND { return scratch_; }
  [[nodiscard]] constexpr size_t max_limit() const noexcept { return max_limit_; }
 
private:
  uintptr_t addr_{0};
  address_space_ref space_{};
  span<char> scratch_{};
  size_t max_limit_{4096};
};
 
template <typename T> class RELOCO_POINTER remote_ref {
public:
  constexpr remote_ref(uintptr_t addr, address_space_ref space,
                       span<std::byte> scratch RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS) noexcept
      : addr_(addr), space_(space), scratch_(scratch) {}
 
  template <size_t N>
  constexpr remote_ref(uintptr_t addr, address_space_ref space, std::byte (&scratch)[N]) noexcept
      : addr_(addr), space_(space), scratch_(scratch, N) {}
 
  [[nodiscard]] constexpr uintptr_t address() const noexcept { return addr_; }
  [[nodiscard]] constexpr bool is_null() const noexcept { return addr_ == 0; }
 
  // decodes raw bytes of a target address space; casts, pointers and offsets are bounded by the explicit lengths
  // checked here.
  RELOCO_BEGIN_UNSAFE_CODE
  [[nodiscard]] expected<T *, remote_load_error> load() const noexcept {
    if (addr_ == 0)
      return unexpected(remote_load_error::null_address);
    if (scratch_.size() < sizeof(T))
      return unexpected(remote_load_error::scratch_too_small);
    if (reinterpret_cast<uintptr_t>(scratch_.data()) % alignof(T) != 0)
      return unexpected(remote_load_error::scratch_misaligned);
    if (!space_)
      return unexpected(remote_load_error::invalid_address_space);
 
    auto *out_ptr = static_cast<T *>(static_cast<void *>(scratch_.data()));
    if (!space_.read_bytes(addr_, out_ptr, sizeof(T)))
      return unexpected(remote_load_error::read_failed);
    return out_ptr;
  }
  RELOCO_END_UNSAFE_CODE
 
private:
  uintptr_t addr_{0};
  address_space_ref space_{};
  span<std::byte> scratch_{};
};
 
// ============================================================================
// microfmt Formatters
// ============================================================================
 
template <> struct formatter<remote_string_view> {
  constexpr void parse(format_parse_context &) noexcept {}
 
  void format(const remote_string_view &view, const sink &out) const noexcept {
    if (view.address() == 0) {
      out.write("(null)");
      return;
    }
 
    if (!view.space() || view.scratch().empty()) {
      microfmt::format_to(out, "<invalid-space@{:#x}>", view.address());
      return;
    }
 
    uintptr_t cur = view.address();
    size_t total = 0;
 
    while (total < view.max_limit()) {
      auto chunk = view.space().read_string_chunk(cur, view.scratch());
      if (!chunk) {
        if (total == 0) {
          microfmt::format_to(out, "<fault@{:#x}>", view.address());
        } else {
          out.write("<fault>");
        }
        return;
      }
 
      const size_t chunk_len = chunk->length;
      if (chunk_len > 0) {
        const size_t limit_left = view.max_limit() - total;
        const size_t to_write = (chunk_len > limit_left) ? limit_left : chunk_len;
        const auto scratch = view.scratch();
        out.write(microfmt::string_view(scratch.data(), to_write));
        total += to_write;
        cur += to_write;
      }
 
      if (chunk->null_terminated || total >= view.max_limit()) {
        break;
      }
    }
 
    if (total >= view.max_limit()) {
      out.write("...");
    }
  }
};
 
template <typename T> struct formatter<remote_ref<T>> {
  microfmt::string_view spec_{""};
 
  constexpr void parse(format_parse_context &ctx) noexcept { spec_ = ctx.spec(); }
 
  void format(const remote_ref<T> &view, const sink &out) const noexcept {
    if (view.is_null()) {
      out.write("(null)");
      return;
    }
 
    auto staged = view.load();
    if (!staged) {
      microfmt::format_to(out, "<fault@{:#x}>", view.address());
      return;
    }
 
    formatter<T> elem_fmt;
    format_parse_context pctx(spec_);
    elem_fmt.parse(pctx);
    elem_fmt.format(**staged, out);
  }
};
 
} // namespace microfmt