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
34 _env_var
= os
.environ
.get('BABELTRACE_PYTHON_BT2_NO_TRACEBACK')
35 _NO_PRINT_TRACEBACK
= _env_var
== '1'
38 # This class wraps a component class pointer. This component class could
39 # have been created by Python code, but since we only have the pointer,
40 # we can only wrap it in a generic way and lose the original Python
42 class _GenericComponentClass(object._Object
):
45 name
= native_bt
.component_class_get_name(self
._ptr
)
46 assert(name
is not None)
50 def description(self
):
51 return native_bt
.component_class_get_description(self
._ptr
)
55 return native_bt
.component_class_get_help(self
._ptr
)
57 def query(self
, obj
, params
=None):
58 return _query(self
._ptr
, obj
, params
)
60 def __eq__(self
, other
):
61 if not isinstance(other
, _GenericComponentClass
):
63 if not issubclass(other
, _UserComponent
):
68 return self
.addr
== other
.addr
71 class _GenericSourceComponentClass(_GenericComponentClass
):
75 class _GenericFilterComponentClass(_GenericComponentClass
):
79 class _GenericSinkComponentClass(_GenericComponentClass
):
83 def _handle_component_status(status
, gen_error_msg
):
84 if status
== native_bt
.COMPONENT_STATUS_END
:
86 elif status
== native_bt
.COMPONENT_STATUS_AGAIN
:
88 elif status
== native_bt
.COMPONENT_STATUS_UNSUPPORTED
:
89 raise bt2
.UnsupportedFeature
90 elif status
== native_bt
.COMPONENT_STATUS_REFUSE_PORT_CONNECTION
:
91 raise bt2
.PortConnectionRefused
92 elif status
== native_bt
.COMPONENT_STATUS_GRAPH_IS_CANCELED
:
93 raise bt2
.GraphCanceled
95 raise bt2
.Error(gen_error_msg
)
98 class _PortIterator(collections
.abc
.Iterator
):
99 def __init__(self
, comp_ports
):
100 self
._comp
_ports
= comp_ports
104 if self
._at
== len(self
._comp
_ports
):
107 comp_ports
= self
._comp
_ports
108 comp_ptr
= comp_ports
._component
._ptr
109 port_ptr
= comp_ports
._get
_port
_at
_index
_fn
(comp_ptr
, self
._at
)
112 if comp_ports
._is
_private
:
113 port_pub_ptr
= native_bt
.port_from_private_port(port_ptr
)
114 name
= native_bt
.port_get_name(port_pub_ptr
)
115 native_bt
.put(port_pub_ptr
)
117 name
= native_bt
.port_get_name(port_ptr
)
119 assert(name
is not None)
120 native_bt
.put(port_ptr
)
125 class _ComponentPorts(collections
.abc
.Mapping
):
126 def __init__(self
, is_private
, component
,
127 get_port_by_name_fn
, get_port_at_index_fn
,
129 self
._is
_private
= is_private
130 self
._component
= component
131 self
._get
_port
_by
_name
_fn
= get_port_by_name_fn
132 self
._get
_port
_at
_index
_fn
= get_port_at_index_fn
133 self
._get
_port
_count
_fn
= get_port_count_fn
135 def __getitem__(self
, key
):
136 utils
._check
_str
(key
)
137 port_ptr
= self
._get
_port
_by
_name
_fn
(self
._component
._ptr
, key
)
143 return bt2
.port
._create
_private
_from
_ptr
(port_ptr
)
145 return bt2
.port
._create
_from
_ptr
(port_ptr
)
149 pub_ptr
= native_bt
.component_from_private_component(self
._component
._ptr
)
150 count
= self
._get
_port
_count
_fn
(pub_ptr
)
151 native_bt
.put(pub_ptr
)
153 count
= self
._get
_port
_count
_fn
(self
._component
._ptr
)
159 return _PortIterator(self
)
162 # This class holds the methods which are common to both generic
163 # component objects and Python user component objects. They use the
164 # internal native _ptr, however it was set, to call native API
169 name
= native_bt
.component_get_name(self
._ptr
)
170 assert(name
is not None)
175 ptr
= native_bt
.component_get_graph(self
._ptr
)
177 return bt2
.Graph
._create
_from
_ptr
(ptr
)
180 def component_class(self
):
181 cc_ptr
= native_bt
.component_get_class(self
._ptr
)
183 return _create_generic_component_class_from_ptr(cc_ptr
)
185 def __eq__(self
, other
):
186 if not hasattr(other
, 'addr'):
189 return self
.addr
== other
.addr
192 class _SourceComponent(_Component
):
196 class _FilterComponent(_Component
):
200 class _SinkComponent(_Component
):
204 # This is analogous to _GenericSourceComponentClass, but for source
206 class _GenericSourceComponent(object._Object
, _SourceComponent
):
208 def output_ports(self
):
209 return _ComponentPorts(False, self
,
210 native_bt
.component_source_get_output_port_by_name
,
211 native_bt
.component_source_get_output_port_by_index
,
212 native_bt
.component_source_get_output_port_count
)
215 # This is analogous to _GenericFilterComponentClass, but for filter
217 class _GenericFilterComponent(object._Object
, _FilterComponent
):
219 def output_ports(self
):
220 return _ComponentPorts(False, self
,
221 native_bt
.component_filter_get_output_port_by_name
,
222 native_bt
.component_filter_get_output_port_by_index
,
223 native_bt
.component_filter_get_output_port_count
)
226 def input_ports(self
):
227 return _ComponentPorts(False, self
,
228 native_bt
.component_filter_get_input_port_by_name
,
229 native_bt
.component_filter_get_input_port_by_index
,
230 native_bt
.component_filter_get_input_port_count
)
233 # This is analogous to _GenericSinkComponentClass, but for sink
235 class _GenericSinkComponent(object._Object
, _SinkComponent
):
237 def input_ports(self
):
238 return _ComponentPorts(False, self
,
239 native_bt
.component_sink_get_input_port_by_name
,
240 native_bt
.component_sink_get_input_port_by_index
,
241 native_bt
.component_sink_get_input_port_count
)
244 _COMP_CLS_TYPE_TO_GENERIC_COMP_PYCLS
= {
245 native_bt
.COMPONENT_CLASS_TYPE_SOURCE
: _GenericSourceComponent
,
246 native_bt
.COMPONENT_CLASS_TYPE_FILTER
: _GenericFilterComponent
,
247 native_bt
.COMPONENT_CLASS_TYPE_SINK
: _GenericSinkComponent
,
251 _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS_PYCLS
= {
252 native_bt
.COMPONENT_CLASS_TYPE_SOURCE
: _GenericSourceComponentClass
,
253 native_bt
.COMPONENT_CLASS_TYPE_FILTER
: _GenericFilterComponentClass
,
254 native_bt
.COMPONENT_CLASS_TYPE_SINK
: _GenericSinkComponentClass
,
258 def _create_generic_component_from_ptr(ptr
):
259 comp_cls_type
= native_bt
.component_get_class_type(ptr
)
260 return _COMP_CLS_TYPE_TO_GENERIC_COMP_PYCLS
[comp_cls_type
]._create
_from
_ptr
(ptr
)
263 def _create_generic_component_class_from_ptr(ptr
):
264 comp_cls_type
= native_bt
.component_class_get_type(ptr
)
265 return _COMP_CLS_TYPE_TO_GENERIC_COMP_CLS_PYCLS
[comp_cls_type
]._create
_from
_ptr
(ptr
)
268 def _trim_docstring(docstring
):
269 lines
= docstring
.expandtabs().splitlines()
272 for line
in lines
[1:]:
273 stripped
= line
.lstrip()
276 indent
= min(indent
, len(line
) - len(stripped
))
278 trimmed
= [lines
[0].strip()]
280 if indent
< sys
.maxsize
:
281 for line
in lines
[1:]:
282 trimmed
.append(line
[indent
:].rstrip())
284 while trimmed
and not trimmed
[-1]:
287 while trimmed
and not trimmed
[0]:
290 return '\n'.join(trimmed
)
293 def _query(comp_cls_ptr
, obj
, params
):
294 utils
._check
_str
(obj
)
297 params_ptr
= native_bt
.value_null
299 params
= bt2
.create_value(params
)
300 params_ptr
= params
._ptr
302 results_ptr
= native_bt
.component_class_query(comp_cls_ptr
, obj
,
305 if results_ptr
is None:
306 raise bt2
.Error('cannot query info with object "{}"'.format(obj
))
308 return bt2
.values
._create
_from
_ptr
(results_ptr
)
311 # Metaclass for component classes defined by Python code.
313 # The Python user can create a standard Python class which inherits one
314 # of the three base classes (_UserSourceComponent, _UserFilterComponent,
315 # or _UserSinkComponent). Those base classes set this class
316 # (_UserComponentType) as their metaclass.
318 # Once the body of a user-defined component class is executed, this
319 # metaclass is used to create and initialize the class. The metaclass
320 # creates a native BT component class of the corresponding type and
321 # associates it with this user-defined class. The metaclass also defines
322 # class methods like the `name` and `description` properties to match
323 # the _GenericComponentClass interface.
325 # The component class name which is used is either:
327 # * The `name` parameter of the class:
329 # class MySink(bt2.SinkComponent, name='my-custom-sink'):
332 # * If the `name` class parameter is not used: the name of the class
333 # itself (`MySink` in the example above).
335 # The component class description which is used is the user-defined
338 # class MySink(bt2.SinkComponent):
339 # 'Description goes here'
342 # A user-defined Python component class can have an __init__() method
343 # which must at least accept the `params` and `name` arguments:
345 # def __init__(self, params, name, something_else):
348 # The user-defined component class can also have a _finalize() method
349 # (do NOT use __del__()) to be notified when the component object is
352 # User-defined source and filter component classes must use the
353 # `notification_iterator_class` class parameter to specify the
354 # notification iterator class to use for this component class:
356 # class MyNotificationIterator(bt2._UserNotificationIterator):
359 # class MySource(bt2._UserSourceComponent,
360 # notification_iterator_class=MyNotificationIterator):
363 # This notification iterator class must inherit
364 # bt2._UserNotificationIterator, and it must define the _get() and
365 # _next() methods. The notification iterator class can also define an
366 # __init__() method: this method has access to the original Python
367 # component object which was used to create it as the `component`
368 # property. The notification iterator class can also define a
369 # _finalize() method (again, do NOT use __del__()): this is called when
370 # the notification iterator is (really) destroyed.
372 # When the user-defined class is destroyed, this metaclass's __del__()
373 # method is called: the native BT component class pointer is put (not
374 # needed anymore, at least not by any Python code since all references
375 # are dropped for __del__() to be called).
376 class _UserComponentType(type):
377 # __new__() is used to catch custom class parameters
378 def __new__(meta_cls
, class_name
, bases
, attrs
, **kwargs
):
379 return super().__new
__(meta_cls
, class_name
, bases
, attrs
)
381 def __init__(cls
, class_name
, bases
, namespace
, **kwargs
):
382 super().__init
__(class_name
, bases
, namespace
)
384 # skip our own bases; they are never directly instantiated by the user
387 '_UserFilterSinkComponent',
388 '_UserSourceComponent',
389 '_UserFilterComponent',
390 '_UserSinkComponent',
393 if class_name
in own_bases
:
396 comp_cls_name
= kwargs
.get('name', class_name
)
397 utils
._check
_str
(comp_cls_name
)
398 comp_cls_descr
= None
401 if hasattr(cls
, '__doc__') and cls
.__doc
__ is not None:
402 utils
._check
_str
(cls
.__doc
__)
403 docstring
= _trim_docstring(cls
.__doc
__)
404 lines
= docstring
.splitlines()
407 comp_cls_descr
= lines
[0]
410 comp_cls_help
= '\n'.join(lines
[2:])
412 iter_cls
= kwargs
.get('notification_iterator_class')
414 if _UserSourceComponent
in bases
:
415 _UserComponentType
._set
_iterator
_class
(cls
, iter_cls
)
416 cc_ptr
= native_bt
.py3_component_class_source_create(cls
,
420 elif _UserFilterComponent
in bases
:
421 _UserComponentType
._set
_iterator
_class
(cls
, iter_cls
)
422 cc_ptr
= native_bt
.py3_component_class_filter_create(cls
,
426 elif _UserSinkComponent
in bases
:
427 if not hasattr(cls
, '_consume'):
428 raise bt2
.IncompleteUserClass("cannot create component class '{}': missing a _consume() method".format(class_name
))
430 cc_ptr
= native_bt
.py3_component_class_sink_create(cls
,
435 raise bt2
.IncompleteUserClass("cannot find a known component class base in the bases of '{}'".format(class_name
))
438 raise bt2
.CreationError("cannot create component class '{}'".format(class_name
))
442 def _init_from_native(cls
, comp_ptr
, params_ptr
):
443 # create instance, not user-initialized yet
444 self
= cls
.__new
__(cls
)
446 # pointer to native private component object (weak/borrowed)
449 # call user's __init__() method
450 if params_ptr
is not None:
451 native_bt
.get(params_ptr
)
452 params
= bt2
.values
._create
_from
_ptr
(params_ptr
)
456 self
.__init
__(params
)
459 def __call__(cls
, *args
, **kwargs
):
460 raise bt2
.Error('cannot directly instantiate a user component from a Python module')
463 def _set_iterator_class(cls
, iter_cls
):
465 raise bt2
.IncompleteUserClass("cannot create component class '{}': missing notification iterator class".format(cls
.__name
__))
467 if not issubclass(iter_cls
, bt2
.notification_iterator
._UserNotificationIterator
):
468 raise bt2
.IncompleteUserClass("cannot create component class '{}': notification iterator class does not inherit bt2._UserNotificationIterator".format(cls
.__name
__))
470 if not hasattr(iter_cls
, '__next__'):
471 raise bt2
.IncompleteUserClass("cannot create component class '{}': notification iterator class is missing a __next__() method".format(cls
.__name
__))
473 cls
._iter
_cls
= iter_cls
477 return native_bt
.component_class_get_name(cls
._cc
_ptr
)
480 def description(cls
):
481 return native_bt
.component_class_get_description(cls
._cc
_ptr
)
485 return native_bt
.component_class_get_help(cls
._cc
_ptr
)
489 return int(cls
._cc
_ptr
)
491 def query(cls
, obj
, params
=None):
492 return _query(cls
._cc
_ptr
, obj
, params
)
494 def _query_from_native(cls
, obj
, params_ptr
):
495 # this can raise, in which case the native call to
496 # bt_component_class_query() returns NULL
497 if params_ptr
is not None:
498 native_bt
.get(params_ptr
)
499 params
= bt2
.values
._create
_from
_ptr
(params_ptr
)
504 results
= cls
._query
(obj
, params
)
506 if not _NO_PRINT_TRACEBACK
:
507 traceback
.print_exc()
511 if results
is NotImplemented:
515 results
= bt2
.create_value(results
)
517 if not _NO_PRINT_TRACEBACK
:
518 traceback
.print_exc()
523 results_addr
= int(native_bt
.value_null
)
525 # return new reference
527 results_addr
= int(results
._ptr
)
532 def _query(cls
, obj
, params
):
533 # BT catches this and returns NULL to the user
534 return NotImplemented
536 def __eq__(self
, other
):
537 if not hasattr(other
, 'addr'):
540 return self
.addr
== other
.addr
543 if hasattr(cls
, '_cc_ptr'):
544 native_bt
.put(cls
._cc
_ptr
)
547 class _UserComponent(metaclass
=_UserComponentType
):
550 pub_ptr
= native_bt
.component_from_private_component(self
._ptr
)
551 name
= native_bt
.component_get_name(pub_ptr
)
552 native_bt
.put(pub_ptr
)
553 assert(name
is not None)
558 pub_ptr
= native_bt
.component_from_private_component(self
._ptr
)
559 ptr
= native_bt
.component_get_graph(pub_ptr
)
560 native_bt
.put(pub_ptr
)
562 return bt2
.Graph
._create
_from
_ptr
(ptr
)
565 def component_class(self
):
566 pub_ptr
= native_bt
.component_from_private_component(self
._ptr
)
567 cc_ptr
= native_bt
.component_get_class(pub_ptr
)
568 native_bt
.put(pub_ptr
)
570 return _create_generic_component_class_from_ptr(cc_ptr
)
574 return int(self
._ptr
)
576 def __init__(self
, params
=None):
582 def _accept_port_connection(self
, port
, other_port
):
585 def _accept_port_connection_from_native(self
, port_ptr
, other_port_ptr
):
586 native_bt
.get(port_ptr
)
587 native_bt
.get(other_port_ptr
)
588 port
= bt2
.port
._create
_private
_from
_ptr
(port_ptr
)
589 other_port
= bt2
.port
._create
_from
_ptr
(other_port_ptr
)
590 res
= self
._accept
_port
_connection
(port
, other_port_ptr
)
592 if type(res
) is not bool:
593 raise TypeError("'{}' is not a 'bool' object")
597 def _port_connected(self
, port
, other_port
):
600 def _port_connected_from_native(self
, port_ptr
, other_port_ptr
):
601 native_bt
.get(port_ptr
)
602 native_bt
.get(other_port_ptr
)
603 port
= bt2
.port
._create
_private
_from
_ptr
(port_ptr
)
604 other_port
= bt2
.port
._create
_from
_ptr
(other_port_ptr
)
607 self
._port
_connected
(port
, other_port_ptr
)
609 if not _NO_PRINT_TRACEBACK
:
610 traceback
.print_exc()
612 def _port_disconnected(self
, port
):
615 def _port_disconnected_from_native(self
, port_ptr
):
616 native_bt
.get(port_ptr
)
617 port
= bt2
.port
._create
_private
_from
_ptr
(port_ptr
)
620 self
._port
_disconnected
(port
)
622 if not _NO_PRINT_TRACEBACK
:
623 traceback
.print_exc()
626 class _UserSourceComponent(_UserComponent
, _SourceComponent
):
628 def _output_ports(self
):
629 return _ComponentPorts(True, self
,
630 native_bt
.private_component_source_get_output_private_port_by_name
,
631 native_bt
.private_component_source_get_output_private_port_by_index
,
632 native_bt
.component_source_get_output_port_count
)
634 def _add_output_port(self
, name
):
635 utils
._check
_str
(name
)
636 fn
= native_bt
.private_component_source_add_output_private_port
637 comp_status
, priv_port_ptr
= fn(self
._ptr
, name
, None)
638 _handle_component_status(comp_status
,
639 'cannot add output port to source component object')
640 assert(priv_port_ptr
)
641 return bt2
.port
._create
_private
_from
_ptr
(priv_port_ptr
)
644 class _UserFilterComponent(_UserComponent
, _FilterComponent
):
646 def _output_ports(self
):
647 return _ComponentPorts(True, self
,
648 native_bt
.private_component_filter_get_output_private_port_by_name
,
649 native_bt
.private_component_filter_get_output_private_port_by_index
,
650 native_bt
.component_filter_get_output_port_count
)
653 def _input_ports(self
):
654 return _ComponentPorts(True, self
,
655 native_bt
.private_component_filter_get_input_private_port_by_name
,
656 native_bt
.private_component_filter_get_input_private_port_by_index
,
657 native_bt
.component_filter_get_input_port_count
)
659 def _add_output_port(self
, name
):
660 utils
._check
_str
(name
)
661 fn
= native_bt
.private_component_filter_add_output_private_port
662 comp_status
, priv_port_ptr
= fn(self
._ptr
, name
, None)
663 _handle_component_status(comp_status
,
664 'cannot add output port to filter component object')
665 assert(priv_port_ptr
)
666 return bt2
.port
._create
_private
_from
_ptr
(priv_port_ptr
)
668 def _add_input_port(self
, name
):
669 utils
._check
_str
(name
)
670 fn
= native_bt
.private_component_filter_add_input_private_port
671 comp_status
, priv_port_ptr
= fn(self
._ptr
, name
, None)
672 _handle_component_status(comp_status
,
673 'cannot add input port to filter component object')
674 assert(priv_port_ptr
)
675 return bt2
.port
._create
_private
_from
_ptr
(priv_port_ptr
)
678 class _UserSinkComponent(_UserComponent
, _SinkComponent
):
680 def _input_ports(self
):
681 return _ComponentPorts(True, self
,
682 native_bt
.private_component_sink_get_input_private_port_by_name
,
683 native_bt
.private_component_sink_get_input_private_port_by_index
,
684 native_bt
.component_sink_get_input_port_count
)
686 def _add_input_port(self
, name
):
687 utils
._check
_str
(name
)
688 fn
= native_bt
.private_component_sink_add_input_private_port
689 comp_status
, priv_port_ptr
= fn(self
._ptr
, name
, None)
690 _handle_component_status(comp_status
,
691 'cannot add input port to sink component object')
692 assert(priv_port_ptr
)
693 return bt2
.port
._create
_private
_from
_ptr
(priv_port_ptr
)