1 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
2 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
31 #include <babeltrace2/logging.h>
38 @defgroup api-comp-cls-dev Component class development
42 Component class development (creation).
44 A <strong><em>component class</em></strong> is the class of a \bt_comp:
46 @image html component.png
49 This module (component class development API) offers functions to
50 programatically create component classes. To get the properties of
51 an existing component class, see \ref api-comp-cls.
53 A component class has <em>methods</em>. This module essentially
56 - Component class method type definitions.
58 - Component class creation functions, to which you pass a mandatory
59 \bt_msg_iter_cls or method.
61 - Functions to set optional component class methods.
63 - Functions to set optional component class properties.
65 A component class method is a user function. There are two types of
69 <dt>\anchor api-comp-cls-dev-instance-meth Instance method</dt>
71 Operates on an instance (a \bt_comp).
73 The type of the method's first parameter is
74 #bt_self_component_source, #bt_self_component_filter, or
75 bt_self_component_sink, depending on the component class's type.
77 This is similar to an instance method in Python (where the instance
78 object name is generally <code>self</code>) or a member function
79 in C++ (where the instance pointer is named <code>this</code>),
83 <dt>\anchor api-comp-cls-dev-class-meth Class method</dt>
85 Operates on a component class.
87 The type of the method's first parameter is
88 #bt_self_component_class_source, #bt_self_component_class_filter, or
89 bt_self_component_class_sink, depending on the component class's
92 This is similar to a class method in Python or a static member
93 function in C++, for example.
97 See \ref api-comp-cls-dev-methods "Methods" to learn more about the
98 different types of component class methods.
100 A component class is a \ref api-fund-shared-object "shared object": see
101 the \ref api-comp-cls module for the reference count functions.
103 Some library functions \ref api-fund-freezing "freeze" component classes
104 on success. The documentation of those functions indicate this
107 Create a component class with bt_component_class_source_create(),
108 bt_component_class_filter_create(), and
109 bt_component_class_sink_create(). You must give the component class a
110 name (not unique in any way) at creation time.
112 When you create a \bt_src_comp_cls or a \bt_flt_comp_cls, you must pass
113 a \bt_msg_iter_cls. This is the class of any \bt_msg_iter created for
114 one of the component class's instance's \bt_oport.
116 When you create a \bt_sink_comp_cls, you must pass a
117 \ref api-comp-cls-dev-meth-consume "consuming method".
119 \ref api-fund-c-typing "Upcast" the #bt_component_class_source,
120 #bt_component_class_filter, and bt_component_class_sink types returned
121 by the creation functions to the #bt_component_class type with
122 bt_component_class_source_as_component_class(),
123 bt_component_class_filter_as_component_class(), and
124 bt_component_class_sink_as_component_class().
126 Set the \ref api-comp-cls-prop-descr "description" and the
127 \ref api-comp-cls-prop-help "help text" of a component class with
128 bt_component_class_set_description() and
129 bt_component_class_set_help().
131 <h1>\anchor api-comp-cls-dev-methods Methods</h1>
133 To learn when exactly the methods below are called, see
134 \ref api-graph-lc "Trace processing graph life cycle".
136 The available component class methods to implement are:
142 <th>Component class types
144 <th>Graph is \ref api-graph-lc "configured"?
148 <td>\ref api-comp-cls-dev-instance-meth "Instance"
152 <td>#bt_component_class_sink_consume_method
160 #bt_component_class_source_finalize_method<br>
161 #bt_component_class_filter_finalize_method<br>
162 #bt_component_class_sink_finalize_method
164 <td>Get supported \bt_mip (MIP) versions
165 <td>\ref api-comp-cls-dev-class-meth "Class"
170 #bt_component_class_source_get_supported_mip_versions_method<br>
171 #bt_component_class_filter_get_supported_mip_versions_method<br>
172 #bt_component_class_sink_get_supported_mip_versions_method
174 <td>Graph is \ref api-graph-lc "configured"
179 <td>#bt_component_class_sink_graph_is_configured_method
187 #bt_component_class_source_initialize_method<br>
188 #bt_component_class_filter_initialize_method<br>
189 #bt_component_class_sink_initialize_method
191 <td>\bt_c_iport connected
197 #bt_component_class_filter_input_port_connected_method<br>
198 #bt_component_class_sink_input_port_connected_method
200 <td>\bt_c_oport connected
202 <td>Source and filter
206 #bt_component_class_source_output_port_connected_method<br>
207 #bt_component_class_filter_output_port_connected_method
215 #bt_component_class_source_query_method<br>
216 #bt_component_class_filter_query_method<br>
217 #bt_component_class_sink_query_method
222 \anchor api-comp-cls-dev-meth-consume
226 Called within bt_graph_run() or bt_graph_run_once() to make your
227 \bt_sink_comp consume and process \bt_p_msg.
229 This method typically gets \em one message batch from one (or more)
230 upstream \bt_msg_iter. You are free to get more than one batch of
231 messages if needed; however, keep in mind that the \bt_name project
232 recommends that this method executes fast enough so as not to block
233 an interactive application running on the same thread.
235 During what you consider to be a long, blocking operation, the
236 project recommends that you periodically check whether or not you
237 are interrupted with bt_self_component_sink_is_interrupted(). When
238 you are, you can return either
239 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN or
240 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR, depending on
241 your capability to continue the current operation later.
243 If you need to block the thread, you can instead report to
244 try again later to the bt_graph_run() or bt_graph_run_once() caller
245 by returning #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN.
247 If your sink component is done consuming and processing, return
248 #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END from this method.
249 The trace processing \bt_graph can continue to run afterwards if
250 other sink components are still consuming.
252 Within this method, you \em cannot add an \bt_iport with
253 bt_self_component_sink_add_input_port().
255 Set this mandatory method at sink component class creation time with
256 bt_component_class_sink_create().
260 \anchor api-comp-cls-dev-meth-fini
264 Called to finalize your \bt_comp, that is, to let you
265 destroy/free/finalize any user data you have (retrieved with
266 bt_self_component_get_data()).
268 The \bt_name library does not specify exactly when this method is
269 called, but guarantees that it's called before the component is
272 For \bt_p_src_comp and \bt_p_flt_comp, the library guarantees that
273 this method is called \em after all the component's \bt_p_msg_iter
276 This method is \em not called if the component's
277 \ref api-comp-cls-dev-meth-init "initialization method"
278 previously returned an error status code.
280 Within this method, you cannot:
283 - Use any \bt_msg_iter.
285 Set this optional method with
286 bt_component_class_source_set_finalize_method(),
287 bt_component_class_filter_set_finalize_method(), and
288 bt_component_class_sink_set_finalize_method().
292 \anchor api-comp-cls-dev-meth-mip
293 Get supported \bt_mip (MIP) versions
296 Called within bt_get_greatest_operative_mip_version() to get the
297 set of MIP versions that an eventual \bt_comp supports.
299 This is a \ref api-comp-cls-dev-class-meth "class method" because
300 you can call bt_get_greatest_operative_mip_version() before you even
301 create a trace processing \bt_graph.
303 In this method, you receive initialization parameters as the
304 \bt_p{params} parameter and initialization method data as the
305 \bt_p{initialize_method_data}. Those parameters are set
306 when bt_component_descriptor_set_add_descriptor() is called, before
307 bt_get_greatest_operative_mip_version() is called.
309 Considering those initialization parameters, you need to fill the
310 received \bt_uint_rs \bt_p{supported_versions} with the rangs of
311 MIP versions you support.
313 As of \bt_name_version_min_maj, you can only support MIP version 0.
315 Not having this method is equivalent to having one which adds the
316 [0, 0] range to the \bt_p{supported_versions} set.
318 Set this optional method with
319 bt_component_class_source_set_get_supported_mip_versions_method(),
320 bt_component_class_filter_set_get_supported_mip_versions_method(),
321 and bt_component_class_sink_set_get_supported_mip_versions_method().
325 \anchor api-comp-cls-dev-meth-graph-configured
326 Graph is \ref api-graph-lc "configured"
329 For a given trace processing \bt_graph, called the first time
330 bt_graph_run() or bt_graph_run_once() is called to notify your
331 \bt_sink_comp that the graph is now configured.
333 Within this method, you can create \bt_p_msg_iter on your sink
334 component's \bt_p_iport. You can also manipulate those message
335 iterators, for example get and process initial messages or make
338 This method is called \em after the component's
339 \ref api-comp-cls-dev-meth-init "initialization method"
340 is called. You cannot create a message iterator in the
341 initialization method.
343 Within this method, you \em cannot add an \bt_iport with
344 bt_self_component_sink_add_input_port().
346 Set this optional method with
347 bt_component_class_sink_set_graph_is_configured_method().
351 \anchor api-comp-cls-dev-meth-init
355 Called within a <code>bt_graph_add_*_component*()</code> function
356 (see \ref api-graph) to initialize your \bt_comp.
358 Within this method, you receive the initialization parameters and
359 initialization method data passed to the
360 <code>bt_graph_add_*_component*()</code> function.
362 This method is where you can add initial \bt_p_port to your
363 component with bt_self_component_source_add_output_port(),
364 bt_self_component_filter_add_input_port(),
365 bt_self_component_filter_add_output_port(), or
366 bt_self_component_sink_add_input_port().
367 You can also add ports in the
368 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
370 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
373 You can create user data and set it as the \bt_self_comp's user data
374 with bt_self_component_set_data().
376 If you return #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK from
377 this method, then your component's
378 \ref api-comp-cls-dev-meth-fini "finalization method" will be
379 called, if it exists, when your component is finalized.
381 Set this optional method with
382 bt_component_class_source_set_initialize_method(),
383 bt_component_class_filter_set_initialize_method(),
384 and bt_component_class_sink_set_initialize_method().
388 \anchor api-comp-cls-dev-meth-iport-connected
389 \bt_c_iport connected
392 Called within bt_graph_connect_ports() to notify your \bt_comp that
393 one of its input ports has been connected.
395 Within this method, you can add more \bt_p_port to your
396 component with bt_self_component_source_add_output_port(),
397 bt_self_component_filter_add_input_port(),
398 bt_self_component_filter_add_output_port(), or
399 bt_self_component_sink_add_input_port().
401 Set this optional method with
402 bt_component_class_filter_set_input_port_connected_method() and
403 bt_component_class_sink_set_input_port_connected_method().
407 \anchor api-comp-cls-dev-meth-oport-connected
408 \bt_c_oport connected
411 Called within bt_graph_connect_ports() to notify your \bt_comp that
412 one of its output ports has been connected.
414 Within this method, you can add more \bt_p_port to your
415 component with bt_self_component_source_add_output_port(),
416 bt_self_component_filter_add_input_port(),
417 bt_self_component_filter_add_output_port(), or
418 bt_self_component_sink_add_input_port().
420 Set this optional method with
421 bt_component_class_source_set_output_port_connected_method() and
422 bt_component_class_filter_set_output_port_connected_method().
426 \anchor api-comp-cls-dev-meth-query
430 Called within bt_query_executor_query() to make your \bt_comp_cls
431 perform a query operation.
433 Within this method, you receive the query object name, the
434 query parameters, and the method data passed when the
435 \bt_qexec was created with bt_query_executor_create() or
436 bt_query_executor_create_with_method_data().
438 You also receive a private view of the query executor which you can
439 cast to a \c const query executor with
440 bt_private_query_executor_as_query_executor_const() to access the
441 executor's logging level with bt_query_executor_get_logging_level().
443 On success, set \bt_p{*result} to the query operation's result: a
444 \em new \bt_val reference.
446 If the queried object's name (\bt_p{object_name} parameter) is
448 #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT.
450 If you need to block the thread, you can instead report to
451 try again later to the bt_query_executor_query() caller
452 by returning #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN.
454 Set this optional method with
455 bt_component_class_source_set_query_method(),
456 bt_component_class_filter_set_query_method(), and
457 bt_component_class_sink_set_query_method().
463 In any of the methods above:
465 - \em Never call bt_component_get_ref(),
466 bt_component_source_get_ref(), bt_component_filter_get_ref(), or
467 bt_component_sink_get_ref() on your own (upcasted) \bt_self_comp
468 to avoid reference cycles.
470 You can keep a borrowed (weak) \bt_self_comp reference in your
471 component's user data (see bt_self_component_set_data()).
473 - \em Never call bt_port_get_ref(), bt_port_input_get_ref(), or
474 bt_port_output_get_ref() on one of your own (upcasted)
475 \bt_p_self_comp_port to avoid reference cycles.
477 - \em Never call bt_component_class_get_ref(),
478 bt_component_class_source_get_ref(),
479 bt_component_class_filter_get_ref(), or
480 bt_component_class_sink_get_ref() on your own (upcasted)
481 \bt_comp_cls to avoid reference cycles.
484 Within any \ref api-comp-cls-dev-instance-meth "instance method", you
485 can access the \bt_comp's configured
486 \ref #bt_logging_level "logging level" by first upcasting the
487 \bt_self_comp to the #bt_component type with
488 bt_self_component_as_component(), and then with
489 bt_component_get_logging_level().
501 Status codes for #bt_component_class_sink_consume_method.
503 typedef enum bt_component_class_sink_consume_method_status
{
508 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
512 Sink component is finished processing.
514 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END
= __BT_FUNC_STATUS_END
,
520 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
526 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
532 BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
533 } bt_component_class_sink_consume_method_status
;
537 \bt_c_sink_comp consuming method.
539 See the \ref api-comp-cls-dev-meth-consume "consume" method.
541 @param[in] self_component
542 \bt_c_sink_comp instance.
544 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK
546 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END
548 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN
550 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR
552 @retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR
555 @bt_pre_not_null{self_component}
557 @sa bt_component_class_sink_create() —
558 Creates a \bt_sink_comp.
560 typedef bt_component_class_sink_consume_method_status
561 (*bt_component_class_sink_consume_method
)(
562 bt_self_component_sink
*self_component
);
566 \bt_c_src_comp finalization method.
568 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
570 @param[in] self_component
571 Source component instance.
573 @bt_pre_not_null{self_component}
577 @sa bt_component_class_source_set_finalize_method() —
578 Sets the finalization method of a source component class.
580 typedef void (*bt_component_class_source_finalize_method
)(
581 bt_self_component_source
*self_component
);
585 \bt_c_flt_comp finalization method.
587 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
589 @param[in] self_component
590 Filter component instance.
592 @bt_pre_not_null{self_component}
596 @sa bt_component_class_filter_set_finalize_method() —
597 Sets the finalization method of a filter component class.
599 typedef void (*bt_component_class_filter_finalize_method
)(
600 bt_self_component_filter
*self_component
);
604 \bt_c_sink_comp finalization method.
606 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
608 @param[in] self_component
609 Sink component instance.
611 @bt_pre_not_null{self_component}
615 @sa bt_component_class_sink_set_finalize_method() —
616 Sets the finalization method of a sink component class.
618 typedef void (*bt_component_class_sink_finalize_method
)(
619 bt_self_component_sink
*self_component
);
624 #bt_component_class_source_get_supported_mip_versions_method,
625 #bt_component_class_filter_get_supported_mip_versions_method, and
626 #bt_component_class_sink_get_supported_mip_versions_method.
628 typedef enum bt_component_class_get_supported_mip_versions_method_status
{
633 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
639 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
645 BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
646 } bt_component_class_get_supported_mip_versions_method_status
;
650 \bt_c_src_comp_cls \"get supported \bt_mip versions\" method.
652 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
655 As of \bt_name_version_min_maj, you can only add the range [0, 0]
656 to \bt_p{supported_versions}.
658 @param[in] self_component_class
659 Source component class.
662 Initialization parameters, as passed as the \bt_p{params} parameter
663 of bt_component_descriptor_set_add_descriptor() or
664 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
666 \bt_p{params} is frozen.
668 @param[in] initialize_method_data
669 User data for this method, as passed as the
670 \bt_p{init_method_data} parameter of
671 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
672 @param[in] logging_level
673 Logging level to use during this method's execution, as passed
674 as the \bt_p{logging_level} parameter of
675 bt_get_greatest_operative_mip_version().
676 @param[in] supported_versions
677 \bt_c_uint_rs to which to add the ranges of supported MIP versions
678 of an eventual instance of \bt_p{self_component_class} considering
679 \bt_p{params} and \bt_p{initialize_method_data}.
681 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
683 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
685 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
688 @bt_pre_not_null{self_component_class}
689 @bt_pre_not_null{params}
690 @bt_pre_is_map_val{params}
691 @bt_pre_not_null{supported_versions}
693 \bt_p{supported_versions} is empty.
695 @sa bt_component_class_source_set_get_supported_mip_versions_method() —
696 Sets the "get supported MIP versions" method of a source
699 typedef bt_component_class_get_supported_mip_versions_method_status
700 (*bt_component_class_source_get_supported_mip_versions_method
)(
701 bt_self_component_class_source
*self_component_class
,
702 const bt_value
*params
, void *initialize_method_data
,
703 bt_logging_level logging_level
,
704 bt_integer_range_set_unsigned
*supported_versions
);
709 \bt_c_flt_comp_cls \"get supported \bt_mip versions\" method.
711 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
714 As of \bt_name_version_min_maj, you can only add the range [0, 0]
715 to \bt_p{supported_versions}.
717 @param[in] self_component_class
718 Filter component class.
721 Initialization parameters, as passed as the \bt_p{params} parameter
722 of bt_component_descriptor_set_add_descriptor() or
723 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
725 \bt_p{params} is frozen.
727 @param[in] initialize_method_data
728 User data for this method, as passed as the
729 \bt_p{init_method_data} parameter of
730 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
731 @param[in] logging_level
732 Logging level to use during this method's execution, as passed
733 as the \bt_p{logging_level} parameter of
734 bt_get_greatest_operative_mip_version().
735 @param[in] supported_versions
736 \bt_c_uint_rs to which to add the ranges of supported MIP versions
737 of an eventual instance of \bt_p{self_component_class} considering
738 \bt_p{params} and \bt_p{initialize_method_data}.
740 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
742 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
744 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
747 @bt_pre_not_null{self_component_class}
748 @bt_pre_not_null{params}
749 @bt_pre_is_map_val{params}
750 @bt_pre_not_null{supported_versions}
752 \bt_p{supported_versions} is empty.
754 @sa bt_component_class_filter_set_get_supported_mip_versions_method() —
755 Sets the "get supported MIP versions" method of a filter
758 typedef bt_component_class_get_supported_mip_versions_method_status
759 (*bt_component_class_filter_get_supported_mip_versions_method
)(
760 bt_self_component_class_filter
*source_component_class
,
761 const bt_value
*params
, void *initialize_method_data
,
762 bt_logging_level logging_level
,
763 bt_integer_range_set_unsigned
*supported_versions
);
767 \bt_c_sink_comp_cls \"get supported \bt_mip versions\" method.
769 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
772 As of \bt_name_version_min_maj, you can only add the range [0, 0]
773 to \bt_p{supported_versions}.
775 @param[in] self_component_class
776 Sink component class.
779 Initialization parameters, as passed as the \bt_p{params} parameter
780 of bt_component_descriptor_set_add_descriptor() or
781 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
783 \bt_p{params} is frozen.
785 @param[in] initialize_method_data
786 User data for this method, as passed as the
787 \bt_p{init_method_data} parameter of
788 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
789 @param[in] logging_level
790 Logging level to use during this method's execution, as passed
791 as the \bt_p{logging_level} parameter of
792 bt_get_greatest_operative_mip_version().
793 @param[in] supported_versions
794 \bt_c_uint_rs to which to add the ranges of supported MIP versions
795 of an eventual instance of \bt_p{self_component_class} considering
796 \bt_p{params} and \bt_p{initialize_method_data}.
798 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
800 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
802 @retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
805 @bt_pre_not_null{self_component_class}
806 @bt_pre_not_null{params}
807 @bt_pre_is_map_val{params}
808 @bt_pre_not_null{supported_versions}
810 \bt_p{supported_versions} is empty.
812 @sa bt_component_class_sink_set_get_supported_mip_versions_method() —
813 Sets the "get supported MIP versions" method of a sink
816 typedef bt_component_class_get_supported_mip_versions_method_status
817 (*bt_component_class_sink_get_supported_mip_versions_method
)(
818 bt_self_component_class_sink
*source_component_class
,
819 const bt_value
*params
, void *initialize_method_data
,
820 bt_logging_level logging_level
,
821 bt_integer_range_set_unsigned
*supported_versions
);
826 #bt_component_class_sink_graph_is_configured_method.
828 typedef enum bt_component_class_sink_graph_is_configured_method_status
{
833 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
839 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
845 BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
846 } bt_component_class_sink_graph_is_configured_method_status
;
850 \bt_c_sink_comp "graph is configured" method.
852 See the \ref api-comp-cls-dev-meth-graph-configured
853 "graph is configured" method.
855 @param[in] self_component
856 Sink component instance.
858 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK
860 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR
862 @retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR
865 @bt_pre_not_null{self_component}
867 @sa bt_component_class_sink_set_graph_is_configured_method() —
868 Sets the "graph is configured" method of a sink component class.
870 typedef bt_component_class_sink_graph_is_configured_method_status
871 (*bt_component_class_sink_graph_is_configured_method
)(
872 bt_self_component_sink
*self_component
);
877 #bt_component_class_source_initialize_method,
878 #bt_component_class_filter_initialize_method, and
879 #bt_component_class_sink_initialize_method.
881 typedef enum bt_component_class_initialize_method_status
{
886 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
892 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
898 BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
899 } bt_component_class_initialize_method_status
;
903 \bt_c_src_comp initialization method.
905 See the \ref api-comp-cls-dev-meth-init "initialize" method.
907 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
910 @param[in] self_component
911 Source component instance.
912 @param[in] configuration
913 Initial component configuration (unused).
916 Initialization parameters, as passed as the \bt_p{params} parameter
917 of bt_graph_add_source_component() or
918 bt_graph_add_source_component_with_initialize_method_data().
920 \bt_p{params} is frozen.
922 @param[in] initialize_method_data
923 User data for this method, as passed as the
924 \bt_p{initialize_method_data} parameter of
925 bt_graph_add_source_component_with_initialize_method_data().
927 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
929 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
931 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
934 @bt_pre_not_null{self_component}
935 @bt_pre_not_null{configuration}
936 @bt_pre_not_null{params}
937 @bt_pre_is_map_val{params}
939 @sa bt_component_class_source_set_initialize_method() —
940 Sets the initialization method of a source component class.
942 typedef bt_component_class_initialize_method_status
943 (*bt_component_class_source_initialize_method
)(
944 bt_self_component_source
*self_component
,
945 bt_self_component_source_configuration
*configuration
,
946 const bt_value
*params
, void *initialize_method_data
);
950 \bt_c_flt_comp initialization method.
952 See the \ref api-comp-cls-dev-meth-init "initialize" method.
954 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
957 @param[in] self_component
958 Filter component instance.
959 @param[in] configuration
960 Initial component configuration (unused).
963 Initialization parameters, as passed as the \bt_p{params} parameter
964 of bt_graph_add_filter_component() or
965 bt_graph_add_filter_component_with_initialize_method_data().
967 \bt_p{params} is frozen.
969 @param[in] initialize_method_data
970 User data for this method, as passed as the
971 \bt_p{initialize_method_data} parameter of
972 bt_graph_add_filter_component_with_initialize_method_data().
974 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
976 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
978 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
981 @bt_pre_not_null{self_component}
982 @bt_pre_not_null{configuration}
983 @bt_pre_not_null{params}
984 @bt_pre_is_map_val{params}
986 @sa bt_component_class_filter_set_initialize_method() —
987 Sets the initialization method of a filter component class.
989 typedef bt_component_class_initialize_method_status
990 (*bt_component_class_filter_initialize_method
)(
991 bt_self_component_filter
*self_component
,
992 bt_self_component_filter_configuration
*configuration
,
993 const bt_value
*params
, void *initialize_method_data
);
997 \bt_c_sink_comp initialization method.
999 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1001 As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
1004 @param[in] self_component
1005 Sink component instance.
1006 @param[in] configuration
1007 Initial component configuration (unused).
1010 Initialization parameters, as passed as the \bt_p{params} parameter
1011 of bt_graph_add_sink_component(),
1012 bt_graph_add_sink_component_with_initialize_method_data(), or
1013 bt_graph_add_simple_sink_component().
1015 \bt_p{params} is frozen.
1017 @param[in] initialize_method_data
1018 User data for this method, as passed as the
1019 \bt_p{initialize_method_data} parameter of
1020 bt_graph_add_sink_component_with_initialize_method_data().
1022 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
1024 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
1026 @retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
1029 @bt_pre_not_null{self_component}
1030 @bt_pre_not_null{configuration}
1031 @bt_pre_not_null{params}
1032 @bt_pre_is_map_val{params}
1034 @sa bt_component_class_sink_set_initialize_method() —
1035 Sets the initialization method of a sink component class.
1037 typedef bt_component_class_initialize_method_status
1038 (*bt_component_class_sink_initialize_method
)(
1039 bt_self_component_sink
*self_component
,
1040 bt_self_component_sink_configuration
*configuration
,
1041 const bt_value
*params
, void *initialize_method_data
);
1046 #bt_component_class_source_output_port_connected_method,
1047 #bt_component_class_filter_input_port_connected_method,
1048 #bt_component_class_filter_output_port_connected_method, and
1049 #bt_component_class_sink_input_port_connected_method.
1051 typedef enum bt_component_class_port_connected_method_status
{
1056 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1062 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1068 BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1069 } bt_component_class_port_connected_method_status
;
1073 \bt_c_src_comp "output port connected" method.
1076 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1079 @param[in] self_component
1080 Source component instance.
1081 @param[in] self_port
1082 Connected \bt_oport of \bt_p{self_component}.
1083 @param[in] other_port
1084 \bt_c_conn's other (input) port.
1086 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1088 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1090 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1093 @bt_pre_not_null{self_component}
1094 @bt_pre_not_null{self_port}
1095 @bt_pre_not_null{other_port}
1097 @sa bt_component_class_source_set_output_port_connected_method() —
1098 Sets the "output port connected" method of a source component class.
1100 typedef bt_component_class_port_connected_method_status
1101 (*bt_component_class_source_output_port_connected_method
)(
1102 bt_self_component_source
*self_component
,
1103 bt_self_component_port_output
*self_port
,
1104 const bt_port_input
*other_port
);
1108 \bt_c_flt_comp "input port connected" method.
1111 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1114 @param[in] self_component
1115 Filter component instance.
1116 @param[in] self_port
1117 Connected \bt_iport of \bt_p{self_component}.
1118 @param[in] other_port
1119 \bt_c_conn's other (output) port.
1121 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1123 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1125 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1128 @bt_pre_not_null{self_component}
1129 @bt_pre_not_null{self_port}
1130 @bt_pre_not_null{other_port}
1132 @sa bt_component_class_filter_set_input_port_connected_method() —
1133 Sets the "input port connected" method of a filter component class.
1135 typedef bt_component_class_port_connected_method_status
1136 (*bt_component_class_filter_input_port_connected_method
)(
1137 bt_self_component_filter
*self_component
,
1138 bt_self_component_port_input
*self_port
,
1139 const bt_port_output
*other_port
);
1143 \bt_c_flt_comp "output port connected" method.
1146 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1149 @param[in] self_component
1150 Filter component instance.
1151 @param[in] self_port
1152 Connected \bt_oport of \bt_p{self_component}.
1153 @param[in] other_port
1154 \bt_c_conn's other (input) port.
1156 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1158 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1160 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1163 @bt_pre_not_null{self_component}
1164 @bt_pre_not_null{self_port}
1165 @bt_pre_not_null{other_port}
1167 @sa bt_component_class_filter_set_output_port_connected_method() —
1168 Sets the "output port connected" method of a filter component class.
1170 typedef bt_component_class_port_connected_method_status
1171 (*bt_component_class_filter_output_port_connected_method
)(
1172 bt_self_component_filter
*self_component
,
1173 bt_self_component_port_output
*self_port
,
1174 const bt_port_input
*other_port
);
1178 \bt_c_sink_comp "input port connected" method.
1181 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1184 @param[in] self_component
1185 Sink component instance.
1186 @param[in] self_port
1187 Connected \bt_iport of \bt_p{self_component}.
1188 @param[in] other_port
1189 \bt_c_conn's other (output) port.
1191 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
1193 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
1195 @retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
1198 @bt_pre_not_null{self_component}
1199 @bt_pre_not_null{self_port}
1200 @bt_pre_not_null{other_port}
1202 @sa bt_component_class_sink_set_input_port_connected_method() —
1203 Sets the "input port connected" method of a sink component class.
1205 typedef bt_component_class_port_connected_method_status
1206 (*bt_component_class_sink_input_port_connected_method
)(
1207 bt_self_component_sink
*self_component
,
1208 bt_self_component_port_input
*self_port
,
1209 const bt_port_output
*other_port
);
1214 #bt_component_class_source_query_method,
1215 #bt_component_class_filter_query_method, and
1216 #bt_component_class_sink_query_method.
1218 typedef enum bt_component_class_query_method_status
{
1223 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1227 Unknown object to query.
1229 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
1235 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
1241 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1247 BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
1248 } bt_component_class_query_method_status
;
1252 \bt_c_src_comp_cls query method.
1254 See the \ref api-comp-cls-dev-meth-query "query" method.
1256 @param[in] self_component_class
1257 Source component class, as passed as the \bt_p{component_class}
1258 parameter of bt_query_executor_create() or
1259 bt_query_executor_create_with_method_data() when creating this query
1260 operation's \ref api-qexec "executor".
1261 @param[in] query_executor
1262 Private view of this query operation's executor.
1263 @param[in] object_name
1264 Name of the object to query, as passed as the \bt_p{object_name}
1265 parameter of bt_query_executor_create() or
1266 bt_query_executor_create_with_method_data() when creating this query
1267 operation's executor.
1270 Query parameters, as passed as the \bt_p{params}
1271 parameter of bt_query_executor_create() or
1272 bt_query_executor_create_with_method_data() when creating this query
1273 operation's executor.
1275 \bt_p{params} is frozen.
1277 @param[in] method_data
1278 User data for this method, as passed as the \bt_p{method_data}
1279 parameter of bt_query_executor_create_with_method_data() when
1280 creating this query operation's executor.
1282 <strong>On success</strong>, \bt_p{*result} is
1283 a \em new reference of this query operation's result.
1285 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1287 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1288 \bt_p{object_name} is unknown.
1289 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1291 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1293 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1296 @bt_pre_not_null{self_component_class}
1297 @bt_pre_not_null{query_executor}
1298 @bt_pre_not_null{object_name}
1299 @bt_pre_not_null{params}
1300 @bt_pre_not_null{result}
1303 <strong>On success</strong>, \bt_p{*result} is set.
1305 @sa bt_component_class_source_set_query_method() —
1306 Sets the query method of a source component class.
1308 typedef bt_component_class_query_method_status
1309 (*bt_component_class_source_query_method
)(
1310 bt_self_component_class_source
*self_component_class
,
1311 bt_private_query_executor
*query_executor
,
1312 const char *object_name
, const bt_value
*params
,
1313 void *method_data
, const bt_value
**result
);
1317 \bt_c_flt_comp_cls query method.
1319 See the \ref api-comp-cls-dev-meth-query "query" method.
1321 @param[in] self_component_class
1322 Filter component class, as passed as the \bt_p{component_class}
1323 parameter of bt_query_executor_create() or
1324 bt_query_executor_create_with_method_data() when creating this query
1325 operation's \ref api-qexec "executor".
1326 @param[in] query_executor
1327 Private view of this query operation's executor.
1328 @param[in] object_name
1329 Name of the object to query, as passed as the \bt_p{object_name}
1330 parameter of bt_query_executor_create() or
1331 bt_query_executor_create_with_method_data() when creating this query
1332 operation's executor.
1335 Query parameters, as passed as the \bt_p{params}
1336 parameter of bt_query_executor_create() or
1337 bt_query_executor_create_with_method_data() when creating this query
1338 operation's executor.
1340 \bt_p{params} is frozen.
1342 @param[in] method_data
1343 User data for this method, as passed as the \bt_p{method_data}
1344 parameter of bt_query_executor_create_with_method_data() when
1345 creating this query operation's executor.
1347 <strong>On success</strong>, \bt_p{*result} is
1348 a \em new reference of this query operation's result.
1350 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1352 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1353 \bt_p{object_name} is unknown.
1354 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1356 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1358 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1361 @bt_pre_not_null{self_component_class}
1362 @bt_pre_not_null{query_executor}
1363 @bt_pre_not_null{object_name}
1364 @bt_pre_not_null{params}
1365 @bt_pre_not_null{result}
1368 <strong>On success</strong>, \bt_p{*result} is set.
1370 @sa bt_component_class_filter_set_query_method() —
1371 Sets the query method of a filter component class.
1373 typedef bt_component_class_query_method_status
1374 (*bt_component_class_filter_query_method
)(
1375 bt_self_component_class_filter
*self_component_class
,
1376 bt_private_query_executor
*query_executor
,
1377 const char *object_name
, const bt_value
*params
,
1378 void *method_data
, const bt_value
**result
);
1382 \bt_c_sink_comp_cls query method.
1384 See the \ref api-comp-cls-dev-meth-query "query" method.
1386 @param[in] self_component_class
1387 Sink component class, as passed as the \bt_p{component_class}
1388 parameter of bt_query_executor_create() or
1389 bt_query_executor_create_with_method_data() when creating this query
1390 operation's \ref api-qexec "executor".
1391 @param[in] query_executor
1392 Private view of this query operation's executor.
1393 @param[in] object_name
1394 Name of the object to query, as passed as the \bt_p{object_name}
1395 parameter of bt_query_executor_create() or
1396 bt_query_executor_create_with_method_data() when creating this query
1397 operation's executor.
1400 Query parameters, as passed as the \bt_p{params}
1401 parameter of bt_query_executor_create() or
1402 bt_query_executor_create_with_method_data() when creating this query
1403 operation's executor.
1405 \bt_p{params} is frozen.
1407 @param[in] method_data
1408 User data for this method, as passed as the \bt_p{method_data}
1409 parameter of bt_query_executor_create_with_method_data() when
1410 creating this query operation's executor.
1412 <strong>On success</strong>, \bt_p{*result} is
1413 a \em new reference of this query operation's result.
1415 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
1417 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
1418 \bt_p{object_name} is unknown.
1419 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
1421 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
1423 @retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
1426 @bt_pre_not_null{self_component_class}
1427 @bt_pre_not_null{query_executor}
1428 @bt_pre_not_null{object_name}
1429 @bt_pre_not_null{params}
1430 @bt_pre_not_null{result}
1433 <strong>On success</strong>, \bt_p{*result} is set.
1435 @sa bt_component_class_sink_set_query_method() —
1436 Sets the query method of a sink component class.
1438 typedef bt_component_class_query_method_status
1439 (*bt_component_class_sink_query_method
)(
1440 bt_self_component_class_sink
*self_component_class
,
1441 bt_private_query_executor
*query_executor
,
1442 const char *object_name
, const bt_value
*params
,
1443 void *method_data
, const bt_value
**result
);
1454 Creates a \bt_src_comp_cls named \bt_p{name} and having the
1455 \bt_msg_iter_cls \bt_p{message_iterator_class}.
1457 On success, the returned source component class has the following
1465 <td>\ref api-comp-cls-prop-name "Name"
1468 <td>\ref api-comp-cls-prop-descr "Description"
1471 <td>\ref api-comp-cls-prop-help "Help text"
1476 Name of the source component class to create (copied).
1477 @param[in] message_iterator_class
1478 Message iterator class of the source component class to create.
1481 New source component class reference, or \c NULL on memory error.
1483 @bt_pre_not_null{name}
1484 @bt_pre_not_null{message_iterator_class}
1486 @bt_post_success_frozen{message_iterator_class}
1488 @sa bt_message_iterator_class_create() —
1489 Creates a message iterator class.
1492 bt_component_class_source
*bt_component_class_source_create(
1494 bt_message_iterator_class
*message_iterator_class
);
1498 Creates a \bt_flt_comp_cls named \bt_p{name} and having the
1499 \bt_msg_iter_cls \bt_p{message_iterator_class}.
1501 On success, the returned filter component class has the following
1509 <td>\ref api-comp-cls-prop-name "Name"
1512 <td>\ref api-comp-cls-prop-descr "Description"
1515 <td>\ref api-comp-cls-prop-help "Help text"
1520 Name of the filter component class to create (copied).
1521 @param[in] message_iterator_class
1522 Message iterator class of the filter component class to create.
1525 New filter component class reference, or \c NULL on memory error.
1527 @bt_pre_not_null{name}
1528 @bt_pre_not_null{message_iterator_class}
1530 @bt_post_success_frozen{message_iterator_class}
1532 @sa bt_message_iterator_class_create() —
1533 Creates a message iterator class.
1536 bt_component_class_filter
*bt_component_class_filter_create(
1538 bt_message_iterator_class
*message_iterator_class
);
1542 Creates a \bt_sink_comp_cls named \bt_p{name} and having the
1543 \ref api-comp-cls-dev-meth-consume "consuming method"
1544 \bt_p{consume_method}.
1546 On success, the returned sink component class has the following
1554 <td>\ref api-comp-cls-prop-name "Name"
1557 <td>\ref api-comp-cls-prop-descr "Description"
1560 <td>\ref api-comp-cls-prop-help "Help text"
1565 Name of the sink component class to create (copied).
1566 @param[in] consume_method
1567 Consuming method of the sink component class to create.
1570 New sink component class reference, or \c NULL on memory error.
1572 @bt_pre_not_null{name}
1573 @bt_pre_not_null{consume_method}
1576 bt_component_class_sink
*bt_component_class_sink_create(
1578 bt_component_class_sink_consume_method consume_method
);
1583 @name Common properties
1589 Status codes for bt_component_class_set_description().
1591 typedef enum bt_component_class_set_description_status
{
1596 BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1602 BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1603 } bt_component_class_set_description_status
;
1607 Sets the description of the component class \bt_p{component_class}
1608 to a copy of \bt_p{description}.
1610 See the \ref api-comp-cls-prop-descr "description" property.
1612 @param[in] component_class
1613 Component class of which to set the description to
1615 @param[in] description
1616 New description of \bt_p{component_class} (copied).
1618 @retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK
1620 @retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
1623 @bt_pre_not_null{component_class}
1624 @bt_pre_hot{component_class}
1625 @bt_pre_not_null{description}
1627 @sa bt_component_class_get_description() —
1628 Returns the description of a component class.
1630 extern bt_component_class_set_description_status
1631 bt_component_class_set_description(bt_component_class
*component_class
,
1632 const char *description
);
1636 Status codes for bt_component_class_set_help().
1638 typedef enum bt_component_class_set_help_status
{
1643 BT_COMPONENT_CLASS_SET_HELP_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1649 BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1650 } bt_component_class_set_help_status
;
1654 Sets the help text of the component class \bt_p{component_class}
1655 to a copy of \bt_p{help_text}.
1657 See the \ref api-comp-cls-prop-help "help text" property.
1659 @param[in] component_class
1660 Component class of which to set the help text to
1662 @param[in] help_text
1663 New help text of \bt_p{component_class} (copied).
1665 @retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_OK
1667 @retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR
1670 @bt_pre_not_null{component_class}
1671 @bt_pre_hot{component_class}
1672 @bt_pre_not_null{help_text}
1674 @sa bt_component_class_get_help() —
1675 Returns the help text of a component class.
1677 extern bt_component_class_set_help_status
bt_component_class_set_help(
1678 bt_component_class
*component_class
,
1679 const char *help_text
);
1684 @name Method setting
1691 <code>bt_component_class_*_set_*_method()</code> functions.
1693 typedef enum bt_component_class_set_method_status
{
1698 BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1699 } bt_component_class_set_method_status
;
1703 Sets the optional finalization method of the \bt_src_comp_cls
1704 \bt_p{component_class} to \bt_p{method}.
1706 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1708 @param[in] component_class
1709 Source component class of which to set the finalization method to
1712 New finalization method of \bt_p{component_class}.
1714 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1717 @bt_pre_not_null{component_class}
1718 @bt_pre_hot{component_class}
1719 @bt_pre_not_null{method}
1721 extern bt_component_class_set_method_status
1722 bt_component_class_source_set_finalize_method(
1723 bt_component_class_source
*component_class
,
1724 bt_component_class_source_finalize_method method
);
1728 Sets the optional finalization method of the \bt_flt_comp_cls
1729 \bt_p{component_class} to \bt_p{method}.
1731 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1733 @param[in] component_class
1734 Filter component class of which to set the finalization method to
1737 New finalization method of \bt_p{component_class}.
1739 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1742 @bt_pre_not_null{component_class}
1743 @bt_pre_hot{component_class}
1744 @bt_pre_not_null{method}
1746 extern bt_component_class_set_method_status
1747 bt_component_class_filter_set_finalize_method(
1748 bt_component_class_filter
*component_class
,
1749 bt_component_class_filter_finalize_method method
);
1753 Sets the optional finalization method of the \bt_sink_comp_cls
1754 \bt_p{component_class} to \bt_p{method}.
1756 See the \ref api-comp-cls-dev-meth-fini "finalize" method.
1758 @param[in] component_class
1759 Sink component class of which to set the finalization method to
1762 New finalization method of \bt_p{component_class}.
1764 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1767 @bt_pre_not_null{component_class}
1768 @bt_pre_hot{component_class}
1769 @bt_pre_not_null{method}
1772 bt_component_class_set_method_status
1773 bt_component_class_sink_set_finalize_method(
1774 bt_component_class_sink
*component_class
,
1775 bt_component_class_sink_finalize_method method
);
1779 Sets the \"get supported \bt_mip versions\" method of the
1780 \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
1782 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1785 @param[in] component_class
1786 Source component class of which to set the "get supported MIP
1787 versions" method to \bt_p{method}.
1789 New "get supported MIP versions" method of \bt_p{component_class}.
1791 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1794 @bt_pre_not_null{component_class}
1795 @bt_pre_hot{component_class}
1796 @bt_pre_not_null{method}
1798 extern bt_component_class_set_method_status
1799 bt_component_class_source_set_get_supported_mip_versions_method(
1800 bt_component_class_source
*component_class
,
1801 bt_component_class_source_get_supported_mip_versions_method method
);
1805 Sets the \"get supported \bt_mip versions\" method of the
1806 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
1808 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1811 @param[in] component_class
1812 Filter component class of which to set the "get supported MIP
1813 versions" method to \bt_p{method}.
1815 New "get supported MIP versions" method of \bt_p{component_class}.
1817 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1820 @bt_pre_not_null{component_class}
1821 @bt_pre_hot{component_class}
1822 @bt_pre_not_null{method}
1824 extern bt_component_class_set_method_status
1825 bt_component_class_filter_set_get_supported_mip_versions_method(
1826 bt_component_class_filter
*component_class
,
1827 bt_component_class_filter_get_supported_mip_versions_method method
);
1831 Sets the \"get supported \bt_mip versions\" method of the
1832 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
1834 See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
1837 @param[in] component_class
1838 Sink component class of which to set the "get supported MIP
1839 versions" method to \bt_p{method}.
1841 New "get supported MIP versions" method of \bt_p{component_class}.
1843 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1846 @bt_pre_not_null{component_class}
1847 @bt_pre_hot{component_class}
1848 @bt_pre_not_null{method}
1850 extern bt_component_class_set_method_status
1851 bt_component_class_sink_set_get_supported_mip_versions_method(
1852 bt_component_class_sink
*component_class
,
1853 bt_component_class_sink_get_supported_mip_versions_method method
);
1857 Sets the "graph is configured" method of the
1858 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
1861 \ref api-comp-cls-dev-meth-graph-configured "graph is configured"
1864 @param[in] component_class
1865 Sink component class of which to set the "graph is configured"
1866 method to \bt_p{method}.
1868 New "graph is configured" method of \bt_p{component_class}.
1870 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1873 @bt_pre_not_null{component_class}
1874 @bt_pre_hot{component_class}
1875 @bt_pre_not_null{method}
1878 bt_component_class_set_method_status
1879 bt_component_class_sink_set_graph_is_configured_method(
1880 bt_component_class_sink
*component_class
,
1881 bt_component_class_sink_graph_is_configured_method method
);
1885 Sets the optional initialization method of the \bt_src_comp_cls
1886 \bt_p{component_class} to \bt_p{method}.
1888 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1890 @param[in] component_class
1891 Source component class of which to set the initialization method to
1894 New initialization method of \bt_p{component_class}.
1896 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1899 @bt_pre_not_null{component_class}
1900 @bt_pre_hot{component_class}
1901 @bt_pre_not_null{method}
1903 extern bt_component_class_set_method_status
1904 bt_component_class_source_set_initialize_method(
1905 bt_component_class_source
*component_class
,
1906 bt_component_class_source_initialize_method method
);
1910 Sets the optional initialization method of the \bt_flt_comp_cls
1911 \bt_p{component_class} to \bt_p{method}.
1913 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1915 @param[in] component_class
1916 Filter component class of which to set the initialization method to
1919 New initialization method of \bt_p{component_class}.
1921 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1924 @bt_pre_not_null{component_class}
1925 @bt_pre_hot{component_class}
1926 @bt_pre_not_null{method}
1928 extern bt_component_class_set_method_status
1929 bt_component_class_filter_set_initialize_method(
1930 bt_component_class_filter
*component_class
,
1931 bt_component_class_filter_initialize_method method
);
1935 Sets the optional initialization method of the \bt_sink_comp_cls
1936 \bt_p{component_class} to \bt_p{method}.
1938 See the \ref api-comp-cls-dev-meth-init "initialize" method.
1940 @param[in] component_class
1941 Sink component class of which to set the initialization method to
1944 New initialization method of \bt_p{component_class}.
1946 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1949 @bt_pre_not_null{component_class}
1950 @bt_pre_hot{component_class}
1951 @bt_pre_not_null{method}
1954 bt_component_class_set_method_status
1955 bt_component_class_sink_set_initialize_method(
1956 bt_component_class_sink
*component_class
,
1957 bt_component_class_sink_initialize_method method
);
1961 Sets the optional "output port connected" method of the
1962 \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
1965 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
1968 @param[in] component_class
1969 Source component class of which to set the "output port connected"
1970 method to \bt_p{method}.
1972 New "output port connected" method of \bt_p{component_class}.
1974 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
1977 @bt_pre_not_null{component_class}
1978 @bt_pre_hot{component_class}
1979 @bt_pre_not_null{method}
1981 extern bt_component_class_set_method_status
1982 bt_component_class_source_set_output_port_connected_method(
1983 bt_component_class_source
*component_class
,
1984 bt_component_class_source_output_port_connected_method method
);
1988 Sets the optional "input port connected" method of the
1989 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
1992 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
1995 @param[in] component_class
1996 Filter component class of which to set the "input port connected"
1997 method to \bt_p{method}.
1999 New "input port connected" method of \bt_p{component_class}.
2001 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2004 @bt_pre_not_null{component_class}
2005 @bt_pre_hot{component_class}
2006 @bt_pre_not_null{method}
2008 extern bt_component_class_set_method_status
2009 bt_component_class_filter_set_input_port_connected_method(
2010 bt_component_class_filter
*component_class
,
2011 bt_component_class_filter_input_port_connected_method method
);
2015 Sets the optional "output port connected" method of the
2016 \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
2019 \ref api-comp-cls-dev-meth-oport-connected "output port connected"
2022 @param[in] component_class
2023 Filter component class of which to set the "output port connected"
2024 method to \bt_p{method}.
2026 New "output port connected" method of \bt_p{component_class}.
2028 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2031 @bt_pre_not_null{component_class}
2032 @bt_pre_hot{component_class}
2033 @bt_pre_not_null{method}
2035 extern bt_component_class_set_method_status
2036 bt_component_class_filter_set_output_port_connected_method(
2037 bt_component_class_filter
*component_class
,
2038 bt_component_class_filter_output_port_connected_method method
);
2042 Sets the optional "input port connected" method of the
2043 \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
2046 \ref api-comp-cls-dev-meth-iport-connected "input port connected"
2049 @param[in] component_class
2050 Sink component class of which to set the "input port connected"
2051 method to \bt_p{method}.
2053 New "input port connected" method of \bt_p{component_class}.
2055 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2058 @bt_pre_not_null{component_class}
2059 @bt_pre_hot{component_class}
2060 @bt_pre_not_null{method}
2063 bt_component_class_set_method_status
2064 bt_component_class_sink_set_input_port_connected_method(
2065 bt_component_class_sink
*component_class
,
2066 bt_component_class_sink_input_port_connected_method method
);
2070 Sets the optional query method of the \bt_src_comp_cls
2071 \bt_p{component_class} to \bt_p{method}.
2073 See the \ref api-comp-cls-dev-meth-query "query" method.
2075 @param[in] component_class
2076 Source component class of which to set the query method to
2079 New query method of \bt_p{component_class}.
2081 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2084 @bt_pre_not_null{component_class}
2085 @bt_pre_hot{component_class}
2086 @bt_pre_not_null{method}
2088 extern bt_component_class_set_method_status
2089 bt_component_class_source_set_query_method(
2090 bt_component_class_source
*component_class
,
2091 bt_component_class_source_query_method method
);
2095 Sets the optional query method of the \bt_flt_comp_cls
2096 \bt_p{component_class} to \bt_p{method}.
2098 See the \ref api-comp-cls-dev-meth-query "query" method.
2100 @param[in] component_class
2101 Filter component class of which to set the query method to
2104 New query method of \bt_p{component_class}.
2106 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2109 @bt_pre_not_null{component_class}
2110 @bt_pre_hot{component_class}
2111 @bt_pre_not_null{method}
2113 extern bt_component_class_set_method_status
2114 bt_component_class_filter_set_query_method(
2115 bt_component_class_filter
*component_class
,
2116 bt_component_class_filter_query_method method
);
2120 Sets the optional query method of the \bt_sink_comp_cls
2121 \bt_p{component_class} to \bt_p{method}.
2123 See the \ref api-comp-cls-dev-meth-query "query" method.
2125 @param[in] component_class
2126 Sink component class of which to set the query method to
2129 New query method of \bt_p{component_class}.
2131 @retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
2134 @bt_pre_not_null{component_class}
2135 @bt_pre_hot{component_class}
2136 @bt_pre_not_null{method}
2139 bt_component_class_set_method_status
2140 bt_component_class_sink_set_query_method(
2141 bt_component_class_sink
*component_class
,
2142 bt_component_class_sink_query_method method
);
2153 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
2154 \bt_p{component_class} to the common #bt_component_class type.
2156 @param[in] component_class
2158 Source component class to upcast.
2164 \bt_p{component_class} as a common component class.
2167 bt_component_class
*bt_component_class_source_as_component_class(
2168 bt_component_class_source
*component_class
)
2170 return __BT_UPCAST(bt_component_class
, component_class
);
2175 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
2176 \bt_p{component_class} to the common #bt_component_class type.
2178 @param[in] component_class
2180 Filter component class to upcast.
2186 \bt_p{component_class} as a common component class.
2189 bt_component_class
*bt_component_class_filter_as_component_class(
2190 bt_component_class_filter
*component_class
)
2192 return __BT_UPCAST(bt_component_class
, component_class
);
2197 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
2198 \bt_p{component_class} to the common #bt_component_class type.
2200 @param[in] component_class
2202 Sink component class to upcast.
2208 \bt_p{component_class} as a common component class.
2211 bt_component_class
*bt_component_class_sink_as_component_class(
2212 bt_component_class_sink
*component_class
)
2214 return __BT_UPCAST(bt_component_class
, component_class
);
2225 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H */