cpyrtModule.cxx

Go to the documentation of this file.

// Bindings
#include "cpyrt.h"
 
using namespace cppjit;
#include "CPPDataMember.h"
#include "CPPExcInstance.h"
#include "CPPInstance.h"
#include "CPPOverload.h"
#include "CPPScope.h"
#include "CallContext.h"
#include "Converters.h"
#include "CustomPyTypes.h"
#include "LowLevelViews.h"
#include "MemoryRegulator.h"
#include "ProxyWrappers.h"
#include "PyStrings.h"
#include "TemplateProxy.h"
#include "TupleOfInstances.h"
#include "TypeManip.h"
#include "Utility.h"
#include "cppjit_interop.h"
#include <unordered_map>
 
#define CPYRT_INTERNAL 1
#include "cpyrt/DispatchPtr.h"
namespace cppjit::cpyrt {
void* Instance_AsVoidPtr(PyObject* pyobject);
PyObject* Instance_FromVoidPtr(void* addr, const std::string& classname,
                               bool python_owns = false);
} // namespace cppjit::cpyrt
#undef CPYRT_INTERNAL
 
// Standard
#include <algorithm>
#include <iostream>
#include <map>
#include <sstream>
#include <string>
#include <unordered_set>
#include <utility>
#include <vector>
 
std::unordered_map<interop::TCppType_t, interop::TCppType_t> TypeReductionMap;
 
//- data -----------------------------------------------------------------------
static PyObject* nullptr_repr(PyObject*) {
  return PyUnicode_FromString("nullptr");
}
 
static void nullptr_dealloc(PyObject*) {
  Py_FatalError("deallocating nullptr");
}
 
static int nullptr_nonzero(PyObject*) { return 0; }
 
static PyNumberMethods nullptr_as_number = {
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    (inquiry)nullptr_nonzero, // tp_nonzero (nb_bool in p3)
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0, // nb_floor_divide
    0, // nb_true_divide
    0,
    0,
    0, // nb_index
    0, // nb_matrix_multiply
    0  // nb_inplace_matrix_multiply
};
 
static PyTypeObject PyNullPtr_t_Type = {
    PyVarObject_HEAD_INIT(&PyType_Type, 0) "nullptr_t", // tp_name
    sizeof(PyObject),                                   // tp_basicsize
    0,                                                  // tp_itemsize
    nullptr_dealloc, // tp_dealloc (never called)
    0,
    0,
    0,
    0,
    nullptr_repr,       // tp_repr
    &nullptr_as_number, // tp_as_number
    0,
    0,
#if PY_VERSION_HEX >= 0x030d0000
    (hashfunc)Py_HashPointer, // tp_hash
#else
    (hashfunc)_Py_HashPointer, // tp_hash
#endif
    0,
    0,
    0,
    0,
    0,
    Py_TPFLAGS_DEFAULT,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0, // tp_del
    0, // tp_version_tag
    0, // tp_finalize
    0  // tp_vectorcall
    CPYRT_PYTYPE_TAIL};
 
static PyObject* default_repr(PyObject*) {
  return PyUnicode_FromString("type default");
}
 
static void default_dealloc(PyObject*) {
  Py_FatalError("deallocating default");
}
 
static PyTypeObject PyDefault_t_Type = {
    PyVarObject_HEAD_INIT(&PyType_Type, 0) "default_t", // tp_name
    sizeof(PyObject),                                   // tp_basicsize
    0,                                                  // tp_itemsize
    default_dealloc, // tp_dealloc (never called)
    0,
    0,
    0,
    0,
    default_repr, // tp_repr
    0,
    0,
    0,
#if PY_VERSION_HEX >= 0x030d0000
    (hashfunc)Py_HashPointer, // tp_hash
#else
    (hashfunc)_Py_HashPointer, // tp_hash
#endif
    0,
    0,
    0,
    0,
    0,
    Py_TPFLAGS_DEFAULT,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0, // tp_del
    0, // tp_version_tag
    0, // tp_finalize
    0  // tp_vectorcall
    CPYRT_PYTYPE_TAIL};
 
namespace {
 
struct {
  PyObject_HEAD
} _cpyrt_NullPtrStruct{PyObject_HEAD_INIT(&PyNullPtr_t_Type)};
 
struct {
  PyObject_HEAD
} _cpyrt_DefaultStruct{PyObject_HEAD_INIT(&PyDefault_t_Type)};
 
// TODO: refactor with Converters.cxx
struct cpyrt_tagCDataObject { // non-public (but stable)
  PyObject_HEAD char* b_ptr;
  int b_needsfree;
};
 
} // unnamed namespace
 
namespace cppjit::cpyrt {
PyObject* gThisModule = nullptr;
PyObject* gPyTypeMap = nullptr;
PyObject* gNullPtrObject = nullptr;
PyObject* gDefaultObject = nullptr;
PyObject* gBusException = nullptr;
PyObject* gSegvException = nullptr;
PyObject* gIllException = nullptr;
PyObject* gAbrtException = nullptr;
std::unordered_set<interop::TCppScope_t> gPinnedTypes;
std::ostringstream gCapturedError;
std::streambuf* gOldErrorBuffer = nullptr;
 
std::unordered_map<std::string, std::vector<PyObject*>>& pythonizations() {
  static std::unordered_map<std::string, std::vector<PyObject*>> pyzMap;
  return pyzMap;
}
} // namespace cppjit::cpyrt
 
//- private helpers ------------------------------------------------------------
namespace {
 
using namespace cppjit::cpyrt;
 
//----------------------------------------------------------------------------
static PyObject* MakeCppTemplateClass(PyObject* /* self */, PyObject* args) {
  // Create a binding for a templated class instantiation.
 
  // args is class name + template arguments; build full instantiation
  Py_ssize_t nArgs = PyTuple_GET_SIZE(args);
  if (nArgs < 2) {
    PyErr_Format(PyExc_TypeError,
                 "too few arguments for template instantiation");
    return nullptr;
  }
  PyObject* cppscope = PyTuple_GET_ITEM(args, 0);
  void* tmpl = PyLong_AsVoidPtr(cppscope);
 
  // build "< type, type, ... >" part of class name (modifies pyname)
  std::vector<Cpp::TemplateArgInfo> types =
      Utility::GetTemplateArgsTypes(cppscope, args, nullptr, Utility::kNone, 1);
  if (PyErr_Occurred())
    return nullptr;
 
  interop::TCppScope_t scope =
      interop::InstantiateTemplate(tmpl, types.data(), types.size());
  for (Cpp::TemplateArgInfo i : types) {
    if (i.m_IntegralValue)
      std::free((void*)i.m_IntegralValue);
  }
 
  if (!scope) {
    PyErr_Format(PyExc_TypeError,
                 "Template instantiation failed: '%s' with args: '%s\n'",
                 interop::GetScopedFinalName(tmpl).c_str(),
                 PyUnicode_AsUTF8(PyObject_Repr(args)));
    return nullptr;
  }
 
  return CreateScopeProxy(scope);
}
 
//----------------------------------------------------------------------------
static char* GCIA_kwlist[] = {(char*)"instance", (char*)"field", (char*)"byref",
                              NULL};
static void* GetCPPInstanceAddress(const char* fname, PyObject* args,
                                   PyObject* kwds) {
  // Helper to get the address (address-of-address) of various object proxy
  // types.
  CPPInstance* pyobj = 0;
  PyObject* pyname = 0;
  int byref = 0;
  if (PyArg_ParseTupleAndKeywords(args, kwds, const_cast<char*>("O|O!b"),
                                  GCIA_kwlist, &pyobj, &PyUnicode_Type, &pyname,
                                  &byref)) {
 
    if (CPPInstance_Check(pyobj)) {
      if (pyname != 0) {
        // locate property proxy for offset info
        CPPDataMember* pyprop = nullptr;
 
        PyObject* pyclass = (PyObject*)Py_TYPE((PyObject*)pyobj);
        PyObject* dict = PyObject_GetAttr(pyclass, PyStrings::gDict);
        pyprop = (CPPDataMember*)PyObject_GetItem(dict, pyname);
        Py_DECREF(dict);
 
        if (CPPDataMember_Check(pyprop)) {
          // this is an address of a value (i.e. &myobj->prop)
          void* addr = (void*)pyprop->GetAddress(pyobj);
          Py_DECREF(pyprop);
          return addr;
        }
 
        Py_XDECREF(pyprop);
 
        PyErr_Format(PyExc_TypeError, "%s is not a valid data member",
                     PyUnicode_AsUTF8(pyname));
        return nullptr;
      }
 
      // this is an address of an address (i.e. &myobj, with myobj of type
      // MyObj*) note that the return result may be null
      if (!byref)
        return ((CPPInstance*)pyobj)->GetObject();
      return &((CPPInstance*)pyobj)->GetObjectRaw();
 
    } else if (PyUnicode_Check(pyobj)) {
      // special cases for access to the cpyrt API
      std::string req = PyUnicode_AsUTF8((PyObject*)pyobj);
      if (req == "Instance_AsVoidPtr")
        return (void*)&Instance_AsVoidPtr;
      else if (req == "Instance_FromVoidPtr")
        return (void*)&Instance_FromVoidPtr;
    }
  }
 
  if (!PyErr_Occurred())
    PyErr_Format(PyExc_ValueError, "invalid argument for %s", fname);
  return nullptr;
}
 
//----------------------------------------------------------------------------
static PyObject* addressof(PyObject* /* dummy */, PyObject* args,
                           PyObject* kwds) {
  // Return object proxy address as a value (cppjit-style), or the same for an
  // array.
  void* addr = GetCPPInstanceAddress("addressof", args, kwds);
  if (addr)
    return PyLong_FromLongLong((intptr_t)addr);
  else if (!PyErr_Occurred()) {
    return PyLong_FromLong(0);
  } else if (PyTuple_CheckExact(args) && PyTuple_GET_SIZE(args) == 1) {
    PyErr_Clear();
    PyObject* arg0 = PyTuple_GET_ITEM(args, 0);
 
    // nullptr special case
    if (arg0 == gNullPtrObject ||
        (PyLong_Check(arg0) && PyLong_AsLong(arg0) == 0))
      return PyLong_FromLong(0);
 
    // overload if unambiguous
    if (CPPOverload_CheckExact(arg0)) {
      const auto& methods = ((CPPOverload*)arg0)->fMethodInfo->fMethods;
      if (methods.size() != 1) {
        PyErr_SetString(PyExc_TypeError, "overload is not unambiguous");
        return nullptr;
      }
 
      interop::TCppFuncAddr_t caddr = methods[0]->GetFunctionAddress();
      return PyLong_FromLongLong((intptr_t)caddr);
    }
 
    // C functions (incl. ourselves)
    if (PyCFunction_Check(arg0)) {
      void* caddr = (void*)PyCFunction_GetFunction(arg0);
      return PyLong_FromLongLong((intptr_t)caddr);
    }
 
    // LowLevelViews
    if (LowLevelView_CheckExact(arg0)) {
      auto* llv = (LowLevelView*)arg0;
      return PyLong_FromLongLong((intptr_t)llv->get_buf());
    }
 
    // final attempt: any type of buffer
    Utility::GetBuffer(arg0, '*', 1, addr, false);
    if (addr)
      return PyLong_FromLongLong((intptr_t)addr);
  }
 
  // error message if not already set
  if (!PyErr_Occurred()) {
    if (PyTuple_CheckExact(args) && PyTuple_GET_SIZE(args)) {
      PyObject* str = PyObject_Str(PyTuple_GET_ITEM(args, 0));
      if (str && PyUnicode_Check(str))
        PyErr_Format(PyExc_TypeError, "unknown object %s",
                     PyUnicode_AsUTF8(str));
      else
        PyErr_Format(PyExc_TypeError, "unknown object at %p",
                     (void*)PyTuple_GET_ITEM(args, 0));
      Py_XDECREF(str);
    }
  }
  return nullptr;
}
 
//----------------------------------------------------------------------------
static PyObject* AsCObject(PyObject* /* unused */, PyObject* args,
                           PyObject* kwds) {
  // Return object proxy as an opaque CObject.
  void* addr = GetCPPInstanceAddress("as_cobject", args, kwds);
  if (addr)
    return PyCapsule_New((void*)addr, nullptr, nullptr);
  return nullptr;
}
 
//----------------------------------------------------------------------------
static PyObject* AsCapsule(PyObject* /* unused */, PyObject* args,
                           PyObject* kwds) {
  // Return object proxy as an opaque PyCapsule.
  void* addr = GetCPPInstanceAddress("as_capsule", args, kwds);
  if (addr)
    return PyCapsule_New(addr, nullptr, nullptr);
  return nullptr;
}
 
//----------------------------------------------------------------------------
static PyObject* AsCTypes(PyObject* /* unused */, PyObject* args,
                          PyObject* kwds) {
  // Return object proxy as a ctypes c_void_p
  void* addr = GetCPPInstanceAddress("as_ctypes", args, kwds);
  if (!addr)
    return nullptr;
 
  // TODO: refactor code below with converters code
  static PyTypeObject* ct_cvoidp = nullptr;
  if (!ct_cvoidp) {
    PyObject* ctmod = PyImport_ImportModule("ctypes"); // ref-count kept
    if (!ctmod)
      return nullptr;
 
    ct_cvoidp = (PyTypeObject*)PyObject_GetAttrString(ctmod, "c_void_p");
    Py_DECREF(ctmod);
    if (!ct_cvoidp)
      return nullptr;
    Py_DECREF(ct_cvoidp); // module keeps a reference
  }
 
  PyObject* ref = ct_cvoidp->tp_new(ct_cvoidp, nullptr, nullptr);
  *(void**)((cpyrt_tagCDataObject*)ref)->b_ptr = addr;
  ((cpyrt_tagCDataObject*)ref)->b_needsfree = 0;
  return ref;
}
 
//----------------------------------------------------------------------------
static PyObject* AsMemoryView(PyObject* /* unused */, PyObject* pyobject) {
  // Return a raw memory view on arrays of PODs.
  if (!CPPInstance_Check(pyobject)) {
    PyErr_SetString(PyExc_TypeError, "C++ object proxy expected");
    return nullptr;
  }
 
  CPPInstance* pyobj = (CPPInstance*)pyobject;
  interop::TCppScope_t klass = ((CPPClass*)Py_TYPE(pyobject))->fCppType;
 
  Py_ssize_t array_len = pyobj->ArrayLength();
 
  if (array_len < 0 || !interop::IsAggregate(klass)) {
    PyErr_SetString(PyExc_TypeError,
                    "object is not a proxy to an array of PODs of known size");
    return nullptr;
  }
 
  Py_buffer view;
 
  view.obj = pyobject;
  view.buf = pyobj->GetObject();
  view.itemsize = interop::SizeOf(klass);
  view.len = view.itemsize * array_len;
  view.readonly = 0;
  view.format = NULL; // i.e. "B" assumed
  view.ndim = 1;
  view.shape = NULL;
  view.strides = NULL;
  view.suboffsets = NULL;
  view.internal = NULL;
 
  return PyMemoryView_FromBuffer(&view);
}
 
//----------------------------------------------------------------------------
static PyObject* BindObject(PyObject*, PyObject* args, PyObject* kwds) {
  // From a long representing an address or a PyCapsule/CObject, bind to a
  // class.
  Py_ssize_t argc = PyTuple_GET_SIZE(args);
  if (argc != 2) {
    PyErr_Format(
        PyExc_TypeError,
        "bind_object takes 2 positional arguments but (" PY_SSIZE_T_FORMAT
        " were given)",
        argc);
    return nullptr;
  }
 
  // convert 2nd argument first (used for both pointer value and instance cases)
  interop::TCppScope_t cast_type = nullptr;
  PyObject* arg1 = PyTuple_GET_ITEM(args, 1);
  if (!PyUnicode_Check(arg1)) { // not string, then class
    if (CPPScope_Check(arg1))
      cast_type = ((CPPClass*)arg1)->fCppType;
    else
      arg1 = PyObject_GetAttr(arg1, PyStrings::gName);
  } else
    Py_INCREF(arg1);
 
  if (!cast_type && arg1) {
    cast_type = (interop::TCppScope_t)interop::GetScope(PyUnicode_AsUTF8(arg1));
    Py_DECREF(arg1);
  }
 
  if (!cast_type) {
    PyErr_SetString(
        PyExc_TypeError,
        "bind_object expects a valid class or class name as an argument");
    return nullptr;
  }
 
  // next, convert the first argument, some pointer value or a pre-existing
  // instance
  PyObject* arg0 = PyTuple_GET_ITEM(args, 0);
 
  if (CPPInstance_Check(arg0)) {
    // if this instance's class has a relation to the requested one, calculate
    // the offset, erase if from any caches, and update the pointer and type
    CPPInstance* arg0_pyobj = (CPPInstance*)arg0;
    interop::TCppScope_t cur_type =
        arg0_pyobj->ObjectIsA(false /* check_smart */);
 
    bool isPython = CPPScope_Check(arg1) &&
                    (((CPPClass*)arg1)->fFlags & CPPScope::kIsPython);
 
    if (cur_type == cast_type && !isPython) {
      Py_INCREF(arg0); // nothing to do
      return arg0;
    }
 
    int direction = 0;
    interop::TCppScope_t base = nullptr, derived = nullptr;
    if (interop::IsSubclass(cast_type, cur_type)) {
      derived = cast_type;
      base = cur_type;
      direction = -1; // down-cast
    } else if (interop::IsSubclass(cur_type, cast_type)) {
      base = cast_type;
      derived = cur_type;
      direction = 1; // up-cast
    } else {
      PyErr_SetString(
          PyExc_TypeError,
          "provided instance and provided target type are unrelated");
      return nullptr;
    }
 
    interop::TCppObject_t address =
        (interop::TCppObject_t)arg0_pyobj->GetObject();
    ptrdiff_t offset =
        interop::GetBaseOffset(derived, base, address, direction);
 
    // it's debatable whether a new proxy should be created rather than updating
    // the old, but changing the old object would be changing the behavior of
    // all code that has a reference to it, which may not be the intention if
    // the cast is on a C++ data member; this probably is the "least surprise"
    // option
 
    // ownership is taken over as needed, again following the principle of
    // "least surprise" as most likely only the cast object will be retained
    bool owns = arg0_pyobj->fFlags & CPPInstance::kIsOwner;
 
    if (!isPython) {
      // ordinary C++ class
      PyObject* pyobj = BindCppObjectNoCast(
          interop::TCppObject_t((void*)((intptr_t)address.data + offset)),
          cast_type, owns ? CPPInstance::kIsOwner : 0);
      if (owns && pyobj)
        arg0_pyobj->CppOwns();
      return pyobj;
 
    } else {
      // rebinding to a Python-side class, create a fresh instance first to be
      // able to perform a lookup of the original dispatch object and if found,
      // return original
      void* cast_address = (void*)((intptr_t)address.data + offset);
      PyObject* pyobj =
          ((PyTypeObject*)arg1)->tp_new((PyTypeObject*)arg1, nullptr, nullptr);
      ((CPPInstance*)pyobj)->GetObjectRaw() = cast_address;
 
      PyObject* dispproxy = cpyrt::GetScopeProxy(cast_type);
      PyObject* res =
          PyObject_CallMethodOneArg(dispproxy, PyStrings::gDispGet, pyobj);
      /* Note: the resultant object is borrowed */
      if (CPPInstance_Check(res) &&
          ((CPPInstance*)res)->GetObject() == cast_address) {
        ((CPPInstance*)pyobj)->CppOwns(); // make sure C++ object isn't deleted
        Py_DECREF(pyobj);                 //  on DECREF (is default, but still)
        pyobj = res;
      } else {
        if (res)
          Py_DECREF(res); // most likely Py_None
        else
          PyErr_Clear(); // should not happen
      }
      Py_DECREF(dispproxy);
 
      if (pyobj && owns) {
        arg0_pyobj->CppOwns();
        ((CPPInstance*)pyobj)->PythonOwns();
      }
 
      return pyobj;
    }
  }
 
  // not a pre-existing object; get the address and bind
  void* addr = nullptr;
  if (arg0 != gNullPtrObject) {
    addr = PyCapsule_GetPointer(arg0, nullptr);
    if (PyErr_Occurred()) {
      PyErr_Clear();
 
      addr = PyLong_AsVoidPtr(arg0);
      if (PyErr_Occurred()) {
        PyErr_Clear();
 
        // last chance, perhaps it's a buffer/array (return from void*)
        Py_ssize_t buflen =
            Utility::GetBuffer(PyTuple_GetItem(args, 0), '*', 1, addr, false);
        if (!addr || !buflen) {
          PyErr_SetString(PyExc_TypeError,
                          "bind_object requires a CObject/Capsule, long "
                          "integer, buffer, or instance as first argument");
          return nullptr;
        }
      }
    }
  }
 
  bool do_cast = false;
  if (kwds) {
    PyObject* cast = PyDict_GetItemString(kwds, "cast");
    do_cast = cast && PyObject_IsTrue(cast);
  }
 
  if (do_cast)
    return BindCppObject(addr, cast_type);
 
  return BindCppObjectNoCast(addr, cast_type);
}
 
//----------------------------------------------------------------------------
static PyObject* BindValue(PyObject*, PyObject* args, PyObject* kwds) {
  // Read through the converter for the given type name, at the given address.
  static const char* kwlist[] = {(char*)"type_name", (char*)"address",
                                 (char*)"dims", nullptr};
 
  const char* type_name = nullptr;
  PyObject* pyaddress = nullptr;
  PyObject* pydims = nullptr;
  if (!PyArg_ParseTupleAndKeywords(args, kwds, "sO|O:bind_value",
                                   (char**)kwlist, &type_name, &pyaddress,
                                   &pydims))
    return nullptr;
 
  void* address = PyLong_AsVoidPtr(pyaddress);
  if (PyErr_Occurred())
    return nullptr;
 
  std::vector<cpyrt::dim_t> dims;
  if (pydims && pydims != Py_None) {
    PyObject* seq =
        PySequence_Fast(pydims, "dims must be a sequence of integers");
    if (!seq)
      return nullptr;
    Py_ssize_t ndim = PySequence_Fast_GET_SIZE(seq);
    if (ndim == 0) {
      Py_DECREF(seq);
      PyErr_SetString(PyExc_ValueError, "dims must be a non-empty sequence");
      return nullptr;
    }
    dims.reserve(ndim);
    for (Py_ssize_t i = 0; i < ndim; ++i) {
      cpyrt::dim_t d =
          (cpyrt::dim_t)PyLong_AsSsize_t(PySequence_Fast_GET_ITEM(seq, i));
      if (d == (cpyrt::dim_t)-1 && PyErr_Occurred()) {
        Py_DECREF(seq);
        return nullptr;
      }
      // an UNKNOWN_SIZE view would keep the address of the pointer slot on
      // our expired stack frame as its data
      if (d < 0) {
        Py_DECREF(seq);
        PyErr_SetString(PyExc_ValueError, "dims entries must be non-negative");
        return nullptr;
      }
      dims.push_back(d);
    }
    Py_DECREF(seq);
 
    // scalar converters ignore dims entirely and would silently read the
    // pointer bits; only array and pointer type names can take a shape
    const std::string cpd = cpyrt::TypeManip::compound(type_name);
    if (cpd != "[]" && cpd != "*") {
      PyErr_Format(PyExc_TypeError,
                   "dims given but \'%s\' is not an array or pointer type",
                   type_name);
      return nullptr;
    }
  }
 
  // an unresolvable name crashes deeper down in the type lookup instead of
  // producing a nullptr converter, so validate first
  const std::string resolvedType = interop::ResolveName(type_name);
  const std::string baseType =
      cpyrt::TypeManip::clean_type(resolvedType, false, true);
  if (!interop::GetType(baseType, /* enable_slow_lookup */ true)) {
    PyErr_Format(PyExc_TypeError, "no converter available for type \'%s\'",
                 type_name);
    return nullptr;
  }
 
  cpyrt::Converter* cnv = cpyrt::CreateConverter(
      type_name, cpyrt::Dimensions((cpyrt::dim_t)dims.size(), dims.data()));
 
  // an array converter reads through the data pointer, so it wants the
  // address of that pointer; a scalar converter wants the address of the
  // value itself
  PyObject* result =
      dims.empty() ? cnv->FromMemory(address) : cnv->FromMemory(&address);
  cpyrt::DestroyConverter(cnv);
 
  if (!result && !PyErr_Occurred())
    PyErr_Format(PyExc_TypeError,
                 "failed to convert a value of type \'%s\' from memory",
                 type_name);
 
  return result;
}
 
//----------------------------------------------------------------------------
static PyObject* Move(PyObject*, PyObject* pyobject) {
  // Prepare the given C++ object for moving.
  if (!CPPInstance_Check(pyobject)) {
    PyErr_SetString(PyExc_TypeError, "C++ object expected");
    return nullptr;
  }
 
  ((CPPInstance*)pyobject)->fFlags |= CPPInstance::kIsRValue;
  Py_INCREF(pyobject);
  return pyobject;
}
 
//----------------------------------------------------------------------------
static PyObject* AddPythonization(PyObject*, PyObject* args) {
  // Remove a previously registered pythonizor from the given scope.
  PyObject* pythonizor = nullptr;
  const char* scope;
  if (!PyArg_ParseTuple(args, const_cast<char*>("Os"), &pythonizor, &scope))
    return nullptr;
 
  if (!PyCallable_Check(pythonizor)) {
    PyObject* pystr = PyObject_Str(pythonizor);
    PyErr_Format(PyExc_TypeError, "given \'%s\' object is not callable",
                 PyUnicode_AsUTF8(pystr));
    Py_DECREF(pystr);
    return nullptr;
  }
 
  Py_INCREF(pythonizor);
  pythonizations()[scope].push_back(pythonizor);
 
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* RemovePythonization(PyObject*, PyObject* args) {
  // Remove a previously registered pythonizor from the given scope.
  PyObject* pythonizor = nullptr;
  const char* scope;
  if (!PyArg_ParseTuple(args, const_cast<char*>("Os"), &pythonizor, &scope))
    return nullptr;
 
  auto& pyzMap = pythonizations();
  auto p1 = pyzMap.find(scope);
  if (p1 != pyzMap.end()) {
    auto p2 = std::find(p1->second.begin(), p1->second.end(), pythonizor);
    if (p2 != p1->second.end()) {
      p1->second.erase(p2);
      Py_RETURN_TRUE;
    }
  }
 
  Py_RETURN_FALSE;
}
 
//----------------------------------------------------------------------------
static PyObject* PinType(PyObject*, PyObject* pyclass) {
  // Add a pinning so that objects of type `derived' are interpreted as
  // objects of type `base'.
  if (!CPPScope_Check(pyclass)) {
    PyErr_SetString(PyExc_TypeError, "C++ class expected");
    return nullptr;
  }
 
  gPinnedTypes.insert(((CPPClass*)pyclass)->fCppType);
 
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* AddTypeReducer(PyObject*, PyObject* args) {
  // Add a type reducer to map type2 to type2 on function returns.
  const char *reducable, *reduced;
  if (!PyArg_ParseTuple(args, const_cast<char*>("ss"), &reducable, &reduced))
    return nullptr;
 
  interop::TCppType_t reducable_type =
      interop::GetTypeFromScope(interop::GetScope(reducable));
  interop::TCppType_t reduced_type =
      interop::GetTypeFromScope(interop::GetScope(reduced));
  TypeReductionMap[reducable_type] = reduced_type;
 
  Py_RETURN_NONE;
}
 
#define DEFINE_CALL_POLICY_TOGGLE(name, flagname)                              \
  static PyObject* name(PyObject*, PyObject* args) {                           \
    PyObject* enabled = 0;                                                     \
    if (!PyArg_ParseTuple(args, const_cast<char*>("O"), &enabled))             \
      return nullptr;                                                          \
                                                                               \
    if (CallContext::SetGlobalPolicy(CallContext::flagname,                    \
                                     PyObject_IsTrue(enabled))) {              \
      Py_RETURN_TRUE;                                                          \
    }                                                                          \
                                                                               \
    Py_RETURN_FALSE;                                                           \
  }
 
DEFINE_CALL_POLICY_TOGGLE(SetHeuristicMemoryPolicy, kUseHeuristics);
DEFINE_CALL_POLICY_TOGGLE(SetImplicitSmartPointerConversion,
                          kImplicitSmartPtrConversion);
DEFINE_CALL_POLICY_TOGGLE(SetGlobalSignalPolicy, kProtected);
 
//----------------------------------------------------------------------------
static PyObject* SetOwnership(PyObject*, PyObject* args) {
  // Set the ownership (True is python-owns) for the given object.
  CPPInstance* pyobj = nullptr;
  PyObject* pykeep = nullptr;
  if (!PyArg_ParseTuple(args, const_cast<char*>("O!O!"), &CPPInstance_Type,
                        (void*)&pyobj, &PyLong_Type, &pykeep))
    return nullptr;
 
  (bool)PyLong_AsLong(pykeep) ? pyobj->PythonOwns() : pyobj->CppOwns();
 
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* AddSmartPtrType(PyObject*, PyObject* args) {
  // Add a smart pointer to the list of known smart pointer types.
  const char* type_name;
  if (!PyArg_ParseTuple(args, const_cast<char*>("s"), &type_name))
    return nullptr;
 
  // interop::AddSmartPtrType(type_name);
 
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* BeginCaptureStderr(PyObject*, PyObject*) {
  gOldErrorBuffer = std::cerr.rdbuf();
  std::cerr.rdbuf(gCapturedError.rdbuf());
 
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* EndCaptureStderr(PyObject*, PyObject*) {
  // restore old rdbuf and return captured result
  std::cerr.rdbuf(gOldErrorBuffer);
  gOldErrorBuffer = nullptr;
 
  std::string capturedError = std::move(gCapturedError).str();
 
  gCapturedError.str("");
  gCapturedError.clear();
 
  return Py_BuildValue("s", capturedError.c_str());
}
} // unnamed namespace
 
//- data -----------------------------------------------------------------------
//----------------------------------------------------------------------------
static PyObject* LockInterpreter(PyObject*, PyObject*) {
  // release the GIL while waiting: the thread holding the interpreter lock
  // may need Python to finish
  Py_BEGIN_ALLOW_THREADS
  interop::LockInterpreter();
  Py_END_ALLOW_THREADS
  Py_RETURN_NONE;
}
 
//----------------------------------------------------------------------------
static PyObject* UnlockInterpreter(PyObject*, PyObject*) {
  interop::UnlockInterpreter();
  Py_RETURN_NONE;
}
 
static PyMethodDef gcpyrtMethods[] = {
    {(char*)"CreateScopeProxy", (PyCFunction)cpyrt::CreateScopeProxy,
     METH_VARARGS, (char*)"cppjit internal function"},
    {(char*)"MakeCppTemplateClass", (PyCFunction)MakeCppTemplateClass,
     METH_VARARGS, (char*)"cppjit internal function"},
    {(char*)"_DestroyPyStrings", (PyCFunction)cpyrt::DestroyPyStrings,
     METH_NOARGS, (char*)"cppjit internal function"},
    {(char*)"addressof", (PyCFunction)addressof, METH_VARARGS | METH_KEYWORDS,
     (char*)"Retrieve address of proxied object or field as a value."},
    {(char*)"as_cobject", (PyCFunction)AsCObject, METH_VARARGS | METH_KEYWORDS,
     (char*)"Retrieve address of proxied object or field in a CObject."},
    {(char*)"as_capsule", (PyCFunction)AsCapsule, METH_VARARGS | METH_KEYWORDS,
     (char*)"Retrieve address of proxied object or field in a PyCapsule."},
    {(char*)"as_ctypes", (PyCFunction)AsCTypes, METH_VARARGS | METH_KEYWORDS,
     (char*)"Retrieve address of proxied object or field in a ctypes "
            "c_void_p."},
    {(char*)"as_memoryview", (PyCFunction)AsMemoryView, METH_O,
     (char*)"Represent an array of objects as raw memory."},
    {(char*)"bind_object", (PyCFunction)BindObject,
     METH_VARARGS | METH_KEYWORDS,
     (char*)"Create an object of given type, from given address."},
    {(char*)"bind_value", (PyCFunction)BindValue, METH_VARARGS | METH_KEYWORDS,
     (char*)"Read a value of given type, from given address."},
    {(char*)"move", (PyCFunction)Move, METH_O,
     (char*)"Cast the C++ object to become movable."},
    {(char*)"add_pythonization", (PyCFunction)AddPythonization, METH_VARARGS,
     (char*)"Add a pythonizor."},
    {(char*)"remove_pythonization", (PyCFunction)RemovePythonization,
     METH_VARARGS, (char*)"Remove a pythonizor."},
    {(char*)"_pin_type", (PyCFunction)PinType, METH_O,
     (char*)"Install a type pinning."},
    {(char*)"_add_type_reducer", (PyCFunction)AddTypeReducer, METH_VARARGS,
     (char*)"Add a type reducer."},
    {(char*)"SetHeuristicMemoryPolicy", (PyCFunction)SetHeuristicMemoryPolicy,
     METH_VARARGS,
     (char*)"Set the global memory policy, which affects object ownership when "
            "objects are passed as function arguments."},
    {(char*)"SetImplicitSmartPointerConversion",
     (PyCFunction)SetImplicitSmartPointerConversion, METH_VARARGS,
     (char*)"Enable or disable the implicit conversion to smart pointers in "
            "function calls (on by default)."},
    {(char*)"SetGlobalSignalPolicy", (PyCFunction)SetGlobalSignalPolicy,
     METH_VARARGS,
     (char*)"Set the global signal policy, which determines whether a jmp "
            "address should be saved to return to after a "
            "C++ segfault. In practical terms: trap signals in safe mode to "
            "prevent interpreter abort."},
    {(char*)"SetOwnership", (PyCFunction)SetOwnership, METH_VARARGS,
     (char*)"Modify held C++ object ownership."},
    {(char*)"AddSmartPtrType", (PyCFunction)AddSmartPtrType, METH_VARARGS,
     (char*)"Add a smart pointer to the list of known smart pointer types."},
    {(char*)"_begin_capture_stderr", (PyCFunction)BeginCaptureStderr,
     METH_NOARGS, (char*)"Begin capturing stderr to a in memory buffer."},
    {(char*)"_end_capture_stderr", (PyCFunction)EndCaptureStderr, METH_NOARGS,
     (char*)"End capturing stderr and returns the captured buffer."},
    {(char*)"_lock_interpreter", (PyCFunction)LockInterpreter, METH_NOARGS,
     (char*)"Take the interpreter lock; pair with _unlock_interpreter."},
    {(char*)"_unlock_interpreter", (PyCFunction)UnlockInterpreter,
     METH_NOARGS, (char*)"Release the lock taken by _lock_interpreter."},
    {nullptr, nullptr, 0, nullptr}};
 
struct module_state {
  PyObject* error;
};
 
#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
 
static int cpycppjitmodule_traverse(PyObject* m, visitproc visit, void* arg) {
  Py_VISIT(GETSTATE(m)->error);
  return 0;
}
 
static int cpycppjitmodule_clear(PyObject* m) {
  Py_CLEAR(GETSTATE(m)->error);
  return 0;
}
 
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,       "libcppjit",           nullptr,
    sizeof(struct module_state), gcpyrtMethods,         nullptr,
    cpycppjitmodule_traverse,    cpycppjitmodule_clear, nullptr};
 
namespace cppjit::cpyrt {
 
//----------------------------------------------------------------------------
PyObject* Init() {
  // Initialization of extension module libcppjit.
 
  // load commonly used python strings
  if (!cpyrt::CreatePyStrings())
    return nullptr;
 
  // setup this module
  gThisModule = PyModule_Create(&moduledef);
  if (!gThisModule)
    return nullptr;
 
  // keep gThisModule, but do not increase its reference count even as it is
  // borrowed, or a self-referencing cycle would be created
 
  // external types
  gPyTypeMap = PyDict_New();
  PyModule_AddObject(gThisModule, "type_map", gPyTypeMap); // steals reference
 
  // Pythonizations ...
  PyModule_AddObject(gThisModule, "UserExceptions", PyDict_New());
 
  // inject meta type
  if (!Utility::InitProxy(gThisModule, &CPPScope_Type, "CPPScope"))
    return nullptr;
 
  // inject object proxy type
  if (!Utility::InitProxy(gThisModule, &CPPInstance_Type, "CPPInstance"))
    return nullptr;
 
  // inject exception object proxy type
  if (!Utility::InitProxy(gThisModule, &CPPExcInstance_Type, "CPPExcInstance"))
    return nullptr;
 
  // inject method proxy type
  if (!Utility::InitProxy(gThisModule, &CPPOverload_Type, "CPPOverload"))
    return nullptr;
 
  // inject template proxy type
  if (!Utility::InitProxy(gThisModule, &TemplateProxy_Type, "TemplateProxy"))
    return nullptr;
 
  // inject property proxy type
  if (!Utility::InitProxy(gThisModule, &CPPDataMember_Type, "CPPDataMember"))
    return nullptr;
 
  if (!Utility::InitProxy(gThisModule, &CustomInstanceMethod_Type,
                          "InstanceMethod"))
    return nullptr;
 
  if (!Utility::InitProxy(gThisModule, &TupleOfInstances_Type, "InstanceArray"))
    return nullptr;
 
  if (!Utility::InitProxy(gThisModule, &LowLevelView_Type, "LowLevelView"))
    return nullptr;
 
  if (!Utility::InitProxy(gThisModule, &PyNullPtr_t_Type, "nullptr_t"))
    return nullptr;
 
  // custom iterators
  if (PyType_Ready(&InstanceArrayIter_Type) < 0)
    return nullptr;
 
  if (PyType_Ready(&IndexIter_Type) < 0)
    return nullptr;
 
  if (PyType_Ready(&VectorIter_Type) < 0)
    return nullptr;
 
  // inject identifiable nullptr and default
  gNullPtrObject = (PyObject*)&_cpyrt_NullPtrStruct;
  Py_INCREF(gNullPtrObject);
  PyModule_AddObject(gThisModule, (char*)"nullptr", gNullPtrObject);
 
  gDefaultObject = (PyObject*)&_cpyrt_DefaultStruct;
  Py_INCREF(gDefaultObject);
  PyModule_AddObject(gThisModule, (char*)"default", gDefaultObject);
 
  // C++-specific exceptions
  PyObject* cppfatal =
      PyErr_NewException((char*)"cppjit.ll.FatalError", nullptr, nullptr);
  PyModule_AddObject(gThisModule, (char*)"FatalError", cppfatal);
 
  gBusException =
      PyErr_NewException((char*)"cppjit.ll.BusError", cppfatal, nullptr);
  PyModule_AddObject(gThisModule, (char*)"BusError", gBusException);
  gSegvException = PyErr_NewException((char*)"cppjit.ll.SegmentationViolation",
                                      cppfatal, nullptr);
  PyModule_AddObject(gThisModule, (char*)"SegmentationViolation",
                     gSegvException);
  gIllException = PyErr_NewException((char*)"cppjit.ll.IllegalInstruction",
                                     cppfatal, nullptr);
  PyModule_AddObject(gThisModule, (char*)"IllegalInstruction", gIllException);
  gAbrtException =
      PyErr_NewException((char*)"cppjit.ll.AbortSignal", cppfatal, nullptr);
  PyModule_AddObject(gThisModule, (char*)"AbortSignal", gAbrtException);
 
  // gbl namespace is injected in cppjit.py
 
  // create the memory regulator
  static MemoryRegulator s_memory_regulator;
 
  Py_INCREF(gThisModule);
  return gThisModule;
}
 
} // namespace cppjit::cpyrt