gdb/python/py-ref.h

   1 /* Python reference-holding class
   2
   3    Copyright (C) 2016 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef GDB_PYTHON_REF_H
  21 #define GDB_PYTHON_REF_H
  22
  23 /* An instance of this class either holds a reference to a PyObject,
  24    or is "NULL".  If it holds a reference, then when the object is
  25    destroyed, the PyObject is decref'd.
  26
  27    Normally an instance is constructed using a PyObject*.  This sort
  28    of initialization lets this class manage the lifetime of that
  29    reference.
  30
  31    Assignment and copy construction will make a new reference as
  32    appropriate.  Assignment from a plain PyObject* is disallowed to
  33    avoid confusion about whether this acquires a new reference;
  34    instead use the "reset" method -- which, like the PyObject*
  35    constructor, transfers ownership.
  36 */
  37 class gdbpy_ref
  38 {
  39  public:
  40
  41   /* Create a new NULL instance.  */
  42   gdbpy_ref ()
  43     : m_obj (NULL)
  44   {
  45   }
  46
  47   /* Create a new instance.  OBJ is a reference, management of which
  48      is now transferred to this class.  */
  49   explicit gdbpy_ref (PyObject *obj)
  50     : m_obj (obj)
  51   {
  52   }
  53
  54   /* Copy another instance.  */
  55   gdbpy_ref (const gdbpy_ref &other)
  56     : m_obj (other.m_obj)
  57   {
  58     Py_XINCREF (m_obj);
  59   }
  60
  61   /* Transfer ownership from OTHER.  */
  62   gdbpy_ref (gdbpy_ref &&other)
  63     : m_obj (other.m_obj)
  64   {
  65     other.m_obj = NULL;
  66   }
  67
  68   /* Destroy this instance.  */
  69   ~gdbpy_ref ()
  70   {
  71     Py_XDECREF (m_obj);
  72   }
  73
  74   /* Copy another instance.  */
  75   gdbpy_ref &operator= (const gdbpy_ref &other)
  76   {
  77     /* Do nothing on self-assignment.  */
  78     if (this != &other)
  79       {
  80         reset (other.m_obj);
  81         Py_XINCREF (m_obj);
  82       }
  83     return *this;
  84   }
  85
  86   /* Transfer ownership from OTHER.  */
  87   gdbpy_ref &operator= (gdbpy_ref &&other)
  88   {
  89     /* Do nothing on self-assignment.  */
  90     if (this != &other)
  91       {
  92         reset (other.m_obj);
  93         other.m_obj = NULL;
  94       }
  95     return *this;
  96   }
  97
  98   /* Change this instance's referent.  OBJ is a reference, management
  99      of which is now transferred to this class.  */
 100   void reset (PyObject *obj)
 101   {
 102     Py_XDECREF (m_obj);
 103     m_obj = obj;
 104   }
 105
 106   /* Return this instance's referent.  In Python terms this is a
 107      borrowed pointer.  */
 108   PyObject *get () const
 109   {
 110     return m_obj;
 111   }
 112
 113   /* Return this instance's referent, and stop managing this
 114      reference.  The caller is now responsible for the ownership of
 115      the reference.  */
 116   PyObject *release ()
 117   {
 118     PyObject *result = m_obj;
 119
 120     m_obj = NULL;
 121     return result;
 122   }
 123
 124  private:
 125
 126   PyObject *m_obj;
 127 };
 128
 129 inline bool operator== (const gdbpy_ref &self, const gdbpy_ref &other)
 130 {
 131   return self.get () == other.get ();
 132 }
 133
 134 inline bool operator== (const gdbpy_ref &self, const PyObject *other)
 135 {
 136   return self.get () == other;
 137 }
 138
 139 inline bool operator== (const PyObject *self, const gdbpy_ref &other)
 140 {
 141   return self == other.get ();
 142 }
 143
 144 inline bool operator!= (const gdbpy_ref &self, const gdbpy_ref &other)
 145 {
 146   return self.get () != other.get ();
 147 }
 148
 149 inline bool operator!= (const gdbpy_ref &self, const PyObject *other)
 150 {
 151   return self.get () != other;
 152 }
 153
 154 inline bool operator!= (const PyObject *self, const gdbpy_ref &other)
 155 {
 156   return self != other.get ();
 157 }
 158
 159 #endif /* GDB_PYTHON_REF_H */