Re: [RFC 1/4] Add gdbpy_borrowed_ref

[Simon Marchi <simark@simark.ca>]

On 2026-02-22 14:49, Tom Tromey wrote:
> 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 | 47 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)
> 
> diff --git a/gdb/python/py-ref.h b/gdb/python/py-ref.h
> index 0a56436634d..56508996eaa 100644
> --- a/gdb/python/py-ref.h
> +++ b/gdb/python/py-ref.h
> @@ -41,6 +41,53 @@ 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.  */
> +class gdbpy_borrowed_ref
> +{
> +public:
> +
> +  gdbpy_borrowed_ref (PyObject *obj)
> +    : m_obj (obj)
> +  {
> +  }
> +
> +  template<typename T>
> +  gdbpy_borrowed_ref (const gdbpy_ref<T> &ref)
> +    : m_obj (ref.get ())
> +  {
> +  }
> +
> +  /* Allow a (checked) conversion to any subclass of PyObject.  */
> +  template<typename T,
> +	   typename = std::is_convertible<T *, PyObject *>>
> +  operator T * ()
> +  {
> +    gdb_assert (PyObject_TypeCheck (m_obj, T::corresponding_object_type));
> +    return static_cast<T *> (m_obj);
> +  }

Shouldn't gdbpy_borrowed_ref be templated?  Allowing any gdbpy_ref to be
downcast to any subclass of PyObject seems a bit permissive.  At least
there is a runtime check, but it would be nice to have more type safety
at compile time.

I imagine:

  arch_object *arch = gdbpy_borrowed_ref<arch_object> (...);  // works
  arch_object *arch = gdbpy_borrowed_ref<PyObject> (...);  // does not work

That being said, apart from the wrappers themselves, I don't expect that
we'll need to do that often.  I suppose that it would be possible to
access the fields like this?

gdbpy_borrowed_ref<arch_object> obj;
obj->gdbarch; // accesses arch_object::gdbarch

I also toyed with defining some types like:

struct PyDict : public PyObject {};
struct PyList : public PyObject {};
struct PyLong : public PyObject {};
struct PyTuple : public PyObject {};
struct PyType : public PyObject {};

gdbpy_new_list would return a gdbpy_ref<PyList>.
gdbpy_list_append would take a gdbpy_borrowed_ref<PyList>.

And then we could have some ways of down-casting, if needed.

Simon