1 # The MIT License (MIT)
3 # Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
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:
12 # The above copyright notice and this permission notice shall be included in
13 # all copies or substantial portions of the Software.
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
23 from bt2
import native_bt
, object, utils
24 import bt2
.notification_iterator
25 import collections
.abc
30 # This class wraps a component class pointer. This component class could
31 # have been created by Python code, but since we only have the pointer,
32 # we can only wrap it in a generic way and lose the original Python
34 class _GenericComponentClass(object._Object
):
37 return native_bt
.component_class_get_name(self
._ptr
)
40 def description(self
):
41 return native_bt
.component_class_get_description(self
._ptr
)
45 return native_bt
.component_class_get_help(self
._ptr
)
47 def __call__(self
, params
=None, name
=None):
48 params
= bt2
.create_value(params
)
49 comp_ptr
= native_bt
.component_create_with_init_method_data(self
._ptr
,
55 raise bt2
.CreationError('cannot create component object')
57 return _create_generic_component_from_ptr(comp_ptr
)
60 class _GenericSourceComponentClass(_GenericComponentClass
):
64 class _GenericFilterComponentClass(_GenericComponentClass
):
68 class _GenericSinkComponentClass(_GenericComponentClass
):
72 # This class holds the methods which are common to both generic
73 # component objects and Python user component objects. They use the
74 # internal native _ptr, however it was set, to call native API
76 class _CommonComponentMethods
:
79 return native_bt
.component_get_name(self
._ptr
)
82 def component_class(self
):
83 cc_ptr
= native_bt
.component_get_class(self
._ptr
)
84 utils
._handle
_ptr
(cc_ptr
, "cannot get component object's class object")
85 return _create_generic_component_class_from_ptr(cc_ptr
)
87 def _handle_status(self
, status
, gen_error_msg
):
88 if status
== native_bt
.COMPONENT_STATUS_END
:
90 elif status
== native_bt
.COMPONENT_STATUS_AGAIN
:
92 elif status
== native_bt
.COMPONENT_STATUS_UNSUPPORTED
:
93 raise bt2
.UnsupportedFeature
95 raise bt2
.Error(gen_error_msg
)
98 class _CommonSourceComponentMethods(_CommonComponentMethods
):
99 def create_notification_iterator(self
):
100 iter_ptr
= native_bt
.component_source_create_notification_iterator_with_init_method_data(self
._ptr
, None)
103 raise bt2
.CreationError('cannot create notification iterator object')
105 return bt2
.notification_iterator
._GenericNotificationIterator
._create
_from
_ptr
(iter_ptr
)
108 class _CommonFilterComponentMethods(_CommonComponentMethods
):
109 def create_notification_iterator(self
):
110 iter_ptr
= native_bt
.component_filter_create_notification_iterator_with_init_method_data(self
._ptr
, None)
113 raise bt2
.CreationError('cannot create notification iterator object')
115 return bt2
.notification_iterator
._GenericNotificationIterator
._create
_from
_ptr
(iter_ptr
)
117 def add_notification_iterator(self
, notif_iter
):
118 utils
._check
_type
(notif_iter
, bt2
.notification_iterator
._GenericNotificationIteratorMethods
)
119 status
= native_bt
.component_filter_add_iterator(self
._ptr
, notif_iter
._ptr
)
120 self
._handle
_status
(status
, 'unexpected error: cannot add notification iterator to filter component object')
123 class _CommonSinkComponentMethods(_CommonComponentMethods
):
124 def add_notification_iterator(self
, notif_iter
):
125 utils
._check
_type
(notif_iter
, bt2
.notification_iterator
._GenericNotificationIteratorMethods
)
126 status
= native_bt
.component_sink_add_iterator(self
._ptr
, notif_iter
._ptr
)
127 self
._handle
_status
(status
, 'unexpected error: cannot add notification iterator to sink component object')
130 status
= native_bt
.component_sink_consume(self
._ptr
)
131 self
._handle
_status
(status
, 'unexpected error: cannot consume sink component object')
134 # This is analogous to _GenericSourceComponentClass, but for source
136 class _GenericSourceComponent(object._Object
, _CommonSourceComponentMethods
):
140 # This is analogous to _GenericFilterComponentClass, but for filter
142 class _GenericFilterComponent(object._Object
, _CommonFilterComponentMethods
):
146 # This is analogous to _GenericSinkComponentClass, but for sink
148 class _GenericSinkComponent(object._Object
, _CommonSinkComponentMethods
):
152 _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS
= {
153 native_bt
.COMPONENT_CLASS_TYPE_SOURCE
: _GenericSourceComponent
,
154 native_bt
.COMPONENT_CLASS_TYPE_FILTER
: _GenericFilterComponent
,
155 native_bt
.COMPONENT_CLASS_TYPE_SINK
: _GenericSinkComponent
,
159 _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS_CLS
= {
160 native_bt
.COMPONENT_CLASS_TYPE_SOURCE
: _GenericSourceComponentClass
,
161 native_bt
.COMPONENT_CLASS_TYPE_FILTER
: _GenericFilterComponentClass
,
162 native_bt
.COMPONENT_CLASS_TYPE_SINK
: _GenericSinkComponentClass
,
166 def _create_generic_component_from_ptr(ptr
):
167 comp_cls_type
= native_bt
.component_get_class_type(ptr
)
168 return _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS
[comp_cls_type
]._create
_from
_ptr
(ptr
)
171 def _create_generic_component_class_from_ptr(ptr
):
172 comp_cls_type
= native_bt
.component_class_get_type(ptr
)
173 return _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS_CLS
[comp_cls_type
]._create
_from
_ptr
(ptr
)
176 def _trim_docstring(docstring
):
177 lines
= docstring
.expandtabs().splitlines()
180 for line
in lines
[1:]:
181 stripped
= line
.lstrip()
184 indent
= min(indent
, len(line
) - len(stripped
))
186 trimmed
= [lines
[0].strip()]
188 if indent
< sys
.maxsize
:
189 for line
in lines
[1:]:
190 trimmed
.append(line
[indent
:].rstrip())
192 while trimmed
and not trimmed
[-1]:
195 while trimmed
and not trimmed
[0]:
198 return '\n'.join(trimmed
)
201 # Metaclass for component classes defined by Python code.
203 # The Python user can create a standard Python class which inherits one
204 # of the three base classes (UserSourceComponent, UserFilterComponent,
205 # or UserSinkComponent). Those base classes set this class
206 # (_UserComponentType) as their metaclass.
208 # Once the body of a user-defined component class is executed, this
209 # metaclass is used to create and initialize the class. The metaclass
210 # creates a native BT component class of the corresponding type and
211 # associates it with this user-defined class. The metaclass also defines
212 # class methods like the `name` and `description` properties to match
213 # the _GenericComponentClass interface.
215 # The component class name which is used is either:
217 # * The `name` parameter of the class:
219 # class MySink(bt2.SinkComponent, name='my-custom-sink'):
222 # * If the `name` class parameter is not used: the name of the class
223 # itself (`MySink` in the example above).
225 # The component class description which is used is the user-defined
228 # class MySink(bt2.SinkComponent):
229 # 'Description goes here'
232 # A user-defined Python component class can have an __init__() method
233 # which must at least accept the `params` and `name` arguments:
235 # def __init__(self, params, name, something_else):
238 # The user-defined component class can also have a _destroy() method
239 # (do NOT use __del__()) to be notified when the component object is
240 # (really) destroyed.
242 # User-defined source and filter component classes must use the
243 # `notification_iterator_class` class parameter to specify the
244 # notification iterator class to use for this component class:
246 # class MyNotificationIterator(bt2.UserNotificationIterator):
249 # class MySource(bt2.UserSourceComponent,
250 # notification_iterator_class=MyNotificationIterator):
253 # This notification iterator class must inherit
254 # bt2.UserNotificationIterator, and it must define the _get() and
255 # _next() methods. The notification iterator class can also define an
256 # __init__() method: this method has access to the original Python
257 # component object which was used to create it as the `component`
258 # property. The notification iterator class can also define a _destroy()
259 # method (again, do NOT use __del__()): this is called when the
260 # notification iterator is (really) destroyed.
262 # When the user-defined class is destroyed, this metaclass's __del__()
263 # method is called: the native BT component class pointer is put (not
264 # needed anymore, at least not by any Python code since all references
265 # are dropped for __del__() to be called).
266 class _UserComponentType(type):
267 # __new__() is used to catch custom class parameters
268 def __new__(meta_cls
, class_name
, bases
, attrs
, **kwargs
):
269 return super().__new
__(meta_cls
, class_name
, bases
, attrs
)
271 def __init__(cls
, class_name
, bases
, namespace
, **kwargs
):
272 super().__init
__(class_name
, bases
, namespace
)
274 # skip our own bases; they are never directly instantiated by the user
275 if class_name
in ('_UserComponent', 'UserSourceComponent', 'UserFilterComponent', 'UserSinkComponent'):
278 comp_cls_name
= kwargs
.get('name', class_name
)
279 comp_cls_descr
= None
282 if hasattr(cls
, '__doc__') and cls
.__doc
__ is not None:
283 docstring
= _trim_docstring(cls
.__doc
__)
284 lines
= docstring
.splitlines()
287 comp_cls_descr
= lines
[0]
290 comp_cls_help
= '\n'.join(lines
[2:])
292 iter_cls
= kwargs
.get('notification_iterator_class')
294 if UserSourceComponent
in bases
:
295 _UserComponentType
._set
_iterator
_class
(cls
, iter_cls
)
296 has_seek_time
= _UserComponentType
._has
_seek
_to
_time
_method
(cls
._iter
_cls
)
297 cc_ptr
= native_bt
.py3_component_class_source_create(cls
,
302 elif UserFilterComponent
in bases
:
303 _UserComponentType
._set
_iterator
_class
(cls
, iter_cls
)
304 has_seek_time
= _UserComponentType
._has
_seek
_to
_time
_method
(cls
._iter
_cls
)
305 cc_ptr
= native_bt
.py3_component_class_filter_create(cls
,
310 elif UserSinkComponent
in bases
:
311 if not hasattr(cls
, '_consume'):
312 raise bt2
.IncompleteUserClassError("cannot create component class '{}': missing a _consume() method".format(class_name
))
314 cc_ptr
= native_bt
.py3_component_class_sink_create(cls
,
319 raise bt2
.IncompleteUserClassError("cannot find a known component class base in the bases of '{}'".format(class_name
))
322 raise bt2
.CreationError("cannot create component class '{}'".format(class_name
))
326 def __call__(cls
, *args
, **kwargs
):
328 self
= cls
.__new
__(cls
)
330 # assign native component pointer received from caller
331 self
._ptr
= kwargs
.get('__comp_ptr')
332 name
= kwargs
.get('name')
334 if self
._ptr
is None:
335 # called from Python code
336 self
._belongs
_to
_native
_component
= False
338 # py3_component_create() will call self.__init__() with the
339 # desired arguments and keyword arguments. This is needed
340 # because functions such as
341 # bt_component_sink_set_minimum_input_count() can only be
342 # called _during_ the bt_component_create() call (in
343 # Python words: during self.__init__()).
345 # The arguments and keyword arguments to use for
346 # self.__init__() are put in the object itself to find them
347 # from the bt_component_create() function.
348 self
._init
_args
= args
349 self
._init
_kwargs
= kwargs
350 native_bt
.py3_component_create(cls
._cc
_ptr
, self
, name
)
352 # At this point, self._ptr should be set to non-None. If
353 # it's not, an error occured during the
354 # native_bt.py3_component_create() call. We consider this a
356 if self
._ptr
is None:
357 raise bt2
.CreationError("cannot create component object from component class '{}'".format(cls
.__name
__))
359 # Called from non-Python code (within
360 # bt_component_create()): call __init__() here, after
361 # removing the __comp_ptr keyword argument which is just for
362 # this __call__() method.
363 self
._belongs
_to
_native
_component
= True
364 del kwargs
['__comp_ptr']
366 # inject `name` into the keyword arguments
367 kwargs
['name'] = self
.name
368 self
.__init
__(*args
, **kwargs
)
373 def _has_seek_to_time_method(iter_cls
):
374 return hasattr(iter_cls
, '_seek_to_time')
377 def _set_iterator_class(cls
, iter_cls
):
379 raise bt2
.IncompleteUserClassError("cannot create component class '{}': missing notification iterator class".format(cls
.__name
__))
381 if not issubclass(iter_cls
, bt2
.notification_iterator
.UserNotificationIterator
):
382 raise bt2
.IncompleteUserClassError("cannot create component class '{}': notification iterator class does not inherit bt2.UserNotificationIterator".format(cls
.__name
__))
384 if not hasattr(iter_cls
, '_get'):
385 raise bt2
.IncompleteUserClassError("cannot create component class '{}': notification iterator class is missing a _get() method".format(cls
.__name
__))
387 if not hasattr(iter_cls
, '_next'):
388 raise bt2
.IncompleteUserClassError("cannot create component class '{}': notification iterator class is missing a _next() method".format(cls
.__name
__))
390 cls
._iter
_cls
= iter_cls
394 return native_bt
.component_class_get_name(cls
._cc
_ptr
)
397 def description(cls
):
398 return native_bt
.component_class_get_description(cls
._cc
_ptr
)
402 return native_bt
.component_class_get_help(cls
._cc
_ptr
)
406 return int(cls
._cc
_ptr
)
409 if hasattr(cls
, '_cc_ptr'):
410 native_bt
.put(cls
._cc
_ptr
)
413 class _ComponentInputNotificationIterators(collections
.abc
.Sequence
):
414 def __init__(self
, comp
, count_func
, get_func
):
416 self
._count
_func
= count_func
417 self
._get
_func
= get_func
420 status
, count
= self
._count
_func
(self
._comp
._ptr
)
421 utils
._handle
_ret
(status
, "cannot get component object's input notification iterator count")
424 def __getitem__(self
, index
):
425 utils
._check
_uint
64(index
)
427 if index
>= len(self
):
430 notif_iter_ptr
= self
._get
_func
(self
._comp
._ptr
, index
)
431 utils
._handle
_ptr
(notif_iter_ptr
, "cannot get component object's input notification iterator")
432 return bt2
.notification_iterator
._GenericNotificationIterator
._create
_from
_ptr
(notif_iter_ptr
)
435 class _UserComponent(metaclass
=_UserComponentType
):
438 return int(self
._ptr
)
440 def __init__(self
, *args
, **kwargs
):
447 if not self
._belongs
_to
_native
_component
:
448 self
._belongs
_to
_native
_component
= True
449 native_bt
.py3_component_on_del(self
)
450 native_bt
.put(self
._ptr
)
453 class UserSourceComponent(_UserComponent
, _CommonSourceComponentMethods
):
457 class UserFilterComponent(_UserComponent
, _CommonFilterComponentMethods
):
458 def _set_minimum_input_notification_iterator_count(self
, count
):
459 utils
._check
_uint
64(count
)
460 status
= native_bt
.component_filter_set_minimum_input_count(self
._ptr
, count
)
461 self
._handle
_status
(status
, "unexpected error: cannot set filter component object's minimum input notification iterator count")
463 _minimum_input_notification_iterator_count
= property(fset
=_set_minimum_input_notification_iterator_count
)
465 def _set_maximum_input_notification_iterator_count(self
, count
):
466 utils
._check
_uint
64(count
)
467 status
= native_bt
.component_filter_set_maximum_input_count(self
._ptr
, count
)
468 self
._handle
_status
(status
, "unexpected error: cannot set filter component object's maximum input notification iterator count")
470 _maximum_input_notification_iterator_count
= property(fset
=_set_maximum_input_notification_iterator_count
)
473 def _input_notification_iterators(self
):
474 return _ComponentInputNotificationIterators(self
,
475 native_bt
.component_filter_get_input_count
,
476 native_bt
.component_filter_get_input_iterator_private
)
478 def _add_iterator_from_bt(self
, notif_iter_ptr
):
479 notif_iter
= bt2
.notification_iterator
._GenericNotificationIterator
._create
_from
_ptr
(notif_iter_ptr
)
480 self
._add
_notification
_iterator
(notif_iter
)
482 def _add_notification_iterator(self
, notif_iter
):
486 class UserSinkComponent(_UserComponent
, _CommonSinkComponentMethods
):
487 def _set_minimum_input_notification_iterator_count(self
, count
):
488 utils
._check
_uint
64(count
)
489 status
= native_bt
.component_sink_set_minimum_input_count(self
._ptr
, count
)
490 self
._handle
_status
(status
, "unexpected error: cannot set sink component object's minimum input notification iterator count")
492 _minimum_input_notification_iterator_count
= property(fset
=_set_minimum_input_notification_iterator_count
)
494 def _set_maximum_input_notification_iterator_count(self
, count
):
495 utils
._check
_uint
64(count
)
496 status
= native_bt
.component_sink_set_maximum_input_count(self
._ptr
, count
)
497 self
._handle
_status
(status
, "unexpected error: cannot set sink component object's maximum input notification iterator count")
499 _maximum_input_notification_iterator_count
= property(fset
=_set_maximum_input_notification_iterator_count
)
502 def _input_notification_iterators(self
):
503 return _ComponentInputNotificationIterators(self
,
504 native_bt
.component_sink_get_input_count
,
505 native_bt
.component_sink_get_input_iterator_private
)
507 def _add_iterator_from_bt(self
, notif_iter_ptr
):
508 notif_iter
= bt2
.notification_iterator
._GenericNotificationIterator
._create
_from
_ptr
(notif_iter_ptr
)
509 self
._add
_notification
_iterator
(notif_iter
)
511 def _add_notification_iterator(self
, notif_iter
):