[PATCH v1 1/4] gdb/python: add gdbpy_borrowed_ref

[Matthieu Longo <matthieu.longo@arm.com>]

From: Tom Tromey <tom@tromey.com>

This adds a new gdbpy_borrowed_ref class.  This class is primarily for
code "documentation" purposes -- it makes it clear to the reader that
a given reference is borrowed.  However, it also adds a tiny bit of
safety, in that conversion to gdbpy_ref<> will acquire a new
reference.
---
 gdb/python/py-ref.h | 114 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/gdb/python/py-ref.h b/gdb/python/py-ref.h
index dc0b14814af..80a08b55288 100644
--- a/gdb/python/py-ref.h
+++ b/gdb/python/py-ref.h
@@ -41,6 +41,120 @@ struct gdbpy_ref_policy
 template<typename T = PyObject> using gdbpy_ref
   = gdb::ref_ptr<T, gdbpy_ref_policy>;
 
+/* A class representing a borrowed reference.
+
+   This is a simple wrapper for a PyObject*.  Aside from documenting
+   what the code does, the main advantage of using this is that
+   conversion to a gdbpy_ref<> is guaranteed to make a new
+   reference.  */
+template <class T = PyObject>
+class gdbpy_borrowed_ref
+{
+public:
+
+  gdbpy_borrowed_ref () noexcept
+    : m_obj (nullptr)
+  {
+  }
+
+  gdbpy_borrowed_ref (const std::nullptr_t) noexcept
+    : m_obj (nullptr)
+  {
+  }
+
+  template <typename U,
+	    typename = std::is_convertible<U *, T*>>
+  gdbpy_borrowed_ref (U *obj) noexcept
+    : m_obj (obj)
+  {
+  }
+
+  template <typename U,
+	    typename = std::is_convertible<U *, T*>>
+  gdbpy_borrowed_ref (const gdbpy_ref<U> &ref) noexcept
+    : m_obj (ref.get ())
+  {
+  }
+
+  gdbpy_borrowed_ref (const gdbpy_borrowed_ref &other) noexcept
+    : m_obj (other.m_obj)
+  {
+  }
+
+  gdbpy_borrowed_ref &operator= (const gdbpy_borrowed_ref &other)
+  {
+    m_obj = other.m_obj;
+    return *this;
+  }
+
+  /* Allow a (checked) conversion to any subclass of PyObject.  */
+  template<typename TObj,
+	   typename = std::is_convertible<TObj *, T *>>
+  operator TObj * ()
+  {
+    //gdb_assert (PyObject_TypeCheck (m_obj, T::corresponding_object_type));
+    return static_cast<TObj *> (m_obj);
+  }
+
+  operator T * () const noexcept
+  {
+    return m_obj;
+  }
+
+  /* When converting a borrowed reference to a gdbpy_ref<>, a new
+     reference is acquired.  */
+  template <typename TObj,
+	    typename = std::is_convertible<TObj *, T *>>
+  operator gdbpy_ref<TObj> ()
+  {
+    gdb_assert (m_obj != nullptr);
+    return gdbpy_ref<TObj>::new_reference (m_obj);
+  }
+
+  gdbpy_ref<T> strong_ref () const noexcept
+  {
+    return static_cast<gdbpy_ref<T>> (*this);
+  }
+
+  /* Let users refer to members of the underlying pointer.  */
+  T *operator-> () const noexcept
+  {
+    return m_obj;
+  }
+
+  T *get () const noexcept
+  {
+    return m_obj;
+  }
+
+private:
+  T *m_obj;
+};
+
+template<typename T>
+inline bool operator== (const gdbpy_borrowed_ref<T> &lhs, const std::nullptr_t)
+{
+  return lhs.get () == nullptr;
+}
+
+template<typename T>
+inline bool operator!= (const gdbpy_borrowed_ref<T> &lhs, const std::nullptr_t)
+{
+  return lhs.get () != nullptr;
+}
+
+template<typename T>
+inline bool operator== (const std::nullptr_t, const gdbpy_borrowed_ref<T> &rhs)
+{
+  return nullptr == rhs.get ();
+}
+
+template<typename T>
+inline bool operator!= (const std::nullptr_t, const gdbpy_borrowed_ref<T> &rhs)
+{
+  return nullptr != rhs.get ();
+}
+
 /* A wrapper class for Python extension objects that have a __dict__ attribute.
 
    Any Python C object extension needing __dict__ should inherit from this
-- 
2.53.0