2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
8 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
17 #include <babeltrace2/logging.h>
24 @defgroup api-comp-cls-dev Component class development
28 Component class development (creation).
30 A <strong><em>component class</em></strong> is the class of a \bt_comp:
32 @image html component.png
35 This module (component class development API) offers functions to
36 programatically create component classes. To get the properties of
37 an existing component class, see \ref api-comp-cls.
39 A component class has <em>methods</em>. This module essentially
42 - Component class method type definitions.
44 - Component class creation functions, to which you pass a mandatory
45 \bt_msg_iter_cls or method.
47 - Functions to set optional component class methods.
49 - Functions to set optional component class properties.
51 A component class method is a user function. There are two types of
55 <dt>\anchor api-comp-cls-dev-instance-meth Instance method</dt>
57 Operates on an instance (a \bt_comp).
59 The type of the method's first parameter is
60 #bt_self_component_source, #bt_self_component_filter, or
61 bt_self_component_sink, depending on the component class's type.
63 This is similar to an instance method in Python (where the instance
64 object name is generally <code>self</code>) or a member function
65 in C++ (where the instance pointer is named <code>this</code>),
69 <dt>\anchor api-comp-cls-dev-class-meth Class method</dt>
71 Operates on a component class.
73 The type of the method's first parameter is
74 #bt_self_component_class_source, #bt_self_component_class_filter, or
75 bt_self_component_class_sink, depending on the component class's
78 This is similar to a class method in Python or a static member
79 function in C++, for example.
83 See \ref api-comp-cls-dev-methods "Methods" to learn more about the
84 different types of component class methods.
86 A component class is a \ref api-fund-shared-object "shared object": see
87 the \ref api-comp-cls module for the reference count functions.
89 Some library functions \ref api-fund-freezing "freeze" component classes
90 on success. The documentation of those functions indicate this
93 Create a component class with bt_component_class_source_create(),
94 bt_component_class_filter_create(), and
95 bt_component_class_sink_create(). You must give the component class a
96 name (not unique in any way) at creation time.
98 When you create a \bt_src_comp_cls or a \bt_flt_comp_cls, you must pass
99 a \bt_msg_iter_cls. This is the class of any \bt_msg_iter created for
100 one of the component class's instance's \bt_oport.
102 When you create a \bt_sink_comp_cls, you must pass a
103 \ref api-comp-cls-dev-meth-consume "consuming method".
105 \ref api-fund-c-typing "Upcast" the #bt_component_class_source,
106 #bt_component_class_filter, and bt_component_class_sink types returned
107 by the creation functions to the #bt_component_class type with
108 bt_component_class_source_as_component_class(),
109 bt_component_class_filter_as_component_class(), and
110 bt_component_class_sink_as_component_class().
112 Set the \ref api-comp-cls-prop-descr "description" and the
113 \ref api-comp-cls-prop-help "help text" of a component class with
114 bt_component_class_set_description() and
115 bt_component_class_set_help().
117 <h1>\anchor api-comp-cls-dev-methods Methods</h1>
119 To learn when exactly the methods below are called, see
120 \ref api-graph-lc "Trace processing graph life cycle".
122 The available component class methods to implement are:
128 <th>Component class types
130 <th>Graph is \ref api-graph-lc "configured"?
134 <td>\ref api-comp-cls-dev-instance-meth "Instance"
138 <td>#bt_component_class_sink_consume_method
146 #bt_component_class_source_finalize_method<br>
147 #bt_component_class_filter_finalize_method<br>
148 #bt_component_class_sink_finalize_method
150 <td>Get supported \bt_mip (MIP) versions
151 <td>\ref api-comp-cls-dev-class-meth "Class"
156 #bt_component_class_source_get_supported_mip_versions_method<br>
157 #bt_component_class_filter_get_supported_mip_versions_method<br>
158 #bt_component_class_sink_get_supported_mip_versions_method
160 <td>Graph is \ref api-graph-lc "configured"
165 <td>#bt_component_class_sink_graph_is_configured_method
173 #bt_component_class_source_initialize_method<br>
174 #bt_component_class_filter_initialize_method<br>
175 #bt_component_class_sink_initialize_method
177 <td>\bt_c_iport connected
183 #bt_component_class_filter_input_port_connected_method<br>
184 #bt_component_class_sink_input_port_connected_method
186 <td>\bt_c_oport connected
188 <td>Source and filter
192 #bt_component_class_source_output_port_connected_method<br>
193 #bt_component_class_filter_output_port_connected_method
201 #bt_component_class_source_query_method<br>
202 #bt_component_class_filter_query_method<br>
203 #bt_component_class_sink_query_method
208 \anchor api-comp-cls-dev-meth-consume
212 Called within bt_graph_run() or bt_graph_run_once() to make your
213 \bt_sink_comp consume and process \bt_p_msg.
215 This method typically gets \em one message batch from one (or more)
216 upstream \bt_msg_iter. You are free to get more than one batch of
217 messages if needed; however, keep in mind that the \bt_name project
218 recommends that this method executes fast enough so as not to block
219 an interactive application running on the same thread.
221 During what you consider to be a long, blocking operation, the
222 project recommends that you periodically check whether or not you
223 are interrupted with bt_self_component_sink_is_interrupted(). When
224 you are, you can return either
225 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN or
226 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR, depending on
227 your capability to continue the current operation later.
229 If you need to block the thread, you can instead report to
230 try again later to the bt_graph_run() or bt_graph_run_once() caller
231 by returning #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN.
233 If your sink component is done consuming and processing, return
234 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END from this method.
235 The trace processing \bt_graph can continue to run afterwards if
236 other sink components are still consuming.
238 Within this method, you \em cannot add an \bt_iport with
239 bt_self_component_sink_add_input_port().
241 Set this mandatory method at sink component class creation time with
242 bt_component_class_sink_create().
246 \anchor api-comp-cls-dev-meth-fini
250 Called to finalize your \bt_comp, that is, to let you
251 destroy/free/finalize any user data you have (retrieved with
252 bt_self_component_get_data()).
254 The \bt_name library does not specify exactly when this method is
255 called, but guarantees that it's called before the component is
258 For \bt_p_src_comp and \bt_p_flt_comp, the library guarantees that
259 this method is called \em after all the component's \bt_p_msg_iter
262 This method is \em not called if the component's
263 \ref api-comp-cls-dev-meth-init "initialization method"
264 previously returned an error status code.
266 Within this method, you cannot:
269 - Use any \bt_msg_iter.
271 Set this optional method with
272 bt_component_class_source_set_finalize_method(),
273 bt_component_class_filter_set_finalize_method(), and
274 bt_component_class_sink_set_finalize_method().
278 \anchor api-comp-cls-dev-meth-mip
279 Get supported \bt_mip (MIP) versions
282 Called within bt_get_greatest_operative_mip_version() to get the
283 set of MIP versions that an eventual \bt_comp supports.
285 This is a \ref api-comp-cls-dev-class-meth "class method" because
286 you can call bt_get_greatest_operative_mip_version() before you even
287 create a trace processing \bt_graph.
289 In this method, you receive initialization parameters as the
290 \bt_p{params} parameter and initialization method data as the
291 \bt_p{initialize_method_data}. Those parameters are set
292 when bt_component_descriptor_set_add_descriptor() is called, before
293 bt_get_greatest_operative_mip_version() is called.
295 Considering those initialization parameters, you need to fill the
296 received \bt_uint_rs \bt_p{supported_versions} with the rangs of
297 MIP versions you support.
299 As of \bt_name_version_min_maj, you can only support MIP version 0.
301 Not having this method is equivalent to having one which adds the
302 [0, 0] range to the \bt_p{supported_versions} set.
304 Set this optional method with
305 bt_component_class_source_set_get_supported_mip_versions_method(),
306 bt_component_class_filter_set_get_supported_mip_versions_method(),
307 and bt_component_class_sink_set_get_supported_mip_versions_method().
311 \anchor api-comp-cls-dev-meth-graph-configured
312 Graph is \ref api-graph-lc "configured"
315 For a given trace processing \bt_graph, called the first time
316 bt_graph_run() or bt_graph_run_once() is called to notify your
317 \bt_sink_comp that the graph is now configured.
319 Within this method, you can create \bt_p_msg_iter on your sink
320 component's \bt_p_iport. You can also manipulate those message
321 iterators, for example get and process initial messages or make
324 This method is called \em after the component's
325 \ref api-comp-cls-dev-meth-init "initialization method"
326 is called. You cannot create a message iterator in the
327 initialization method.
329 Within this method, you \em cannot add an \bt_iport with
330 bt_self_component_sink_add_input_port().
332 Set this optional method with
333 bt_component_class_sink_set_graph_is_configured_method().
337 \anchor api-comp-cls-dev-meth-init
341 Called within a <code>bt_graph_add_*_component*()</code> function
342 (see \ref api-graph) to initialize your \bt_comp.
344 Within this method, you receive the initialization parameters and
345 initialization method data passed to the
346 <code>bt_graph_add_*_component*()</code> function.
348 This method is where you can add initial \bt_p_port to your
349 component with bt_self_component_source_add_output_port(),
350 bt_self_component_filter_add_input_port(),
351 bt_self_component_filter_add_output_port(), or
352 bt_self_component_sink_add_input_port().
353 You can also add ports in the
354 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
356 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
359 You can create user data and set it as the \bt_self_comp's user data
360 with bt_self_component_set_data().
362 If you return #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK from
363 this method, then your component's
364 \ref api-comp-cls-dev-meth-fini "finalization method" will be
365 called, if it exists, when your component is finalized.
367 Set this optional method with
368 bt_component_class_source_set_initialize_method(),
369 bt_component_class_filter_set_initialize_method(),
370 and bt_component_class_sink_set_initialize_method().
374 \anchor api-comp-cls-dev-meth-iport-connected
375 \bt_c_iport connected
378 Called within bt_graph_connect_ports() to notify your \bt_comp that
379 one of its input ports has been connected.
381 Within this method, you can add more \bt_p_port to your
382 component with bt_self_component_source_add_output_port(),
383 bt_self_component_filter_add_input_port(),
384 bt_self_component_filter_add_output_port(), or
385 bt_self_component_sink_add_input_port().
387 Set this optional method with
388 bt_component_class_filter_set_input_port_connected_method() and
389 bt_component_class_sink_set_input_port_connected_method().
393 \anchor api-comp-cls-dev-meth-oport-connected
394 \bt_c_oport connected
397 Called within bt_graph_connect_ports() to notify your \bt_comp that
398 one of its output ports has been connected.
400 Within this method, you can add more \bt_p_port to your
401 component with bt_self_component_source_add_output_port(),
402 bt_self_component_filter_add_input_port(),
403 bt_self_component_filter_add_output_port(), or
404 bt_self_component_sink_add_input_port().
406 Set this optional method with
407 bt_component_class_source_set_output_port_connected_method() and
408 bt_component_class_filter_set_output_port_connected_method().
412 \anchor api-comp-cls-dev-meth-query
416 Called within bt_query_executor_query() to make your \bt_comp_cls
417 perform a query operation.
419 Within this method, you receive the query object name, the
420 query parameters, and the method data passed when the
421 \bt_qexec was created with bt_query_executor_create() or
422 bt_query_executor_create_with_method_data().
424 You also receive a private view of the query executor which you can
425 cast to a \c const query executor with
426 bt_private_query_executor_as_query_executor_const() to access the
427 executor's logging level with bt_query_executor_get_logging_level().
429 On success, set \bt_p{*result} to the query operation's result: a
430 \em new \bt_val reference.
432 If the queried object's name (\bt_p{object_name} parameter) is
434 #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT.
436 If you need to block the thread, you can instead report to
437 try again later to the bt_query_executor_query() caller
438 by returning #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN.
440 Set this optional method with
441 bt_component_class_source_set_query_method(),
442 bt_component_class_filter_set_query_method(), and
443 bt_component_class_sink_set_query_method().
449 In any of the methods above:
451 - \em Never call bt_component_get_ref(),
452 bt_component_source_get_ref(), bt_component_filter_get_ref(), or
453 bt_component_sink_get_ref() on your own (upcasted) \bt_self_comp
454 to avoid reference cycles.
456 You can keep a borrowed (weak) \bt_self_comp reference in your
457 component's user data (see bt_self_component_set_data()).
459 - \em Never call bt_port_get_ref(), bt_port_input_get_ref(), or
460 bt_port_output_get_ref() on one of your own (upcasted)
461 \bt_p_self_comp_port to avoid reference cycles.
463 - \em Never call bt_component_class_get_ref(),
464 bt_component_class_source_get_ref(),
465 bt_component_class_filter_get_ref(), or
466 bt_component_class_sink_get_ref() on your own (upcasted)
467 \bt_comp_cls to avoid reference cycles.
470 Within any \ref api-comp-cls-dev-instance-meth "instance method", you
471 can access the \bt_comp's configured
472 \ref #bt_logging_level "logging level" by first upcasting the
473 \bt_self_comp to the #bt_component type with
474 bt_self_component_as_component(), and then with
475 bt_component_get_logging_level().
487 Status codes for #bt_component_class_sink_consume_method.
489 typedef enum bt_component_class_sink_consume_method_status
{
494 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
498 Sink component is finished processing.
500 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END
= __BT_FUNC_STATUS_END
,
506 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
512 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
518 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
519 } bt_component_class_sink_consume_method_status
;
523 \bt_c_sink_comp consuming method.
525 See the \ref api-comp-cls-dev-meth-consume "consume" method.
527 @param[in] self_component
528 \bt_c_sink_comp instance.
530 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK
532 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END
534 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN
536 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR
538 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR
541 @bt_pre_not_null{self_component}
543 @sa bt_component_class_sink_create() —
544 Creates a \bt_sink_comp.
546 typedef bt_component_class_sink_consume_method_status
547 (*bt_component_class_sink_consume_method
)(
548 bt_self_component_sink
*self_component
);
552 \bt_c_src_comp finalization method.
554 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
556 @param[in] self_component
557 Source component instance.
559 @bt_pre_not_null{self_component}
563 @sa bt_component_class_source_set_finalize_method() —
564 Sets the finalization method of a source component class.
566 typedef void (*bt_component_class_source_finalize_method
)(
567 bt_self_component_source
*self_component
);
571 \bt_c_flt_comp finalization method.
573 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
575 @param[in] self_component
576 Filter component instance.
578 @bt_pre_not_null{self_component}
582 @sa bt_component_class_filter_set_finalize_method() —
583 Sets the finalization method of a filter component class.
585 typedef void (*bt_component_class_filter_finalize_method
)(
586 bt_self_component_filter
*self_component
);
590 \bt_c_sink_comp finalization method.
592 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
594 @param[in] self_component
595 Sink component instance.
597 @bt_pre_not_null{self_component}
601 @sa bt_component_class_sink_set_finalize_method() —
602 Sets the finalization method of a sink component class.
604 typedef void (*bt_component_class_sink_finalize_method
)(
605 bt_self_component_sink
*self_component
);
610 #bt_component_class_source_get_supported_mip_versions_method,
611 #bt_component_class_filter_get_supported_mip_versions_method, and
612 #bt_component_class_sink_get_supported_mip_versions_method.
614 typedef enum bt_component_class_get_supported_mip_versions_method_status
{
619 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
625 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
631 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
632 } bt_component_class_get_supported_mip_versions_method_status
;
636 \bt_c_src_comp_cls \"get supported \bt_mip versions\" method.
638 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
641 As of \bt_name_version_min_maj, you can only add the range [0, 0]
642 to \bt_p{supported_versions}.
644 @param[in] self_component_class
645 Source component class.
648 Initialization parameters, as passed as the \bt_p{params} parameter
649 of bt_component_descriptor_set_add_descriptor() or
650 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
652 \bt_p{params} is frozen.
654 @param[in] initialize_method_data
655 User data for this method, as passed as the
656 \bt_p{init_method_data} parameter of
657 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
658 @param[in] logging_level
659 Logging level to use during this method's execution, as passed
660 as the \bt_p{logging_level} parameter of
661 bt_get_greatest_operative_mip_version().
662 @param[in] supported_versions
663 \bt_c_uint_rs to which to add the ranges of supported MIP versions
664 of an eventual instance of \bt_p{self_component_class} considering
665 \bt_p{params} and \bt_p{initialize_method_data}.
667 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
669 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
671 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
674 @bt_pre_not_null{self_component_class}
675 @bt_pre_not_null{params}
676 @bt_pre_is_map_val{params}
677 @bt_pre_not_null{supported_versions}
679 \bt_p{supported_versions} is empty.
681 @sa bt_component_class_source_set_get_supported_mip_versions_method() —
682 Sets the "get supported MIP versions" method of a source
685 typedef bt_component_class_get_supported_mip_versions_method_status
686 (*bt_component_class_source_get_supported_mip_versions_method
)(
687 bt_self_component_class_source
*self_component_class
,
688 const bt_value
*params
, void *initialize_method_data
,
689 bt_logging_level logging_level
,
690 bt_integer_range_set_unsigned
*supported_versions
);
694 \bt_c_flt_comp_cls \"get supported \bt_mip versions\" method.
696 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
699 As of \bt_name_version_min_maj, you can only add the range [0, 0]
700 to \bt_p{supported_versions}.
702 @param[in] self_component_class
703 Filter component class.
706 Initialization parameters, as passed as the \bt_p{params} parameter
707 of bt_component_descriptor_set_add_descriptor() or
708 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
710 \bt_p{params} is frozen.
712 @param[in] initialize_method_data
713 User data for this method, as passed as the
714 \bt_p{init_method_data} parameter of
715 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
716 @param[in] logging_level
717 Logging level to use during this method's execution, as passed
718 as the \bt_p{logging_level} parameter of
719 bt_get_greatest_operative_mip_version().
720 @param[in] supported_versions
721 \bt_c_uint_rs to which to add the ranges of supported MIP versions
722 of an eventual instance of \bt_p{self_component_class} considering
723 \bt_p{params} and \bt_p{initialize_method_data}.
725 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
727 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
729 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
732 @bt_pre_not_null{self_component_class}
733 @bt_pre_not_null{params}
734 @bt_pre_is_map_val{params}
735 @bt_pre_not_null{supported_versions}
737 \bt_p{supported_versions} is empty.
739 @sa bt_component_class_filter_set_get_supported_mip_versions_method() —
740 Sets the "get supported MIP versions" method of a filter
743 typedef bt_component_class_get_supported_mip_versions_method_status
744 (*bt_component_class_filter_get_supported_mip_versions_method
)(
745 bt_self_component_class_filter
*source_component_class
,
746 const bt_value
*params
, void *initialize_method_data
,
747 bt_logging_level logging_level
,
748 bt_integer_range_set_unsigned
*supported_versions
);
752 \bt_c_sink_comp_cls \"get supported \bt_mip versions\" method.
754 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
757 As of \bt_name_version_min_maj, you can only add the range [0, 0]
758 to \bt_p{supported_versions}.
760 @param[in] self_component_class
761 Sink component class.
764 Initialization parameters, as passed as the \bt_p{params} parameter
765 of bt_component_descriptor_set_add_descriptor() or
766 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
768 \bt_p{params} is frozen.
770 @param[in] initialize_method_data
771 User data for this method, as passed as the
772 \bt_p{init_method_data} parameter of
773 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
774 @param[in] logging_level
775 Logging level to use during this method's execution, as passed
776 as the \bt_p{logging_level} parameter of
777 bt_get_greatest_operative_mip_version().
778 @param[in] supported_versions
779 \bt_c_uint_rs to which to add the ranges of supported MIP versions
780 of an eventual instance of \bt_p{self_component_class} considering
781 \bt_p{params} and \bt_p{initialize_method_data}.
783 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
785 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
787 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
790 @bt_pre_not_null{self_component_class}
791 @bt_pre_not_null{params}
792 @bt_pre_is_map_val{params}
793 @bt_pre_not_null{supported_versions}
795 \bt_p{supported_versions} is empty.
797 @sa bt_component_class_sink_set_get_supported_mip_versions_method() —
798 Sets the "get supported MIP versions" method of a sink
801 typedef bt_component_class_get_supported_mip_versions_method_status
802 (*bt_component_class_sink_get_supported_mip_versions_method
)(
803 bt_self_component_class_sink
*source_component_class
,
804 const bt_value
*params
, void *initialize_method_data
,
805 bt_logging_level logging_level
,
806 bt_integer_range_set_unsigned
*supported_versions
);
811 #bt_component_class_sink_graph_is_configured_method.
813 typedef enum bt_component_class_sink_graph_is_configured_method_status
{
818 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
824 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
830 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
831 } bt_component_class_sink_graph_is_configured_method_status
;
835 \bt_c_sink_comp "graph is configured" method.
837 See the \ref api-comp-cls-dev-meth-graph-configured
838 "graph is configured" method.
840 @param[in] self_component
841 Sink component instance.
843 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK
845 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR
847 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR
850 @bt_pre_not_null{self_component}
852 @sa bt_component_class_sink_set_graph_is_configured_method() —
853 Sets the "graph is configured" method of a sink component class.
855 typedef bt_component_class_sink_graph_is_configured_method_status
856 (*bt_component_class_sink_graph_is_configured_method
)(
857 bt_self_component_sink
*self_component
);
862 #bt_component_class_source_initialize_method,
863 #bt_component_class_filter_initialize_method, and
864 #bt_component_class_sink_initialize_method.
866 typedef enum bt_component_class_initialize_method_status
{
871 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
877 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
883 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
884 } bt_component_class_initialize_method_status
;
888 \bt_c_src_comp initialization method.
890 See the \ref api-comp-cls-dev-meth-init "initialize" method.
892 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
895 @param[in] self_component
896 Source component instance.
897 @param[in] configuration
898 Initial component configuration (unused).
901 Initialization parameters, as passed as the \bt_p{params} parameter
902 of bt_graph_add_source_component() or
903 bt_graph_add_source_component_with_initialize_method_data().
905 \bt_p{params} is frozen.
907 @param[in] initialize_method_data
908 User data for this method, as passed as the
909 \bt_p{initialize_method_data} parameter of
910 bt_graph_add_source_component_with_initialize_method_data().
912 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
914 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
916 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
919 @bt_pre_not_null{self_component}
920 @bt_pre_not_null{configuration}
921 @bt_pre_not_null{params}
922 @bt_pre_is_map_val{params}
924 @sa bt_component_class_source_set_initialize_method() —
925 Sets the initialization method of a source component class.
927 typedef bt_component_class_initialize_method_status
928 (*bt_component_class_source_initialize_method
)(
929 bt_self_component_source
*self_component
,
930 bt_self_component_source_configuration
*configuration
,
931 const bt_value
*params
, void *initialize_method_data
);
935 \bt_c_flt_comp initialization method.
937 See the \ref api-comp-cls-dev-meth-init "initialize" method.
939 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
942 @param[in] self_component
943 Filter component instance.
944 @param[in] configuration
945 Initial component configuration (unused).
948 Initialization parameters, as passed as the \bt_p{params} parameter
949 of bt_graph_add_filter_component() or
950 bt_graph_add_filter_component_with_initialize_method_data().
952 \bt_p{params} is frozen.
954 @param[in] initialize_method_data
955 User data for this method, as passed as the
956 \bt_p{initialize_method_data} parameter of
957 bt_graph_add_filter_component_with_initialize_method_data().
959 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
961 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
963 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
966 @bt_pre_not_null{self_component}
967 @bt_pre_not_null{configuration}
968 @bt_pre_not_null{params}
969 @bt_pre_is_map_val{params}
971 @sa bt_component_class_filter_set_initialize_method() —
972 Sets the initialization method of a filter component class.
974 typedef bt_component_class_initialize_method_status
975 (*bt_component_class_filter_initialize_method
)(
976 bt_self_component_filter
*self_component
,
977 bt_self_component_filter_configuration
*configuration
,
978 const bt_value
*params
, void *initialize_method_data
);
982 \bt_c_sink_comp initialization method.
984 See the \ref api-comp-cls-dev-meth-init "initialize" method.
986 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
989 @param[in] self_component
990 Sink component instance.
991 @param[in] configuration
992 Initial component configuration (unused).
995 Initialization parameters, as passed as the \bt_p{params} parameter
996 of bt_graph_add_sink_component(),
997 bt_graph_add_sink_component_with_initialize_method_data(), or
998 bt_graph_add_simple_sink_component().
1000 \bt_p{params} is frozen.
1002 @param[in] initialize_method_data
1003 User data for this method, as passed as the
1004 \bt_p{initialize_method_data} parameter of
1005 bt_graph_add_sink_component_with_initialize_method_data().
1007 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
1009 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
1011 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
1014 @bt_pre_not_null{self_component}
1015 @bt_pre_not_null{configuration}
1016 @bt_pre_not_null{params}
1017 @bt_pre_is_map_val{params}
1019 @sa bt_component_class_sink_set_initialize_method() —
1020 Sets the initialization method of a sink component class.
1022 typedef bt_component_class_initialize_method_status
1023 (*bt_component_class_sink_initialize_method
)(
1024 bt_self_component_sink
*self_component
,
1025 bt_self_component_sink_configuration
*configuration
,
1026 const bt_value
*params
, void *initialize_method_data
);
1031 #bt_component_class_source_output_port_connected_method,
1032 #bt_component_class_filter_input_port_connected_method,
1033 #bt_component_class_filter_output_port_connected_method, and
1034 #bt_component_class_sink_input_port_connected_method.
1036 typedef enum bt_component_class_port_connected_method_status
{
1041 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1047 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1053 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1054 } bt_component_class_port_connected_method_status
;
1058 \bt_c_src_comp "output port connected" method.
1061 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1064 @param[in] self_component
1065 Source component instance.
1066 @param[in] self_port
1067 Connected \bt_oport of \bt_p{self_component}.
1068 @param[in] other_port
1069 \bt_c_conn's other (input) port.
1071 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1073 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1075 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1078 @bt_pre_not_null{self_component}
1079 @bt_pre_not_null{self_port}
1080 @bt_pre_not_null{other_port}
1082 @sa bt_component_class_source_set_output_port_connected_method() —
1083 Sets the "output port connected" method of a source component class.
1085 typedef bt_component_class_port_connected_method_status
1086 (*bt_component_class_source_output_port_connected_method
)(
1087 bt_self_component_source
*self_component
,
1088 bt_self_component_port_output
*self_port
,
1089 const bt_port_input
*other_port
);
1093 \bt_c_flt_comp "input port connected" method.
1096 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1099 @param[in] self_component
1100 Filter component instance.
1101 @param[in] self_port
1102 Connected \bt_iport of \bt_p{self_component}.
1103 @param[in] other_port
1104 \bt_c_conn's other (output) port.
1106 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1108 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1110 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1113 @bt_pre_not_null{self_component}
1114 @bt_pre_not_null{self_port}
1115 @bt_pre_not_null{other_port}
1117 @sa bt_component_class_filter_set_input_port_connected_method() —
1118 Sets the "input port connected" method of a filter component class.
1120 typedef bt_component_class_port_connected_method_status
1121 (*bt_component_class_filter_input_port_connected_method
)(
1122 bt_self_component_filter
*self_component
,
1123 bt_self_component_port_input
*self_port
,
1124 const bt_port_output
*other_port
);
1128 \bt_c_flt_comp "output port connected" method.
1131 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1134 @param[in] self_component
1135 Filter component instance.
1136 @param[in] self_port
1137 Connected \bt_oport of \bt_p{self_component}.
1138 @param[in] other_port
1139 \bt_c_conn's other (input) port.
1141 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1143 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1145 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1148 @bt_pre_not_null{self_component}
1149 @bt_pre_not_null{self_port}
1150 @bt_pre_not_null{other_port}
1152 @sa bt_component_class_filter_set_output_port_connected_method() —
1153 Sets the "output port connected" method of a filter component class.
1155 typedef bt_component_class_port_connected_method_status
1156 (*bt_component_class_filter_output_port_connected_method
)(
1157 bt_self_component_filter
*self_component
,
1158 bt_self_component_port_output
*self_port
,
1159 const bt_port_input
*other_port
);
1163 \bt_c_sink_comp "input port connected" method.
1166 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1169 @param[in] self_component
1170 Sink component instance.
1171 @param[in] self_port
1172 Connected \bt_iport of \bt_p{self_component}.
1173 @param[in] other_port
1174 \bt_c_conn's other (output) port.
1176 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1178 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1180 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1183 @bt_pre_not_null{self_component}
1184 @bt_pre_not_null{self_port}
1185 @bt_pre_not_null{other_port}
1187 @sa bt_component_class_sink_set_input_port_connected_method() —
1188 Sets the "input port connected" method of a sink component class.
1190 typedef bt_component_class_port_connected_method_status
1191 (*bt_component_class_sink_input_port_connected_method
)(
1192 bt_self_component_sink
*self_component
,
1193 bt_self_component_port_input
*self_port
,
1194 const bt_port_output
*other_port
);
1199 #bt_component_class_source_query_method,
1200 #bt_component_class_filter_query_method, and
1201 #bt_component_class_sink_query_method.
1203 typedef enum bt_component_class_query_method_status
{
1208 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1212 Unknown object to query.
1214 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
1220 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1226 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1232 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1233 } bt_component_class_query_method_status
;
1237 \bt_c_src_comp_cls query method.
1239 See the \ref api-comp-cls-dev-meth-query "query" method.
1241 @param[in] self_component_class
1242 Source component class, as passed as the \bt_p{component_class}
1243 parameter of bt_query_executor_create() or
1244 bt_query_executor_create_with_method_data() when creating this query
1245 operation's \ref api-qexec "executor".
1246 @param[in] query_executor
1247 Private view of this query operation's executor.
1248 @param[in] object_name
1249 Name of the object to query, as passed as the \bt_p{object_name}
1250 parameter of bt_query_executor_create() or
1251 bt_query_executor_create_with_method_data() when creating this query
1252 operation's executor.
1255 Query parameters, as passed as the \bt_p{params}
1256 parameter of bt_query_executor_create() or
1257 bt_query_executor_create_with_method_data() when creating this query
1258 operation's executor.
1260 \bt_p{params} is frozen.
1262 @param[in] method_data
1263 User data for this method, as passed as the \bt_p{method_data}
1264 parameter of bt_query_executor_create_with_method_data() when
1265 creating this query operation's executor.
1267 <strong>On success</strong>, \bt_p{*result} is
1268 a \em new reference of this query operation's result.
1270 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1272 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1273 \bt_p{object_name} is unknown.
1274 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1276 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1278 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1281 @bt_pre_not_null{self_component_class}
1282 @bt_pre_not_null{query_executor}
1283 @bt_pre_not_null{object_name}
1284 @bt_pre_not_null{params}
1285 @bt_pre_not_null{result}
1288 <strong>On success</strong>, \bt_p{*result} is set.
1290 @sa bt_component_class_source_set_query_method() —
1291 Sets the query method of a source component class.
1293 typedef bt_component_class_query_method_status
1294 (*bt_component_class_source_query_method
)(
1295 bt_self_component_class_source
*self_component_class
,
1296 bt_private_query_executor
*query_executor
,
1297 const char *object_name
, const bt_value
*params
,
1298 void *method_data
, const bt_value
**result
);
1302 \bt_c_flt_comp_cls query method.
1304 See the \ref api-comp-cls-dev-meth-query "query" method.
1306 @param[in] self_component_class
1307 Filter component class, as passed as the \bt_p{component_class}
1308 parameter of bt_query_executor_create() or
1309 bt_query_executor_create_with_method_data() when creating this query
1310 operation's \ref api-qexec "executor".
1311 @param[in] query_executor
1312 Private view of this query operation's executor.
1313 @param[in] object_name
1314 Name of the object to query, as passed as the \bt_p{object_name}
1315 parameter of bt_query_executor_create() or
1316 bt_query_executor_create_with_method_data() when creating this query
1317 operation's executor.
1320 Query parameters, as passed as the \bt_p{params}
1321 parameter of bt_query_executor_create() or
1322 bt_query_executor_create_with_method_data() when creating this query
1323 operation's executor.
1325 \bt_p{params} is frozen.
1327 @param[in] method_data
1328 User data for this method, as passed as the \bt_p{method_data}
1329 parameter of bt_query_executor_create_with_method_data() when
1330 creating this query operation's executor.
1332 <strong>On success</strong>, \bt_p{*result} is
1333 a \em new reference of this query operation's result.
1335 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1337 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1338 \bt_p{object_name} is unknown.
1339 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1341 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1343 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1346 @bt_pre_not_null{self_component_class}
1347 @bt_pre_not_null{query_executor}
1348 @bt_pre_not_null{object_name}
1349 @bt_pre_not_null{params}
1350 @bt_pre_not_null{result}
1353 <strong>On success</strong>, \bt_p{*result} is set.
1355 @sa bt_component_class_filter_set_query_method() —
1356 Sets the query method of a filter component class.
1358 typedef bt_component_class_query_method_status
1359 (*bt_component_class_filter_query_method
)(
1360 bt_self_component_class_filter
*self_component_class
,
1361 bt_private_query_executor
*query_executor
,
1362 const char *object_name
, const bt_value
*params
,
1363 void *method_data
, const bt_value
**result
);
1367 \bt_c_sink_comp_cls query method.
1369 See the \ref api-comp-cls-dev-meth-query "query" method.
1371 @param[in] self_component_class
1372 Sink component class, as passed as the \bt_p{component_class}
1373 parameter of bt_query_executor_create() or
1374 bt_query_executor_create_with_method_data() when creating this query
1375 operation's \ref api-qexec "executor".
1376 @param[in] query_executor
1377 Private view of this query operation's executor.
1378 @param[in] object_name
1379 Name of the object to query, as passed as the \bt_p{object_name}
1380 parameter of bt_query_executor_create() or
1381 bt_query_executor_create_with_method_data() when creating this query
1382 operation's executor.
1385 Query parameters, as passed as the \bt_p{params}
1386 parameter of bt_query_executor_create() or
1387 bt_query_executor_create_with_method_data() when creating this query
1388 operation's executor.
1390 \bt_p{params} is frozen.
1392 @param[in] method_data
1393 User data for this method, as passed as the \bt_p{method_data}
1394 parameter of bt_query_executor_create_with_method_data() when
1395 creating this query operation's executor.
1397 <strong>On success</strong>, \bt_p{*result} is
1398 a \em new reference of this query operation's result.
1400 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1402 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1403 \bt_p{object_name} is unknown.
1404 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1406 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1408 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1411 @bt_pre_not_null{self_component_class}
1412 @bt_pre_not_null{query_executor}
1413 @bt_pre_not_null{object_name}
1414 @bt_pre_not_null{params}
1415 @bt_pre_not_null{result}
1418 <strong>On success</strong>, \bt_p{*result} is set.
1420 @sa bt_component_class_sink_set_query_method() —
1421 Sets the query method of a sink component class.
1423 typedef bt_component_class_query_method_status
1424 (*bt_component_class_sink_query_method
)(
1425 bt_self_component_class_sink
*self_component_class
,
1426 bt_private_query_executor
*query_executor
,
1427 const char *object_name
, const bt_value
*params
,
1428 void *method_data
, const bt_value
**result
);
1439 Creates a \bt_src_comp_cls named \bt_p{name} and having the
1440 \bt_msg_iter_cls \bt_p{message_iterator_class}.
1442 On success, the returned source component class has the following
1450 <td>\ref api-comp-cls-prop-name "Name"
1453 <td>\ref api-comp-cls-prop-descr "Description"
1456 <td>\ref api-comp-cls-prop-help "Help text"
1461 Name of the source component class to create (copied).
1462 @param[in] message_iterator_class
1463 Message iterator class of the source component class to create.
1466 New source component class reference, or \c NULL on memory error.
1468 @bt_pre_not_null{name}
1469 @bt_pre_not_null{message_iterator_class}
1471 @bt_post_success_frozen{message_iterator_class}
1473 @sa bt_message_iterator_class_create() —
1474 Creates a message iterator class.
1477 bt_component_class_source
*bt_component_class_source_create(
1479 bt_message_iterator_class
*message_iterator_class
);
1483 Creates a \bt_flt_comp_cls named \bt_p{name} and having the
1484 \bt_msg_iter_cls \bt_p{message_iterator_class}.
1486 On success, the returned filter component class has the following
1494 <td>\ref api-comp-cls-prop-name "Name"
1497 <td>\ref api-comp-cls-prop-descr "Description"
1500 <td>\ref api-comp-cls-prop-help "Help text"
1505 Name of the filter component class to create (copied).
1506 @param[in] message_iterator_class
1507 Message iterator class of the filter component class to create.
1510 New filter component class reference, or \c NULL on memory error.
1512 @bt_pre_not_null{name}
1513 @bt_pre_not_null{message_iterator_class}
1515 @bt_post_success_frozen{message_iterator_class}
1517 @sa bt_message_iterator_class_create() —
1518 Creates a message iterator class.
1521 bt_component_class_filter
*bt_component_class_filter_create(
1523 bt_message_iterator_class
*message_iterator_class
);
1527 Creates a \bt_sink_comp_cls named \bt_p{name} and having the
1528 \ref api-comp-cls-dev-meth-consume "consuming method"
1529 \bt_p{consume_method}.
1531 On success, the returned sink component class has the following
1539 <td>\ref api-comp-cls-prop-name "Name"
1542 <td>\ref api-comp-cls-prop-descr "Description"
1545 <td>\ref api-comp-cls-prop-help "Help text"
1550 Name of the sink component class to create (copied).
1551 @param[in] consume_method
1552 Consuming method of the sink component class to create.
1555 New sink component class reference, or \c NULL on memory error.
1557 @bt_pre_not_null{name}
1558 @bt_pre_not_null{consume_method}
1561 bt_component_class_sink
*bt_component_class_sink_create(
1563 bt_component_class_sink_consume_method consume_method
);
1568 @name Common properties
1574 Status codes for bt_component_class_set_description().
1576 typedef enum bt_component_class_set_description_status
{
1581 BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1587 BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1588 } bt_component_class_set_description_status
;
1592 Sets the description of the component class \bt_p{component_class}
1593 to a copy of \bt_p{description}.
1595 See the \ref api-comp-cls-prop-descr "description" property.
1597 @param[in] component_class
1598 Component class of which to set the description to
1600 @param[in] description
1601 New description of \bt_p{component_class} (copied).
1603 @retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK
1605 @retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
1608 @bt_pre_not_null{component_class}
1609 @bt_pre_hot{component_class}
1610 @bt_pre_not_null{description}
1612 @sa bt_component_class_get_description() —
1613 Returns the description of a component class.
1615 extern bt_component_class_set_description_status
1616 bt_component_class_set_description(bt_component_class
*component_class
,
1617 const char *description
);
1621 Status codes for bt_component_class_set_help().
1623 typedef enum bt_component_class_set_help_status
{
1628 BT_COMPONENT_CLASS_SET_HELP_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1634 BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1635 } bt_component_class_set_help_status
;
1639 Sets the help text of the component class \bt_p{component_class}
1640 to a copy of \bt_p{help_text}.
1642 See the \ref api-comp-cls-prop-help "help text" property.
1644 @param[in] component_class
1645 Component class of which to set the help text to
1647 @param[in] help_text
1648 New help text of \bt_p{component_class} (copied).
1650 @retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_OK
1652 @retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR
1655 @bt_pre_not_null{component_class}
1656 @bt_pre_hot{component_class}
1657 @bt_pre_not_null{help_text}
1659 @sa bt_component_class_get_help() —
1660 Returns the help text of a component class.
1662 extern bt_component_class_set_help_status
bt_component_class_set_help(
1663 bt_component_class
*component_class
,
1664 const char *help_text
);
1669 @name Method setting
1676 <code>bt_component_class_*_set_*_method()</code> functions.
1678 typedef enum bt_component_class_set_method_status
{
1683 BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1684 } bt_component_class_set_method_status
;
1688 Sets the optional finalization method of the \bt_src_comp_cls
1689 \bt_p{component_class} to \bt_p{method}.
1691 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1693 @param[in] component_class
1694 Source component class of which to set the finalization method to
1697 New finalization method of \bt_p{component_class}.
1699 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1702 @bt_pre_not_null{component_class}
1703 @bt_pre_hot{component_class}
1704 @bt_pre_not_null{method}
1706 extern bt_component_class_set_method_status
1707 bt_component_class_source_set_finalize_method(
1708 bt_component_class_source
*component_class
,
1709 bt_component_class_source_finalize_method method
);
1713 Sets the optional finalization method of the \bt_flt_comp_cls
1714 \bt_p{component_class} to \bt_p{method}.
1716 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1718 @param[in] component_class
1719 Filter component class of which to set the finalization method to
1722 New finalization method of \bt_p{component_class}.
1724 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1727 @bt_pre_not_null{component_class}
1728 @bt_pre_hot{component_class}
1729 @bt_pre_not_null{method}
1731 extern bt_component_class_set_method_status
1732 bt_component_class_filter_set_finalize_method(
1733 bt_component_class_filter
*component_class
,
1734 bt_component_class_filter_finalize_method method
);
1738 Sets the optional finalization method of the \bt_sink_comp_cls
1739 \bt_p{component_class} to \bt_p{method}.
1741 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1743 @param[in] component_class
1744 Sink component class of which to set the finalization method to
1747 New finalization method of \bt_p{component_class}.
1749 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1752 @bt_pre_not_null{component_class}
1753 @bt_pre_hot{component_class}
1754 @bt_pre_not_null{method}
1757 bt_component_class_set_method_status
1758 bt_component_class_sink_set_finalize_method(
1759 bt_component_class_sink
*component_class
,
1760 bt_component_class_sink_finalize_method method
);
1764 Sets the \"get supported \bt_mip versions\" method of the
1765 \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
1767 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1770 @param[in] component_class
1771 Source component class of which to set the "get supported MIP
1772 versions" method to \bt_p{method}.
1774 New "get supported MIP versions" method of \bt_p{component_class}.
1776 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1779 @bt_pre_not_null{component_class}
1780 @bt_pre_hot{component_class}
1781 @bt_pre_not_null{method}
1783 extern bt_component_class_set_method_status
1784 bt_component_class_source_set_get_supported_mip_versions_method(
1785 bt_component_class_source
*component_class
,
1786 bt_component_class_source_get_supported_mip_versions_method method
);
1790 Sets the \"get supported \bt_mip versions\" method of the
1791 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
1793 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1796 @param[in] component_class
1797 Filter component class of which to set the "get supported MIP
1798 versions" method to \bt_p{method}.
1800 New "get supported MIP versions" method of \bt_p{component_class}.
1802 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1805 @bt_pre_not_null{component_class}
1806 @bt_pre_hot{component_class}
1807 @bt_pre_not_null{method}
1809 extern bt_component_class_set_method_status
1810 bt_component_class_filter_set_get_supported_mip_versions_method(
1811 bt_component_class_filter
*component_class
,
1812 bt_component_class_filter_get_supported_mip_versions_method method
);
1816 Sets the \"get supported \bt_mip versions\" method of the
1817 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
1819 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1822 @param[in] component_class
1823 Sink component class of which to set the "get supported MIP
1824 versions" method to \bt_p{method}.
1826 New "get supported MIP versions" method of \bt_p{component_class}.
1828 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1831 @bt_pre_not_null{component_class}
1832 @bt_pre_hot{component_class}
1833 @bt_pre_not_null{method}
1835 extern bt_component_class_set_method_status
1836 bt_component_class_sink_set_get_supported_mip_versions_method(
1837 bt_component_class_sink
*component_class
,
1838 bt_component_class_sink_get_supported_mip_versions_method method
);
1842 Sets the "graph is configured" method of the
1843 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
1846 \ref api-comp-cls-dev-meth-graph-configured "graph is configured"
1849 @param[in] component_class
1850 Sink component class of which to set the "graph is configured"
1851 method to \bt_p{method}.
1853 New "graph is configured" method of \bt_p{component_class}.
1855 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1858 @bt_pre_not_null{component_class}
1859 @bt_pre_hot{component_class}
1860 @bt_pre_not_null{method}
1863 bt_component_class_set_method_status
1864 bt_component_class_sink_set_graph_is_configured_method(
1865 bt_component_class_sink
*component_class
,
1866 bt_component_class_sink_graph_is_configured_method method
);
1870 Sets the optional initialization method of the \bt_src_comp_cls
1871 \bt_p{component_class} to \bt_p{method}.
1873 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1875 @param[in] component_class
1876 Source component class of which to set the initialization method to
1879 New initialization method of \bt_p{component_class}.
1881 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1884 @bt_pre_not_null{component_class}
1885 @bt_pre_hot{component_class}
1886 @bt_pre_not_null{method}
1888 extern bt_component_class_set_method_status
1889 bt_component_class_source_set_initialize_method(
1890 bt_component_class_source
*component_class
,
1891 bt_component_class_source_initialize_method method
);
1895 Sets the optional initialization method of the \bt_flt_comp_cls
1896 \bt_p{component_class} to \bt_p{method}.
1898 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1900 @param[in] component_class
1901 Filter component class of which to set the initialization method to
1904 New initialization method of \bt_p{component_class}.
1906 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1909 @bt_pre_not_null{component_class}
1910 @bt_pre_hot{component_class}
1911 @bt_pre_not_null{method}
1913 extern bt_component_class_set_method_status
1914 bt_component_class_filter_set_initialize_method(
1915 bt_component_class_filter
*component_class
,
1916 bt_component_class_filter_initialize_method method
);
1920 Sets the optional initialization method of the \bt_sink_comp_cls
1921 \bt_p{component_class} to \bt_p{method}.
1923 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1925 @param[in] component_class
1926 Sink component class of which to set the initialization method to
1929 New initialization method of \bt_p{component_class}.
1931 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1934 @bt_pre_not_null{component_class}
1935 @bt_pre_hot{component_class}
1936 @bt_pre_not_null{method}
1939 bt_component_class_set_method_status
1940 bt_component_class_sink_set_initialize_method(
1941 bt_component_class_sink
*component_class
,
1942 bt_component_class_sink_initialize_method method
);
1946 Sets the optional "output port connected" method of the
1947 \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
1950 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1953 @param[in] component_class
1954 Source component class of which to set the "output port connected"
1955 method to \bt_p{method}.
1957 New "output port connected" method of \bt_p{component_class}.
1959 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1962 @bt_pre_not_null{component_class}
1963 @bt_pre_hot{component_class}
1964 @bt_pre_not_null{method}
1966 extern bt_component_class_set_method_status
1967 bt_component_class_source_set_output_port_connected_method(
1968 bt_component_class_source
*component_class
,
1969 bt_component_class_source_output_port_connected_method method
);
1973 Sets the optional "input port connected" method of the
1974 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
1977 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1980 @param[in] component_class
1981 Filter component class of which to set the "input port connected"
1982 method to \bt_p{method}.
1984 New "input port connected" method of \bt_p{component_class}.
1986 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1989 @bt_pre_not_null{component_class}
1990 @bt_pre_hot{component_class}
1991 @bt_pre_not_null{method}
1993 extern bt_component_class_set_method_status
1994 bt_component_class_filter_set_input_port_connected_method(
1995 bt_component_class_filter
*component_class
,
1996 bt_component_class_filter_input_port_connected_method method
);
2000 Sets the optional "output port connected" method of the
2001 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
2004 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
2007 @param[in] component_class
2008 Filter component class of which to set the "output port connected"
2009 method to \bt_p{method}.
2011 New "output port connected" method of \bt_p{component_class}.
2013 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2016 @bt_pre_not_null{component_class}
2017 @bt_pre_hot{component_class}
2018 @bt_pre_not_null{method}
2020 extern bt_component_class_set_method_status
2021 bt_component_class_filter_set_output_port_connected_method(
2022 bt_component_class_filter
*component_class
,
2023 bt_component_class_filter_output_port_connected_method method
);
2027 Sets the optional "input port connected" method of the
2028 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
2031 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
2034 @param[in] component_class
2035 Sink component class of which to set the "input port connected"
2036 method to \bt_p{method}.
2038 New "input port connected" method of \bt_p{component_class}.
2040 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2043 @bt_pre_not_null{component_class}
2044 @bt_pre_hot{component_class}
2045 @bt_pre_not_null{method}
2048 bt_component_class_set_method_status
2049 bt_component_class_sink_set_input_port_connected_method(
2050 bt_component_class_sink
*component_class
,
2051 bt_component_class_sink_input_port_connected_method method
);
2055 Sets the optional query method of the \bt_src_comp_cls
2056 \bt_p{component_class} to \bt_p{method}.
2058 See the \ref api-comp-cls-dev-meth-query "query" method.
2060 @param[in] component_class
2061 Source component class of which to set the query method to
2064 New query method of \bt_p{component_class}.
2066 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2069 @bt_pre_not_null{component_class}
2070 @bt_pre_hot{component_class}
2071 @bt_pre_not_null{method}
2073 extern bt_component_class_set_method_status
2074 bt_component_class_source_set_query_method(
2075 bt_component_class_source
*component_class
,
2076 bt_component_class_source_query_method method
);
2080 Sets the optional query method of the \bt_flt_comp_cls
2081 \bt_p{component_class} to \bt_p{method}.
2083 See the \ref api-comp-cls-dev-meth-query "query" method.
2085 @param[in] component_class
2086 Filter component class of which to set the query method to
2089 New query method of \bt_p{component_class}.
2091 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2094 @bt_pre_not_null{component_class}
2095 @bt_pre_hot{component_class}
2096 @bt_pre_not_null{method}
2098 extern bt_component_class_set_method_status
2099 bt_component_class_filter_set_query_method(
2100 bt_component_class_filter
*component_class
,
2101 bt_component_class_filter_query_method method
);
2105 Sets the optional query method of the \bt_sink_comp_cls
2106 \bt_p{component_class} to \bt_p{method}.
2108 See the \ref api-comp-cls-dev-meth-query "query" method.
2110 @param[in] component_class
2111 Sink component class of which to set the query method to
2114 New query method of \bt_p{component_class}.
2116 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2119 @bt_pre_not_null{component_class}
2120 @bt_pre_hot{component_class}
2121 @bt_pre_not_null{method}
2124 bt_component_class_set_method_status
2125 bt_component_class_sink_set_query_method(
2126 bt_component_class_sink
*component_class
,
2127 bt_component_class_sink_query_method method
);
2138 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
2139 \bt_p{component_class} to the common #bt_component_class type.
2141 @param[in] component_class
2143 Source component class to upcast.
2149 \bt_p{component_class} as a common component class.
2152 bt_component_class
*bt_component_class_source_as_component_class(
2153 bt_component_class_source
*component_class
)
2155 return __BT_UPCAST(bt_component_class
, component_class
);
2160 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
2161 \bt_p{component_class} to the common #bt_component_class type.
2163 @param[in] component_class
2165 Filter component class to upcast.
2171 \bt_p{component_class} as a common component class.
2174 bt_component_class
*bt_component_class_filter_as_component_class(
2175 bt_component_class_filter
*component_class
)
2177 return __BT_UPCAST(bt_component_class
, component_class
);
2182 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
2183 \bt_p{component_class} to the common #bt_component_class type.
2185 @param[in] component_class
2187 Sink component class to upcast.
2193 \bt_p{component_class} as a common component class.
2196 bt_component_class
*bt_component_class_sink_as_component_class(
2197 bt_component_class_sink
*component_class
)
2199 return __BT_UPCAST(bt_component_class
, component_class
);
2210 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H */