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         obj._ptr = ptr
  76         obj._owner_ptr = owner_ptr
  77         obj._owner_put_ref = owner_put_ref
  78         owner_get_ref(obj._owner_ptr)
  79         return obj
  80
  81     def __del__(self):
  82         self._owner_put_ref(self._owner_ptr)
  83
  84
  85 # Python object that owns a reference to a Babeltrace object.
  86 class _SharedObject(_BaseObject):
  87
  88     # Get a new reference on ptr.
  89     #
  90     # This must be implemented by subclasses to work correctly with a pointer
  91     # of the native type they wrap.
  92
  93     @staticmethod
  94     def _get_ref(ptr):
  95         raise NotImplementedError
  96
  97     # Put a reference on ptr.
  98     #
  99     # This must be implemented by subclasses to work correctly with a pointer
 100     # of the native type they wrap.
 101
 102     @staticmethod
 103     def _put_ref(ptr):
 104         raise NotImplementedError
 105
 106     # Create a _SharedObject from an existing reference.
 107     #
 108     # This assumes that the caller owns a reference to the Babeltrace object
 109     # and transfers this ownership to the newly created Python object.
 110
 111     @classmethod
 112     def _create_from_ptr(cls, ptr_owned):
 113         obj = cls.__new__(cls)
 114         obj._ptr = ptr_owned
 115         return obj
 116
 117     # Like _create_from_ptr, but acquire a new reference rather than
 118     # stealing the caller's reference.
 119
 120     @classmethod
 121     def _create_from_ptr_and_get_ref(cls, ptr):
 122         obj = cls._create_from_ptr(ptr)
 123         cls._get_ref(obj._ptr)
 124         return obj
 125
 126     def _release(self):
 127         """Return the wrapped pointer, transfer its ownership to the
 128         caller."""
 129         ptr = self._ptr
 130         self._ptr = None
 131         return ptr
 132
 133     def __del__(self):
 134         self._put_ref(self._ptr)