bindings/python/bt2/bt2/object.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23
  24 class _BaseObject:
  25     # Ensure that the object always has _ptr set, even if it throws during
  26     # construction.
  27
  28     def __new__(cls, *args, **kwargs):
  29         obj = super().__new__(cls)
  30         obj._ptr = None
  31         return obj
  32
  33     def __init__(self, ptr):
  34         self._ptr = ptr
  35
  36     @property
  37     def addr(self):
  38         return int(self._ptr)
  39
  40     def __repr__(self):
  41         return '<{}.{} object @ {}>'.format(self.__class__.__module__,
  42                                             self.__class__.__name__,
  43                                             hex(self.addr))
  44
  45     def __copy__(self):
  46         raise NotImplementedError
  47
  48     def __deepcopy__(self, memo):
  49         raise NotImplementedError
  50
  51
  52 # A Python object that is itself not refcounted, but is wholly owned by an
  53 # object that is itself refcounted (a _SharedObject).  A Babeltrace unique
  54 # object gets destroyed once its owner gets destroyed (its refcount drops to
  55 # 0).
  56 #
  57 # In the Python bindings, to avoid having to deal with issues with the lifetime
  58 # of unique objects, we make it so acquiring a reference on a unique object
  59 # acquires a reference on its owner.
  60
  61 class _UniqueObject(_BaseObject):
  62
  63     # Create a _UniqueObject.
  64     #
  65     #   - ptr: SWIG Object, pointer to the unique object.
  66     #   - owner_ptr: SWIG Object, pointer to the owner of the unique
  67     #     object.  A new reference is acquired.
  68     #   - owner_get_ref: Callback to get a reference on the owner
  69     #   - owner_put_ref: Callback to put a reference on the owner.
  70
  71     @classmethod
  72     def _create_from_ptr_and_get_ref(cls, ptr, owner_ptr,
  73                                      owner_get_ref, owner_put_ref):
  74         obj = cls.__new__(cls)
  75
  76         obj._ptr = ptr
  77         obj._owner_ptr = owner_ptr
  78         obj._owner_get_ref = owner_get_ref
  79         obj._owner_put_ref = owner_put_ref
  80
  81         obj._owner_get_ref(obj._owner_ptr)
  82
  83         return obj
  84
  85     def __del__(self):
  86         self._owner_put_ref(self._owner_ptr)
  87
  88
  89 # Python object that owns a reference to a Babeltrace object.
  90 class _SharedObject(_BaseObject):
  91
  92     # Get a new reference on ptr.
  93     #
  94     # This must be implemented by subclasses to work correctly with a pointer
  95     # of the native type they wrap.
  96
  97     @staticmethod
  98     def _get_ref(ptr):
  99         raise NotImplementedError
 100
 101     # Put a reference on ptr.
 102     #
 103     # This must be implemented by subclasses to work correctly with a pointer
 104     # of the native type they wrap.
 105
 106     @staticmethod
 107     def _put_ref(ptr):
 108         raise NotImplementedError
 109
 110     # Create a _SharedObject from an existing reference.
 111     #
 112     # This assumes that the caller owns a reference to the Babeltrace object
 113     # and transfers this ownership to the newly created Python object.
 114
 115     @classmethod
 116     def _create_from_ptr(cls, ptr_owned):
 117         obj = cls.__new__(cls)
 118         obj._ptr = ptr_owned
 119         return obj
 120
 121     # Like _create_from_ptr, but acquire a new reference rather than
 122     # stealing the caller's reference.
 123
 124     @classmethod
 125     def _create_from_ptr_and_get_ref(cls, ptr):
 126         obj = cls._create_from_ptr(ptr)
 127         cls._get_ref(obj._ptr)
 128         return obj
 129
 130     def _release(self):
 131         """Return the wrapped pointer, transfer its ownership to the
 132         caller."""
 133         ptr = self._ptr
 134         self._ptr = None
 135         return ptr
 136
 137     def __del__(self):
 138         self._put_ref(self._ptr)