CppInterOp.h

Go to the documentation of this file.

//===--- CppInterOp.h - A layer for language interoperability ---*- C++ -*-===//
//
// Part of the compiler-research project, under the Apache License v2.0 with
// LLVM Exceptions.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file defines API for introspection which enables language
// interoperability.
//
//===----------------------------------------------------------------------===//
 
#ifndef CPPINTEROP_CPPINTEROP_H
#define CPPINTEROP_CPPINTEROP_H
 
#ifdef CPPINTEROP_DISPATCH_H
#error "CppInterOp.h and Dispatch.h are mutually exclusive — include only one."
#endif
 
#include "CppInterOp/CppInterOpTypes.h"
// Cpp::Box must be visible before the tablegen-generated declarations
// below, since Evaluate (and future Value-returning APIs) reference it.
#include "CppInterOp/Box.h"
 
#include <initializer_list>
#include <memory>
#include <utility>
#include <vector>
 
namespace Cpp {
 
// Public API function declarations. Generated by cppinterop-tblgen
// from CppInterOp.td. Do not edit this section by hand.
#include "CppInterOp/CppInterOpDecl.inc"
 
namespace detail {
// Total slots before the published vtable's address point in an overlay
// block: the ABI prefix of the underlying class (1 on MSVC --
// complete-object-locator; 2 on Itanium -- offset-to-top + type_info)
// plus 1 hidden slot CppInterOp interposes for the dtor-hook
// self-pointer. Exposed only so the inline VTableOverlayExtraSlot helper
// below can compile the offset; users should not read or write any slots
// directly.
// static (not inline) so the reproducer-as-TU compiles under C++14;
// inline-variable is a C++17 extension and the JIT-compiled reproducer
// is fed back through the interpreter at its default language standard.
#ifdef _WIN32
static constexpr int kVTableOverlayPrefixSize = 1 + 1;
#else
static constexpr int kVTableOverlayPrefixSize = 2 + 1;
#endif
} // namespace detail
 
/// Address of the i-th extra-prefix slot of an instance with an overlay
/// installed via MakeVTableOverlay(..., n_extra_prefix_slots = N, ...).
/// Returns a void*& so callers read and write through the same expression;
/// this is the canonical access path -- bindings should not synthesize the
/// vptr arithmetic themselves. Behavior is undefined if \c inst has no
/// overlay or i >= N.
inline void*& VTableOverlayExtraSlot(void* inst, std::size_t i) {
  void** vptr = *reinterpret_cast<void***>(inst);
  return vptr[-(detail::kVTableOverlayPrefixSize + 1 + static_cast<int>(i))];
}
 
struct VTableOverlayDeleter {
  void operator()(VTableOverlay* o) const noexcept { DestroyVTableOverlay(o); }
};
using UniqueVTableOverlay =
    std::unique_ptr<VTableOverlay, VTableOverlayDeleter>;
 
/// Owning wrapper over MakeVTableOverlay: each pair maps a virtual method
/// of polymorphic class \c base to its replacement function pointer. The
/// overlay is installed on construction and the original vptr restored when
/// the handle is destroyed. The caller works in reflected methods, not
/// ABI-specific slot indices -- the common path for language bindings.
/// \c n_extra_prefix_slots reserves nullptr-initialized slots immediately
/// before the ABI prefix for the caller to write per-instance data into.
/// \c on_destroy, when non-null, is invoked once after the C++ destructor
/// of \c inst runs (operator-delete path). It receives the original \c
/// inst pointer (which may be dangling at that point -- do not deref) and
/// \c cleanup_data verbatim; bindings use it to release any per-instance
/// state (Python handles, closures) tied to the object's lifetime. The
/// callback must not throw: it runs inside a C++ destructor, so an
/// escaping exception is undefined behavior.
inline UniqueVTableOverlay MakeUniqueVTableOverlay(
    void* inst, DeclRef base,
    std::initializer_list<std::pair<ConstFuncRef, void*>> overrides,
    std::size_t n_extra_prefix_slots = 0,
    VTableOverlayDtorHook on_destroy = nullptr, void* cleanup_data = nullptr) {
  std::vector<ConstFuncRef> methods;
  std::vector<void*> fns;
  methods.reserve(overrides.size());
  fns.reserve(overrides.size());
  for (const auto& p : overrides) {
    methods.push_back(p.first);
    fns.push_back(p.second);
  }
  return UniqueVTableOverlay{MakeVTableOverlay(
      inst, base, methods.data(), fns.data(), methods.size(),
      n_extra_prefix_slots, on_destroy, cleanup_data)};
}
 
} // namespace Cpp
 
#endif // CPPINTEROP_CPPINTEROP_H