lib: rename include dir to babeltrace2 Rename the include dir to be co-installable with bt1. Change-Id: Icb9a048988544eaca7054648b9c7a9e76d70b9db Signed-off-by: Michael Jeanson <mjeanson@efficios.com> Reviewed-on: https://review.lttng.org/c/babeltrace/+/1405 Tested-by: jenkins Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
CTF writer: use own `bt_ctf_object` and `bt_ctf_value` internal APIs Removing CTF writer's implementation's dependency on `bt_object` and `bt_value` makes it even more independent so as to be free to change the `bt_object` and `bt_value` APIs without having to update the CTF writer part. Both APIs are not public as of this patch, so I'm hiding the public CTF writer functions to get a trace's environment field (and their tests), which is a `bt_ctf_value` object. This is not breaking backward compatibility with Babeltrace 1.5. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
lib: graph: add "self" and some "private" APIs The main purpose of this patch is to create different "views" of the same graph objects. The terms are as such: Public API: You can only read properties of the object. Example: bt_graph_is_canceled(). Private API: You can create the object and set properties. Example: bt_private_graph_create(). Self API: You conceptually inherit this object. Example: bt_self_component_set_data(). This means that component user method now accepts a "self component", on which: * You can set and get user data (bt_self_component_set_data() and bt_self_component_get_data()). * You can add ports (for example, bt_self_component_source_add_output_port()). * You can borrow "self component ports", on which you can get user data (bt_self_component_port_get_data()) that you set previously with a port adding function. A notification iterator method now accepts a "self notification iterator", on which: * You can set and get user data (bt_self_notification_iterator_set_data() and bt_self_notification_iterator_get_data()). * You can borrow your "self component" (bt_self_notification_iterator_borrow_component()) or "self component output port" (bt_self_notification_iterator_borrow_port()). Also, you now use the private component class API to create component classes and set optional methods, a description, and the rest. Also in this patch: * Component class and component APIs are split into source, filter, and sink parts. This makes everything more type safe considering that: * We don't need any polymorphism like we do, for example, for field classes, for component classes and components: you always know, contextually, with which type you're dealing. * We don't need to have collections of components or component classes of different types: we can just use three collections each time. This means that the private graph API, for example, now has the three distinct bt_private_graph_add_source_component(), bt_private_graph_add_filter_component(), and bt_private_graph_add_sink_component(), each of them accepting the appropriate component class type and returning the corresponding component type. No function exists to borrow a source component's input port or a sink component's output port. * The port API is split into input and output parts, with the new `struct bt_port_in` and `struct bt_port_out` types. An interesting consequence is that, as a component class developer, there are different methods for input and output ports, so that a fitler component class, for example, can have both an "input port connected" and an "output port connected". The `flt.utils.muxer` component class is an example which takes advantage of this, not having to check the port's type in its "input port connected" method now. * Functions to go from one type to another (private to public, self to public, input port to port, and so on) are now `static inline` to avoid any performance hit. Those functions are now universally named bt_X_borrow_Y(), where `X` is the API's prefix (for example, `private_component_class`) and `Y` is the transformed type name (for example, `component_class`). * The query executor API is split into private (create, query, cancel) and public (is canceled?) parts. A user's query method accepts a "self component class" of the appropriate type. * "Private connection private notification iterator" is removed in favor of "self component input port notification iterator": you need to call bt_self_component_port_input_notification_iterator_create() with a self component input port (which you can only borrow from your own self component). Because of this, `enum bt_connection_status` is removed because it's not needed anymore. * `enum bt_component_status` is removed because it's not needed anymore. Most statuses are moved to `enum bt_self_component_status` (what a component class method returns). * `bt_output_port_notification_iterator` is renamed to `bt_port_output_notification_iterator` to be consistent with `bt_self_component_port_input_notification_iterator`. * Graph and plugin API status values are standardized. * Precondition assertion macros are used to validate preconditions in developer mode across the whole graph and plugin APIs. Consequences: * bt_plugin_get_version() returns `enum bt_property_availability` instead of `enum bt_plugin_status`. * Functions which return a count return `uint64_t` instead of `int64_t`. * Status ending with `_INVALID` are removed (not needed anymore). * Types ending with `_UNKNOWN` are removed (not needed anymore). * All "getting" functions in the graph/plugin APIs are removed in favor of "borrowing" functions. Interesting changes needed to be made to bt_connection_end() and remove_port_by_index() to support this. * bt_plugin_find_component_class() is removed. Let's not encourage this because it creates a plugin object each time, whereas the recommended approach is to create a plugin first (with bt_plugin_find() for example), and then borrow the required component classes. * Graph API: when an object's member is destroyed, internally, its pointer is set to `NULL` immediately. This makes it possible to log partial objects during destruction while keeping Valgrind's memcheck happy. * Generic logging is replaced by library logging in the graph and plugin API implementations. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Rename: bt_put(), bt_get() -> bt_object_put_ref(), bt_object_get_ref() Because those function apply to any (shared) Babeltrace object, let's put them under the `bt_object` namespace and make it clear what we're putting and getting. Also, reference counting macros are renamed: * BT_PUT() -> BT_OBJECT_PUT_REF_AND_RESET() * BT_MOVE() -> BT_OBJECT_MOVE_REF() Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Split CTF IR and CTF writer APIs and implementations This patch splits the CTF IR and CTF writer APIs, previously implemented at a single place with aliases to make CTF writer functions and types be synonymous to CTF IR ones, with as much common code as possible for both APIs. The goal of this change is to be able to modify one API/implementation without disturbing the other, optimization being one major use case. Common API ========== Most of the CTF IR and CTF writer functions perform the exact same tasks. Some functions, however, have minor differences. For example, bt_trace_add_stream_class() tries to automatically map specific integer field types to the stream class's CTF writer clock's class if the trace object was created by a CTF writer object. To keep as much common code as possible, `struct bt_*_common` types and bt_*_common() functions are introduced. A common structure contains the common data needed for both CTF IR and CTF writer, while actual CTF IR/writer structures "inherit" this one. For example: struct bt_stream_common { struct bt_object base; int64_t id; struct bt_stream_class_common *stream_class; GString *name; GArray *destroy_listeners; }; struct bt_stream { struct bt_stream_common common; }; struct bt_ctf_stream { struct bt_stream_common common; struct bt_ctf_field *packet_header; struct bt_ctf_field *packet_context; GPtrArray *events; struct bt_ctf_stream_pos pos; unsigned int flushed_packet_count; uint64_t discarded_events; uint64_t size; uint64_t last_ts_end; }; All bt_stream_common_*() functions require a pointer to `struct bt_stream_common`. You can use the BT_TO_COMMON() and BT_FROM_COMMON() macros of `include/babeltrace/ctf-ir/utils-internal.h` to statically cast the pointers in each direction. BT_TO_COMMON() needs the concrete (non-common) structure to have a common structure member named `common`. A concrete implementation is responsible for the allocation and deallocation of its objects, but the common API provides internal functions to initialize and finalize the common parts. Examples are bt_event_common_initialize(), bt_event_class_common_finalize(), and bt_field_type_common_floating_point_initialize(). Those initialization functions take a `release_func` parameter which is the concrete object destruction function. The latter is responsible for finalizing the specific part, calling bt_*_common_finalize() to finalize the common part, and deallocating the object. Most of the concrete functions look like this: struct bt_field_type *bt_event_class_get_payload_field_type( struct bt_event_class *event_class) { return BT_FROM_COMMON(bt_event_class_common_get_payload_field_type( BT_TO_COMMON(event_class))); } Some common functions are more complicated and can be considered template methods: they take various options and callback functions to be called at specific places within the procedure. bt_event_common_initialize() and bt_trace_common_add_stream_class() are obvious examples. The cases of field types and fields are special because those structures already use inheritance: an integer field type structure inherits the field type structure. In order for all the APIs to be able to statically cast to the appropriate types, here's how a concrete field type is arranged: +------------------------------------+ | Common field type | <- bt_field_type_common_*() +------------------------------------+ | Concrete common field type (union) | <- bt_(ctf_)field_type_*() +------------------------------------+ | Common specific field type | <- bt_field_type_common_integer_*() +------------------------------------+ | Specific field type | <- bt_(ctf_)field_type_integer_*() +------------------------------------+ The four parts are at a fixed offset. Field objects follow the same structure. As of this patch, `struct bt_field_type`, `struct bt_ctf_field_type`, `struct bt_field`, and `struct bt_ctf_field` are only forward-declared and always `(void *)` casted to and from the appropriate common type for public APIs because they don't add specific data. For example: int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *ft, unsigned int alignment) { return bt_field_type_common_set_alignment((void *) ft, alignment); } Also of interest is `struct bt_ctf_clock_class` which includes `struct bt_clock_class`: there's no `struct bt_clock_class_common` because as of this patch we don't expect a CTF IR clock class property to be absent from a CTF writer clock class. As of this patch, the common API and implementation are in the same source and header files as CTF IR. Fast path common functions (most getters and almost everything related to fields and events) are implemented in internal header files as `static inline` functions. Logging ======= BT_LIB_LOG(), and consequently BT_ASSERT_PRE() and its variants, is modified with an added prefix character to distinguish a CTF IR object from a CTF writer object and from a common object. The prefix character is inserted just before the format specifier: `_` means a common object (underscore as in low as in base), and `w` means a CTF writer object. No prefix means a CTF IR or other object (graph objects, value objects, etc.). Using `%!+_t` with a CTF IR trace object, for example, is correct because it inherits the common part, but using `%!+t` with a common trace object could eventually lead to bad data or to a segmentation fault. See the updated description in `include/babeltrace/lib-logging-internal.h` for more details. Testing ======= Some tests in `tests/lib` are modified because they used a mix of CTF IR and CTF writer APIs. Also there is a new precondition that a CTF IR event class must be part of a trace before you can create an event from it (the CTF writer API does not have this restriction for backward compatibility reasons): this guarantee could make things easier in the future and it is acceptable for a CTF IR user. Some CTF writer tests are removed because they were in fact CTF IR tests. In the future we should create specific CTF IR tests and reuse the removed tests. Limitations =========== This patch does not address, and reserves for future work: * Python bindings * Python bindings tests * `src.ctf.lttng-live`, `sink.ctf.fs`, `flt.utils.trimmer`, `flt.lttng-utils.debug-info`, and `src.text.dmesg` component classes Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Rename bt_ctf_X -> bt_X, maintain backward compat. for pre-2.0 CTF writer This patch replaces the `bt_ctf_` prefix with `bt_` for all the functions, types, and enumerations. It also replaces the `BT_CTF_` prefix with `BT_` for all the preprocessor definitions and enumerators. Since there is only one IR as of Babeltrace 2, there is no need for this superfluous prefix: there's no confusion without it, and it might even be more straightforward for the newcomer to see `bt_trace` instead of `bt_ctf_trace`, for example. Backward compatibility is maintained with the help of specific preprocessor definitions placed in each relevant public header file to create aliases for legacy function names, type names, enumerator names, and preprocessor definition names. Because Babeltrace 2 asks current applications to be rebuilt anyway (soname is bumped), it is okay to lose some symbol names as long as the API is equivalent. The only possible issue that I can see is if an application uses a new API name as a variable name, for example: struct bt_ctf_trace bt_ctf_trace; struct something_else bt_trace; This is an error after this patch is applied because, after the preprocessor pass, it is the equivalent of: struct bt_trace bt_trace; struct something_else bt_trace; because of (include/babeltrace/ctf-ir/trace.h): #define bt_ctf_trace bt_trace which affects both the type name and the variable name. This should not be a problem in most cases, and it is easy to fix otherwise. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
CTF writer: Add function to add an integer environment field value From the Python API, it's only possible to set an environment field value as a string (whatever you pass, it gets stringified). This patch adds a function to the CTF writer to allow setting an integer (int64_t) environment field, and then exposes it in the Python interface. The Python method Writer.add_environment_field now uses the type of the passed value to determine which underlying C function to call (string or integer). Any other type is rejected. This causes a behavior change, since passing an integer value to add_environment_field used to produce a string version of the value, whereas it will now produce an integer version. However, I think it will now behave more closely to the expectation of a lambda user. Example: w.add_environment_field("foo", 2) Result before: env { foo = "2"; }; Result after: env { foo = 2; }; Signed-off-by: Simon Marchi <simon.marchi@polymtl.ca> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
ir: consolidate reference counting functions This patch adds the bt_ctf_get() and bt_ctf_put() functions which resp. get and put references of any CTF IR object. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Fix: Field types native byte order refers to the trace Following a misunderstanding of the CTF specification, the native byte order was implemented as meaning the host's endianness. It should refer to the Trace's endianness. This modification ensures that stream classes, event classes and field types correctly inherit the trace's endianness when "native" is used. Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Add public CTF Writer API headers Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Reviewed-by: Christian Babeux <christian.babeux@efficios.com> Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>