babeltrace.git
7 years agoAdd graph topology tests
Philippe Proulx [Tue, 28 Mar 2017 16:01:49 +0000 (12:01 -0400)] 
Add graph topology tests

The new tests verify that the component methods and graph listeners are
called by the graph framework in reaction to specific events with the
expected parameters and in the expected order.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoCall a single "ports connected/disconnected" graph listener instead of two
Philippe Proulx [Wed, 29 Mar 2017 15:55:11 +0000 (11:55 -0400)] 
Call a single "ports connected/disconnected" graph listener instead of two

It is reasonable to believe that a user implementing a
"ports connected" or "ports disconnected" graph listener wants both
the upstream and downstream ports, instead of getting called two times
with one and the other.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: call acting component's "port disconnected" method too
Philippe Proulx [Wed, 29 Mar 2017 06:27:53 +0000 (02:27 -0400)] 
Fix: call acting component's "port disconnected" method too

When a port is disconnected, call both upstream and downstream
components. It's okay to get notified as a component even if you
caused this notification.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt_graph_connect() -> bt_graph_connect_ports()
Philippe Proulx [Wed, 29 Mar 2017 02:31:45 +0000 (22:31 -0400)] 
bt_graph_connect() -> bt_graph_connect_ports()

This is more explicit.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRename <babeltrace/component/...> -> <babeltrace/graph/...>
Philippe Proulx [Wed, 29 Mar 2017 02:04:59 +0000 (22:04 -0400)] 
Rename <babeltrace/component/...> -> <babeltrace/graph/...>

Also put all the graph-related header files directly in this directory,
not in subdirectories.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoUpdate notification iterator's "init" function signature
Philippe Proulx [Wed, 29 Mar 2017 00:15:40 +0000 (20:15 -0400)] 
Update notification iterator's "init" function signature

As per this project's standard way of calling methods, the self object
should always be the first parameter. In the cast of
bt_component_class_notification_iterator_init_method, we don't need to
explicitly pass the bt_private_component object since you can get it
from the notification iterator with
bt_private_notification_iterator_get_private_component().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRemove the need to implement the notification iterator's "get" method
Philippe Proulx [Tue, 28 Mar 2017 23:57:34 +0000 (19:57 -0400)] 
Remove the need to implement the notification iterator's "get" method

The order of a notification iterator's "get" method is to return the
"current notification", set by the last "next" method call. Since all
source and filter plugins do the same in their "get" method, let's
remove the need to implement it at all.

The bt_notification_iterator_next() and
bt_notification_iterator_get_notification() public functions are still
available for the iterator's user, but the iterator object itself keeps
the current notification returned by the last "next" method call.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years ago"destroy" method -> "finalize" method
Philippe Proulx [Tue, 28 Mar 2017 23:24:01 +0000 (19:24 -0400)] 
"destroy" method -> "finalize" method

"Finalize" is more symmetric with "initialize" ("init"), and "destroy"
implies that the object is completely destroyed, which might not be the
case eventually.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAccept port connection method: take other port as parameter
Philippe Proulx [Tue, 28 Mar 2017 23:09:31 +0000 (19:09 -0400)] 
Accept port connection method: take other port as parameter

This can be useful, as we already have it at this point when calling the
method, to inspect the other port and its component.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoVisibility: split graph API into public and private interfaces
Philippe Proulx [Tue, 28 Mar 2017 18:14:42 +0000 (14:14 -0400)] 
Visibility: split graph API into public and private interfaces

The goal here is to avoid that a component or a graph user calls methods
that do not logically apply to itself, but should according to the API's
intention. For example, a component should not be able to remove the
ports of another component, and a graph user should not be able to
create a notification iterator directly.

Therefore the existing bt_component, bt_port, bt_connection, and
bt_notification_iterator objects are considered "public": any user can
call their API.

The user-defined methods (callbacks) now accept private versions of
those objects:

* bt_private_component
* bt_private_port
* bt_private_connection
* bt_private_notification_iterator

This ensures that only the user which is called back with those private
objects can call specific, private methods, which start with the
`bt_private_` prefix.

For example, any user can get a sink component's input port by name with
bt_component_sink_get_input_port(). This function accepts a bt_component
object parameter and returns a bt_port object. However, only the called
back user can get its private version of the port with the equivalent
bt_private_component_sink_get_input_private_port(). This function
accepts a bt_private_component object parameter and returns a
bt_private_port object. The private port API has the
bt_private_port_remove_from_component() function: thus only the owner
component of a port can remove it from itself.

Each private API has a bt_OBJ_from_private_OBJ() function which
returns a _new reference_ to the equivalent public object of a private
object to be able to call public functions.

With all this, if a user calls a private function with a public object,
the compiler emits a warning similar to:

    warning: assignment from incompatible pointer type

With GCC and Clang, you can make this warning an error with:

    -Werror=incompatible-pointer-types

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd graph event listeners
Philippe Proulx [Sat, 25 Mar 2017 05:27:24 +0000 (01:27 -0400)] 
Add graph event listeners

With this patch you can add event listeners to a graph:

* Port added to a graph's component. Note that this is only called when
  the component belongs to a graph. It is not called for existing ports
  when the component becomes part of a graph (with bt_graph_connect()).
* Port removed from a graph's component.
* Graph component's port connected.
* Graph component's port disconnected.

All those listeners return `void` because they cannot "fail". In the
worst case they should just abort. Another way would be to set a flag
at some place and read it once you have called bt_graph_run() or
bt_graph_consume().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAllow a component to remove a port and any user to disconnect one
Philippe Proulx [Thu, 23 Mar 2017 21:12:40 +0000 (17:12 -0400)] 
Allow a component to remove a port and any user to disconnect one

This patch allows a component to remove one of its own ports at anytime.
Removing a connected port has the side effect of also disconnecting it.
This patch also allows any user (graph's creator or component, for
example) to disconnect a component's port.

A component can remove one of its port with
bt_port_remove_from_component(). This function only needs the port
object because the removing component is its parent. Note that this
function does not check in any way that the removing component is the
parent of the port to remove from its parent, so any component or even
the graph's user could remove any component's port. This is prohibited
by the API's contract, but it's not enforced. It should be documented
accordingly.

You can disconnect a port with bt_port_disconnect(). When you call this
function, both upstream and downstream ports of the port's current
connection are disconnected, that is, they become available again for
bt_graph_connect().

When a port is disconnected with bt_port_remove_from_component(), the
parent component's of the connection's other port is called back ("port
disconnected" method) to notify it that one of its ports lost a
connection. Then the component is free to keep this port as an available
port, or to remove it too.

When a port is disconnected with bt_port_disconnect(), both
components are called back ("port disconnected method").

The existing iterators on a connection which is dropped (ports are
disconnected) are left as is: they still work.

The "new connection" optional method is renamed to "accept port
connection": this method can return
BT_COMPONENT_STATUS_REFUSE_PORT_CONNECTION to explicitly refuse the
new connection.

With this patch, only one connection per port is allowed. This
simplifies the model. One-to-many connections can be replaced with
a "tee" filter. Thus this patch removes the concept of a maximum number
of connections per port (it's always one).

With this patch, a component can add a new port at anytime, not just
during its initialization.

Also in this patch: the input and output ports are part of the
bt_component object. The public API is not changed. This avoids some
code duplication.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoPut Python plugin support in a separate shared object
Philippe Proulx [Wed, 8 Mar 2017 19:00:07 +0000 (14:00 -0500)] 
Put Python plugin support in a separate shared object

This is to make the work of packagers easier for libbabeltrace not
to depend on libpython, even if you need Python plugin support.

With this patch, python.c's constructor tries to open the new Python
plugin provider shared object. If it fails, Python plugin support is
disabled, but shared object plugins can still be loaded.

The new BUILT_IN_PYTHON_PLUGIN_SUPPORT configure variable, if set to 1,
makes the build embed the Python plugin provider into libbabeltrace
(like before this patch).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd `babeltrace convert` argument tests
Philippe Proulx [Tue, 7 Mar 2017 15:04:58 +0000 (10:04 -0500)] 
Add `babeltrace convert` argument tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoCLI: add `run` command and make `convert` command use it
Philippe Proulx [Fri, 3 Mar 2017 05:13:36 +0000 (00:13 -0500)] 
CLI: add `run` command and make `convert` command use it

This patch adds the babeltrace(1) command `run` which is essentially the
same as the current `convert` command without the magic stuff (legacy
options and their interesting constraints), plus this:

* You can set the name of a component by prefixing the --source,
  --filter, or --sink option's argument with `NAME:`. You can escape
  `.`, `:`, and `\` with `\`. Example:

      --source=instance:ctf.fs --sink=my-text:text.text
      --filter='my\.name:my\.plugin.my\.comp\.cls'

  This is the equivalent of:

      --source=ctf.fs --name=instance --sink=text.text --name=my-text
      --filter='my\.plugin.my\.comp\.cls' --name my.name

  The --name option still exists: it sets the current name of the
  current component, so that, with this:

      --sink=a:b.c --name=salut --name=bonjour

  the effective name of this component is `bonjour`.

* You can use the new --key and --value options to add one string
  initialization parameter to the current component. The name of this
  parameter is given by the last --key option's argument, and its value
  by the --value option's argument. Examples:

      --source=ctf.fs --key=path --value ~/lttng-traces/...
      --key=path --source=ctf.fs --value ~/lttng-traces/...

  This is useful to not care about the specific escaping required by the
  --params option format for a string parameter, to use any parameter
  name, and to use shell expansion for the value (tilde expansion for
  example, as --path is not a `run` command's option).

The `convert` command is now a specialization of the `run` command,
specific to a _conversion graph_ (whereas the terminology for what you
build with the `run` command is a _processing graph_). The conversion
graph that the `convert` command builds always has the following
topology:

    sources -> utils.muxer -> [utils.trimmer] -> lttng-utils.debug-info -.
           .-------------------------------------------------------------'
           '-> [user filters] -> sinks

There's no more --connect option in the `convert` command. When you run
the `convert` command, it prepares the equivalent `run` command
arguments and invokes the latter directly. However if `-o ctf-metadata`
exists, a new "print CTF metadata" command configuration is created, and
if `-o lttng-live` exists with a URL missing a session name, a new
"print LTTng-live sessions" command configuration is created.

New `convert` options are:

--color=(always | auto | never)
    Adds the `color` initialization parameter set to the corresponding
    value to the implicit text.text sink component.

--no-debug-info
    Do not add an implicit lttng-utils.debug-info filter component to
    the filter chain. The lttng-utils.debug-info filter always exists
    otherwise.

--run-args
    Instead of invoking the `run` command, prints to the standard output
    the equivalent `run` command arguments, formatted for a shell. This
    means you can copy the whole output and use it as is to execute
    `babeltrace run` without escaping, so that the two following
    commands are equivalent:

        babeltrace convert [...]
        babeltrace run $(babeltrace convert --run-args [...])

    You can also use this trick to augment the conversion graph with the
    `run` command, for example:

        babeltrace run --base-params common-to-each-convert-comp=23
                       $(babeltrace convert --run-args /path/to/trace
                         --source=src:my.source [...])
                       --reset-base-params
                       --sink=special-sink:my.sink
                       --connect=src.some-port:special-sink

--run-args-0
    Like --run-args, but does not escape the individual arguments for a
    shell, and uses the null character as the argument delimiter. This
    is useful to get the list of equivalent raw arguments outside a
    shell (in a user program), or to use `xargs -0`.

--url=URL
    Set the `url` initialization parameter of the current user component
    to URL.

Lost `convert` options are:

* --base-params
* --connect
* --reset-base-params

Note that --clock-force-correlate sets the boolean `force-correlate`
initialization parameter of the implicit utils.muxer filter to true.

The necessary conditions to instantiate implicit components are now:

* Implicit ctf.fs source: any of:
  * Leftover argument and no --input-format
  * Leftover argument and --input-format=ctf
  * Leftover argument and --clock-offset
  * Leftover argument and --clock-offset-ns
  * Leftover argument and --stream-intersection

* Implicit ctf.lttng-live source: any of:
  * Leftover argument and --input-format=lttng-live

* Implicit utils.muxer filter: always exists

* Implicit utils.trimmer filter: any of:
  * --begin
  * --end
  * --timerange

* Implicit lttng-utils.debug-info filter:
  * No --no-debug-info

* Implicit utils.dummy sink:
  * --output-format=dummy

* Implicit text.text sink: any of:
  * No --output-format and no --sink
  * --output-format=text
  * --clock-cycles
  * --clock-date
  * --clock-gmt
  * --clock-seconds
  * --color
  * --fields
  * --names
  * --no-delta
  * --output

The default names of the implicit components, given by the `convert`
command, to be used by the `run` command, are:

* Implicit ctf.fs source: `ctf`
* Implicit ctf.lttng-live source: `lttng-live`
* Implicit utils.muxer filter: always exists `mux`
* Implicit utils.trimmer filter: `trim`
* Implicit lttng-utils.debug-info filter: `debug-info`
* Implicit utils.dummy sink: `dummy`
* Implicit text.text sink: `text`

If any name is already taken by an explicit user component (--source,
--filter, and --sink), the rule is to try `NAME-0`, then `NAME-1`, then
`NAME-2`, etc. The same rule applies to unnamed user components.
Implicit components are always automatically named after automatically
naming the unnamed user components.

This patch also adds the following:

* Connection cycle detection in babeltrace-cfg-connect.c.
* bt_common_string_until() which returns a substring from a given point
  to one of a set of terminating characters, possibly with escapable
  characters.
* bt_common_shell_quote() which quotes a string (if necessary) for a
  shell.
* bt_common_string_is_printable() which checks if a string contains
  only printable characters, including whitespaces.
* bt_common_parse_lttng_live_url() to parse a LTTng-live URL. This is
  needed in both the LTTng-live plugin itself and babeltrace-cfg.c to
  know if the command is a `run` command or a "print LTTng-live
  sessions" command.
* The --name, --source, --filter, --sink, and --connect arguments are
  checked with bt_common_string_is_printable().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: missing reference release in field reset
Jérémie Galarneau [Fri, 10 Mar 2017 21:59:52 +0000 (16:59 -0500)] 
Fix: missing reference release in field reset

A missing bt_put() on in reset_structure_field() will cause
the reset fields to be leaked. This function is used on fields
which are automatically managed by the writer such as
timestamp_begin, timestamp_end, packet_size, and content_size.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: bt_connection_get_*_port() must take a reference on port
Jérémie Galarneau [Fri, 10 Mar 2017 19:29:15 +0000 (14:29 -0500)] 
Fix: bt_connection_get_*_port() must take a reference on port

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: only remove newly added components on connection error
Jérémie Galarneau [Fri, 10 Mar 2017 19:19:43 +0000 (14:19 -0500)] 
Fix: only remove newly added components on connection error

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: only add components to graph if they are not already present
Jérémie Galarneau [Fri, 10 Mar 2017 19:16:46 +0000 (14:16 -0500)] 
Fix: only add components to graph if they are not already present

bt_graph_connect() creates a connection and adds the components
on both ends of the connection to the graph. This fix ensures
that the components are not added a second time if multiple
connections involving the same components are established.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: release the reference held by a child to its former parent
Jérémie Galarneau [Fri, 10 Mar 2017 19:11:29 +0000 (14:11 -0500)] 
Fix: release the reference held by a child to its former parent

The bt_object class' bt_object_set_parent() increments the reference
count of the parent since the child now holds a reference to it.
This assumes that a child is externally visible when this call is
made (as is always the case currently).

The parent of a child can be changed in the future. In this case,
we want to ensure the reference it held to its former parent is
released.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace-cfg.c: do not allow duplicate -v option
Philippe Proulx [Wed, 22 Feb 2017 15:17:45 +0000 (10:17 -0500)] 
babeltrace-cfg.c: do not allow duplicate -v option

Otherwise, `babeltrace -vvv list-plugins` passes and tries to open the
`list-plugins` directory with ctf.fs.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace-cfg.c: add "Command line error" prefix to error messages
Philippe Proulx [Wed, 22 Feb 2017 15:20:46 +0000 (10:20 -0500)] 
babeltrace-cfg.c: add "Command line error" prefix to error messages

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace-cfg.c: do not infer text.text sink with -v
Philippe Proulx [Wed, 22 Feb 2017 15:26:00 +0000 (10:26 -0500)] 
babeltrace-cfg.c: do not infer text.text sink with -v

Having the -v option passed to the `convert` command is not a
sufficient criterion to infer a text.text sink component, because -v
is also a general option which applies to the whole command. Without
this patch, you can't run this:

    babeltrace -v /path/to/trace -o my.sink

because the configurator sees both an implicit text.text sink (caused by
-v) and an explicit my.sink sink.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): add --filter option to create filter components
Philippe Proulx [Wed, 22 Feb 2017 16:08:32 +0000 (11:08 -0500)] 
babeltrace(1): add --filter option to create filter components

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): escape '.' in PLUGIN.COMPCLS arguments
Philippe Proulx [Wed, 22 Feb 2017 18:08:12 +0000 (13:08 -0500)] 
babeltrace(1): escape '.' in PLUGIN.COMPCLS arguments

Now you can have dots in your plugin or component class names:

    babeltrace --source 'hello\.world.my\.component\.class'

Also, escape `\` with `\\`.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agocommon.c: bt_common_colors_supported(): add a few supported terminal prefixes
Philippe Proulx [Wed, 22 Feb 2017 18:18:53 +0000 (13:18 -0500)] 
common.c: bt_common_colors_supported(): add a few supported terminal prefixes

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoReturn component port counts by parameter
Jérémie Galarneau [Thu, 23 Feb 2017 14:36:05 +0000 (09:36 -0500)] 
Return component port counts by parameter

The rest of the API separates the return of success/error from
the return of the item count. This change makes the component
API consistent with the style used elsewhere.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRemove component prefix from graph, connection and port filenames
Jérémie Galarneau [Thu, 23 Feb 2017 13:45:01 +0000 (08:45 -0500)] 
Remove component prefix from graph, connection and port filenames

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd missing include in component-sink-internal.h
Jérémie Galarneau [Wed, 22 Feb 2017 18:47:22 +0000 (13:47 -0500)] 
Add missing include in component-sink-internal.h

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoBuild and run hard-coded component graph in babeltrace.c
Jérémie Galarneau [Wed, 22 Feb 2017 15:07:42 +0000 (10:07 -0500)] 
Build and run hard-coded component graph in babeltrace.c

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoUse graph facilities in dummy sink component class
Jérémie Galarneau [Wed, 22 Feb 2017 15:06:22 +0000 (10:06 -0500)] 
Use graph facilities in dummy sink component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoUse graph facilities in text component class
Jérémie Galarneau [Wed, 22 Feb 2017 15:05:57 +0000 (10:05 -0500)] 
Use graph facilities in text component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoUse graph facilities in trimmer component class
Jérémie Galarneau [Wed, 22 Feb 2017 15:05:16 +0000 (10:05 -0500)] 
Use graph facilities in trimmer component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoUse graph facilities in writer component class
Jérémie Galarneau [Wed, 22 Feb 2017 15:04:52 +0000 (10:04 -0500)] 
Use graph facilities in writer component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd missing forward declarations to component-class.h
Jérémie Galarneau [Wed, 22 Feb 2017 14:52:25 +0000 (09:52 -0500)] 
Add missing forward declarations to component-class.h

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoReplace add_iterator methods by a single new_connection method
Jérémie Galarneau [Tue, 21 Feb 2017 01:29:00 +0000 (20:29 -0500)] 
Replace add_iterator methods by a single new_connection method

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoImplement the component graph interface
Jérémie Galarneau [Sat, 18 Feb 2017 22:21:33 +0000 (17:21 -0500)] 
Implement the component graph interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoHide bt_component_sink_consume
Jérémie Galarneau [Sat, 18 Feb 2017 18:17:48 +0000 (13:17 -0500)] 
Hide bt_component_sink_consume

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoHide filter iterator creation functions
Jérémie Galarneau [Sat, 18 Feb 2017 18:16:34 +0000 (13:16 -0500)] 
Hide filter iterator creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoHide source iterator creation functions
Jérémie Galarneau [Sat, 18 Feb 2017 18:15:51 +0000 (13:15 -0500)] 
Hide source iterator creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoHide filter creation functions
Jérémie Galarneau [Sat, 18 Feb 2017 16:48:25 +0000 (11:48 -0500)] 
Hide filter creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd ports to the source, filter and sink component interfaces
Jérémie Galarneau [Fri, 17 Feb 2017 20:08:38 +0000 (15:08 -0500)] 
Add ports to the source, filter and sink component interfaces

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd the component port interface
Jérémie Galarneau [Tue, 14 Feb 2017 17:55:29 +0000 (12:55 -0500)] 
Add the component port interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoText: print unknown enumeration mappings in red
Jérémie Galarneau [Tue, 14 Feb 2017 17:50:33 +0000 (12:50 -0500)] 
Text: print unknown enumeration mappings in red

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoImplement the component connection interface
Jérémie Galarneau [Fri, 10 Feb 2017 15:50:13 +0000 (10:50 -0500)] 
Implement the component connection interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoText: tone down the rainbow text color scheme
Jérémie Galarneau [Tue, 14 Feb 2017 15:01:12 +0000 (10:01 -0500)] 
Text: tone down the rainbow text color scheme

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRename "query info" to "query" everywhere, and "action" to "object"
Philippe Proulx [Mon, 13 Feb 2017 22:01:33 +0000 (17:01 -0500)] 
Rename "query info" to "query" everywhere, and "action" to "object"

A "query" here is a request for a specific named object using or not
parameters. This is analogous to a REST (HTTP) GET stateless request:

    GET /path/to/object?param1=value1&param2=value2

Also expect the `metadata-info` object in the ctf.fs query method
instead of the `get-metadata-info` action.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agotext: mask some internal fields
Julien Desfossez [Mon, 23 Jan 2017 20:39:39 +0000 (15:39 -0500)] 
text: mask some internal fields

Some fields from the stream packet context are not really useful to the
end user of the text output, so we mask them by default. They can be
displayed using the -v/--verbose flag. The masked fields are the same as
in previous version:
 - timestamp_begin
 - timestamp_end
 - events_discarded
 - content_size
 - packet_size
 - packet_seq_num

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd the verbose parameter to the legacy text options
Julien Desfossez [Mon, 23 Jan 2017 20:37:32 +0000 (15:37 -0500)] 
Add the verbose parameter to the legacy text options

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): support -o metadata legacy option
Philippe Proulx [Sat, 11 Feb 2017 23:26:13 +0000 (18:26 -0500)] 
babeltrace(1): support -o metadata legacy option

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoctf.fs source: add `get-metadata-info` query info action
Philippe Proulx [Sat, 11 Feb 2017 22:30:46 +0000 (17:30 -0500)] 
ctf.fs source: add `get-metadata-info` query info action

The `get-metadata-info` query info action of the ctf.fs source returns,
if successful, the (possibly decoded) metadata string and if the
metadata file is packetized or not. It only needs the `path` parameter
which is the trace directory path (non-recursive).

You can test it with the query-info command:

    babeltrace query-info --source ctf.fs get-metadata-info
                          -p 'path="/path/to/trace"'

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): print value with colors
Philippe Proulx [Sat, 11 Feb 2017 21:05:12 +0000 (16:05 -0500)] 
babeltrace(1): print value with colors

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): add the query-info command
Philippe Proulx [Sat, 11 Feb 2017 20:37:09 +0000 (15:37 -0500)] 
babeltrace(1): add the query-info command

The new query-info command is the interface for the query info component
class API:

    babeltrace query-info --sink plugin.sink get-something
       --params meow=mix,zoom=18,consider-this=yes

The action is mandatory, as well as exactly one --source/--filter/--sink
option with the plugin and component class names to query info from. If
--params is not omitted, the query info method receives bt_value_null.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace-cfg: put comp. class type within struct bt_config_component
Philippe Proulx [Sat, 11 Feb 2017 19:20:21 +0000 (14:20 -0500)] 
babeltrace-cfg: put comp. class type within struct bt_config_component

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: test query info API
Philippe Proulx [Sat, 11 Feb 2017 18:54:52 +0000 (13:54 -0500)] 
bt2: test query info API

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: add support for the "query info" API
Philippe Proulx [Sat, 11 Feb 2017 18:27:06 +0000 (13:27 -0500)] 
bt2: add support for the "query info" API

Any user-defined component class can now define a _query_info() static
method which accepts an action name and parameters (value object, or
None) and returns a bt2.create_value()-compatible object:

    class MySink(bt2.UserSinkComponent):
        def _consume(self):
            pass

        @staticmethod
        def _query_info(action, params):
            if action == 'get-stuff':
                return {
                    'stuff': get_stuff(),
                    'id': get_id()
                }
            elif action == 'get-thing':
                return the_thing()

This static method can raise any exception: the caller of
bt_component_class_query_info() gets NULL.

On the Python side, either with a user-defined component class or with
a component class wrapper:

    results = comp_class.query_info('get-stuff', {'name': 'wrerzvr'})

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: raise when bt2.create_plugin_from_name() finds nothing
Philippe Proulx [Sat, 11 Feb 2017 18:23:12 +0000 (13:23 -0500)] 
bt2: raise when bt2.create_plugin_from_name() finds nothing

Returning None from this function when there's no plugin is Pythonically
weird:

    plugin = bt2.create_plugin_from_name()
    print(plugin.name)

The execution should not reach print() here when the plugin is not
found.

Raise the new bt2.NoSuchPluginError exception instead.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd query info API tests
Philippe Proulx [Sat, 11 Feb 2017 04:44:44 +0000 (23:44 -0500)] 
Add query info API tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoSO plugin API: add comp. class query info method macro and use it
Philippe Proulx [Sat, 11 Feb 2017 04:29:28 +0000 (23:29 -0500)] 
SO plugin API: add comp. class query info method macro and use it

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd bt_component_class_query_info() API
Philippe Proulx [Sat, 11 Feb 2017 04:19:27 +0000 (23:19 -0500)] 
Add bt_component_class_query_info() API

When you create a component class, you can set an optional "query info"
class method with bt_component_class_sink_set_query_info_method().

A "query info" class method is a method which accepts an action name
and custom parameters and returns custom results. It can be used for
component class-specific requests such as getting the beginning and end
timestamps of a trace, its total size, and other statistics. On some
real-time source component class, it can be used to get a list of
endpoints to which to connect.

You can use bt_component_class_query_info() to query a component class.
The action name and parameters are mandatory, although you can use
bt_value_null for the parameters.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): handle legacy -o dummy option
Philippe Proulx [Sat, 11 Feb 2017 03:56:33 +0000 (22:56 -0500)] 
babeltrace(1): handle legacy -o dummy option

Legacy -o dummy option instantiates a utils.dummy sink component.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd utils.dummy component class, move plugins/trimmer to plugins/utils
Philippe Proulx [Sat, 11 Feb 2017 03:49:22 +0000 (22:49 -0500)] 
Add utils.dummy component class, move plugins/trimmer to plugins/utils

This patch adds a plugins/utils directory where the utils plugin sources
are. plugins/trimmer is moved to this new directory because the trimmer
component class is part of the utils plugin.

Also in the utils plugin is the dummy sink component class. This sink
does absolutely nothing with its notifications. It is the equivalent of
the BT 1.x dummy format. At consume time, it gets one notification per
input notification iterator and returns
BT_NOTIFICATION_ITERATOR_STATUS_END when all the iterators are at the
end.

The legacy `-o dummy` option is not handled specifically in this commit.
You can use the dummy sink as usual:

    babeltrace /path/to/trace -o utils.dummy

The dummy component class ignores its initialization parameters.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agotext plugin: add color support
Philippe Proulx [Sat, 11 Feb 2017 01:31:56 +0000 (20:31 -0500)] 
text plugin: add color support

This patch adds terminal color support to the text plugin.

The text component class accepts a new initialization parameter `color`
which you can set to one of the following strings:

never:
  Never output color codes.

auto:
  Output color codes if the standard output is connected to a
  color-capable terminal and if the file stream to use is the standard
  output.

always:
  Always output color codes. This is useful to print colors even if the
  standard output is not connected to a terminal, for example:

      babeltrace /path/to/trace -o text.text -p color=always | less -R

The semantic of this parameter is the same as ls(1)'s and grep(1)'s
--color option.

The chosen color scheme is open to debate. In an ideal world, it should
be configurable by the component parameters, or read $LS_COLORS.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): add --connect option and connection management
Philippe Proulx [Fri, 10 Feb 2017 20:54:23 +0000 (15:54 -0500)] 
babeltrace(1): add --connect option and connection management

This patch adds the --connect option to connect component instances
by name (and optional port name):

    --connect SRC[SRCPORT]:DST[DSTPORT]

Example:

    babeltrace convert --source a.a --name A1 --source a.a --name A2
                       --sink b.b --name B
                       --connect A1.port:B
                       --connect A2.port:B.other-port

The code in babeltrace-cfg-connect.c validates that:

1. All the endpoint specified in connection arguments exist.

2. All connections are in the correct direction (source to filter,
   source to sink, filter to filter, filter to sink).

3. SRC and DST are not the same above.

4. All component instances are connected (no orphan component).

5. There's no duplicate connection.

There's a remaining validation to be done: ensure that there's no cycle
in the graph created by those connections.

If no --connect options are specified, babeltrace-cfg-connect.c connects
the component instances automatically:

1. It gives a unique name to unnamed component instances. The automatic
   name is TYPE-PLUGIN.COMPCLS.INDEX, where:

   TYPE:
     `source`, `filter`, or `sink`

   PLUGIN:
     Plugin name

   COMPCLS:
     Component class name

   INDEX:
     Automatic index to avoid collisions

2. It creates a multiplexer filter component configuration
   (`utils.mux`).

3. It connects the default ports of all the configured sources to the
   default port of this multiplexer filter.

4. It connects this multiplexer filter to the default ports of all the
   configured sinks.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace convert: add --name option
Philippe Proulx [Fri, 10 Feb 2017 06:33:06 +0000 (01:33 -0500)] 
babeltrace convert: add --name option

The --name option sets the name of the current (latest) component
instance, e.g.:

    babeltrace convert --source=abc.xzy --name=my-component ...

This can be useful to locate specific instances in the conversion graph,
in particular in case of error.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace(1): add help command
Philippe Proulx [Fri, 10 Feb 2017 06:12:57 +0000 (01:12 -0500)] 
babeltrace(1): add help command

The new `help` command shows all the information of a specific plugin
or of a specific component class.

The syntax to get help for a specific plugin is:

    babeltrace help PLUGIN

and for a specific component class:

    babeltrace help (--source | --filter | --sink) PLUGIN.COMPCLS

The full help of the component class (bt_component_class_get_help())
is printed when available.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace-cfg.c: improve error messages
Philippe Proulx [Fri, 10 Feb 2017 00:02:49 +0000 (19:02 -0500)] 
babeltrace-cfg.c: improve error messages

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoMake babeltrace(1)'s CLI Git-like and implement the list-plugins command
Philippe Proulx [Thu, 9 Feb 2017 19:42:57 +0000 (14:42 -0500)] 
Make babeltrace(1)'s CLI Git-like and implement the list-plugins command

This patch adds a command concept to the babeltrace(1) program, so that
the usage becomes:

    babeltrace [GENERAL OPTIONS] [COMMAND] [COMMAND OPTIONS]

The idea is to support multiple actions performed by the same program
without having to deal with a single command-line option parsing phase.

The default command is `convert`: it builds a trace conversion graph and
runs it. Therefore the current behaviour without a command name remains
the same.

The general command-line options, which can apply to all commands, are:

    -d, --debug        Enable debug mode
    -h  --help         Show general help and quit
        --help-legacy  Show Babeltrace 1.x legacy help and quit
    -v, --verbose      Enable verbose output
    -V, --version      Show version and quit

You can get the usage of a specific command with:

    babeltrace COMMAND --help

Because there is a default command, the parsing of the general options
is done manually to catch the first unknown option OR positional
argument. If an unknown option is found, all the arguments are given
back to the convert command. This is why the convert command also
parses --verbose, for example, because of this situation:

    babeltrace --debug --sink=my.sink --verbose

Here, the general options parsing stops at --sink because it's unknown,
and no explicit command name was found so far, so everything starting
with --debug is given to the convert command.

I also implemented the `list-plugins` command which lists plugins, their
component classes, and their properties:

    babeltrace list-plugins

You can still specify a plugin path or use the BABELTRACE_PLUGIN_PATH
environment variable with this command:

    babeltrace list-plugins --plugin-path=/path/to/other/plugins

I added color support in libbabeltrace-common and used it in the
`list-plugins` command. Color codes are only printed when color support
is detected, that is, when the standard output is connected to a
color-compatible terminal.

I also improved the way bt_value objects are printed with print_value()
in babeltrace.c to make it look more YAML-ish. This is easier on the
eyes.

This patch introduces a backward compatibility break in the very
specific scenario where an explicit command name is used and a directory
in the CWD exists with this name:

    babeltrace list-plugins

If `list-plugins` is a directory in the CWD, the legacy behaviour is to
recursively find CTF traces in it. With this patch, plugins are listed.
However a message is printed at the end of the command in this case:

    NOTE: The `list-plugins` command was executed. If you meant to
    convert a trace located in the local `list-plugins` directory,
    please use:

        babeltrace convert list-plugins [OPTIONS]

In other words, `babeltrace convert` (with 2.x) is a drop-in replacement
of `babeltrace` (with 1.x).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobabeltrace.c: replace printf_verbose() with printf() where appropriate
Philippe Proulx [Thu, 9 Feb 2017 06:24:55 +0000 (01:24 -0500)] 
babeltrace.c: replace printf_verbose() with printf() where appropriate

Only check if babeltrace_verbose is active and use printf() directly if
so instead of always using printf_verbose() which prints the [verbose]
prefix.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoCleanup babeltrace-cfg, use BABELTRACE_PLUGIN_PATH
Philippe Proulx [Thu, 9 Feb 2017 03:04:45 +0000 (22:04 -0500)] 
Cleanup babeltrace-cfg, use BABELTRACE_PLUGIN_PATH

This commit changes a few things at once:

* Cleanups the help message (orders long options alphabetically,
  adds metavars where missing, etc.).

* Removes is_setuid_setgid() to use the common bt_is_setuid_setgid().

* Makes the CLI load plugins *non-recursively*, which is more in line
  with typical lists of paths such as PATH, LD_LIBRARY_PATH, PYTHONPATH,
  etc., from the following directories, in this order:

  1. BABELTRACE_PLUGIN_PATH environment variable
  2. --plugin-path option
  3. ~/.local/lib/babeltrace/plugins
  4. System path (/usr/lib/babeltrace/plugins)

  For the in-tree version (conveter/babeltrace), Makefile.am passes all
  the in-tree plugin paths so that it can find everything that is known
  within the tree.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: test comp. class help attribute
Philippe Proulx [Wed, 8 Feb 2017 01:20:07 +0000 (20:20 -0500)] 
bt2: test comp. class help attribute

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: add support for comp. class help
Philippe Proulx [Wed, 8 Feb 2017 01:12:39 +0000 (20:12 -0500)] 
bt2: add support for comp. class help

The description of a user component class is the first line of the
class's docstring; the help is everything else starting at line 3:

class MySink(bt2.UserSinkComponent):
    '''This is the description.

    This is the help.

    This too:

        * And this.
        * And also that.

    Voilà.
    '''

    def _consume(self):
        # ...

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd shared object comp. class help attribute test
Philippe Proulx [Wed, 8 Feb 2017 00:56:36 +0000 (19:56 -0500)] 
Add shared object comp. class help attribute test

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoShared object plugin: add component class help support
Philippe Proulx [Wed, 8 Feb 2017 00:55:43 +0000 (19:55 -0500)] 
Shared object plugin: add component class help support

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd component class help property
Philippe Proulx [Wed, 8 Feb 2017 00:40:49 +0000 (19:40 -0500)] 
Add component class help property

The help of a component class is a full text which describes its
purpose, the expected params for its constructor, etc. It does not have
to start with a description since there's already a description property for
this.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt2: add create_plugin_from_name()
Philippe Proulx [Wed, 8 Feb 2017 00:12:33 +0000 (19:12 -0500)] 
bt2: add create_plugin_from_name()

This function wraps bt_plugin_create_from_name().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd bt_plugin_create_from_name() tests
Philippe Proulx [Tue, 7 Feb 2017 23:30:48 +0000 (18:30 -0500)] 
Add bt_plugin_create_from_name() tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd bt_plugin_create_from_name()
Philippe Proulx [Tue, 7 Feb 2017 06:22:10 +0000 (01:22 -0500)] 
Add bt_plugin_create_from_name()

This new function creates a new bt_plugin object from a simple plugin
name. It returns the first plugin which has the given name within the
following directories, in this order:

1. The colon-separated directories listed in the BABELTRACE_PLUGIN_PATH
   environment variable.
2. ~/.local/lib/babeltrace/plugins
3. $libdir/babeltrace/plugins, where $libdir is the value of --libdir
   at configure time (/usr/local/lib by default, typically /usr/lib
   when installed through a distribution).
4. The statically built-in plugins.

This makes it easier for any application using libbabeltrace to find a
Babeltrace plugin in a standard way without having to know the exact
location of the plugin file:

    ctf_plugin = bt_plugin_create_from_name("ctf");

Since babeltrace(1) also does this search, but has a --plugin-path
parameter to insert other directories at a specific place within the
search list, the common functions are put in the new
common/libbabeltrace-common.la convenience library. This is where new
(and existing) common functions between libbabeltrace and other parts of
the source tree (converter, plugins, etc.) should be put.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd support for plugins written in Python
Philippe Proulx [Fri, 3 Feb 2017 20:30:38 +0000 (15:30 -0500)] 
Add support for plugins written in Python

Now that the bt2 package exists and allows a user to create its own
component classes, we're not so far from a Python plugin support, a
Babeltrace plugin being only a set of basic attributes and a list of
component classes.

The chosen approach here is to add a module to the bt2 package,
py_plugin, which contains the following:

* plugin_component_class(): Function to be used as a decorator to tag a
  given user component class as being part of a Babeltrace plugin.

* register_plugin(): Function to be called anywhere from a Python module
  to register this module as a Babeltrace plugin. This call receives
  the name of the plugin and other optional attributes (description,
  author, license, etc.).

* _try_load_plugin_module(): Function reserved for the Babeltrace
  library to try to get a plugin information object from a given
  path (Python file).

  The same logic could be implemented with the Python C API, but since
  a Babeltrace Python plugin needs to import the bt2 package anyway,
  we're sure that the package exists and that we can use it. Arguably
  this function could be located in another module, outside the bt2
  package, for example in /usr/lib/babeltrace/plugin_utils.py.

Here's a very simple Python plugin which contains a single sink
component class named MySink:

    import bt2

    @bt2.plugin_component_class
    class MySink(bt2.UserSinkComponent):
        def __init__(self, params, name):
            self._stuff = params['stuff']

        def _consume(self):
            got_one = False

            for notif_iter in self._input_notification_iterators:
                try:
                    notif = next(notif_iter)
                except StopIteration:
                    continue

                got_one = True

                if isinstance(notif, bt2.TraceEventNotification):
                    event = notif.event
                    print('>>>', self._stuff, event.name)

            if not got_one:
                raise bt2.Stop

    bt2.register_plugin(__name__, name='my_plugin',
                        author='Philippe Proulx', license='MIT',
                        version=(2, 35, 3, '-dev'))

Here's what happens when the C API user does this:

    plugins = bt_plugin_create_all_from_file(
        "python-plugins/bt_plugin_hello.py");

1. bt_plugin_create_all_from_file() calls
   bt_plugin_so_create_all_from_file() without success, because the
   extension does not match.

   Then it tries bt_plugin_python_create_all_from_file().

2. bt_plugin_python_create_all_from_file() makes sure that the base name
   of the file to load starts with `bt_plugin_` and ends with `.py`. The
   prefix is up for debate, but my argument is that we don't want to
   import all the Python files when loading all the plugins of a
   directory: some Python files could be modules imported by plugins,
   not actual plugins. Having the prefix at least reduces the
   possibility of importing a non-plugin Python module.

3. init_python() is called. This function initializes the Python
   interpreter if it's not already done. It also refuses to do so if
   BABELTRACE_DISABLE_PYTHON_PLUGINS=1 (environment variable). It also
   imports the bt2.py_plugin module and finds the
   _try_load_plugin_module() function (global object, put in the
   library's destructor).

   If the needed global objects are still not set after this call,
   bt_plugin_python_create_all_from_file() returns an error. If
   init_python() fails, all the future calls to
   bt_plugin_python_create_all_from_file() will also fail (we don't
   attempt to initialize Python again if it failed once).

4. bt_plugin_python_create_all_from_file() calls
   _try_load_plugin_module() (Python) with the path, let's say
   `python-plugins/bt_plugin_hello.py`.

  a) A module name is created for this plugin. Since the plugin system
     can load plugins from files having the same base name, but in
     different directories, we cannot use the base name here. For
     example, we cannot name the module `bt_plugin_hello`: module names
     are unique in Python (for the whole interpreter) and are registered
     in the sys.modules dictionary.

     What's done here is to hash the path and prefix this with
     `bt_plugin_`. For example, this module would have the name
     bt_plugin_9dc80c7b58e49667cb5898697a5197d22f3a09386d017e08e2....

  b) The function tries to import the module using importlib. The module
     is executed from top to bottom:

    i) The @bt2.plugin_component_class decorator is called on the MySink
       class (which, thanks to its metaclass, has an associated native
       BT component class created): as a reminder, this is the
       equivalent of:

           MySink = bt2.plugin_component_class(MySink)

       This function adds an attribute to MySink: it sets
       MySink._bt_plugin_component_class to None. The mere existence
       of this attribute, whatever its value, means that this user
       component class is part of the plugin.

    ii) The module calls bt2.register_plugin(), passing __name__ as the
        first argument. This is used for bt2.register_plugin() to find
        the module from which it is called. In this case, __name__
        is bt_plugin_9dc80c7b58e49667cb5898697a5197d22f3a09386d017e...
        bt2.register_plugin() gets the actual module object from
        sys.modules and adds the _bt_plugin_info attribute to it after
        checking that all the arguments are correct. This is an object
        which contains, so far, the name and other optional properties
        of the plugin.

  c) If the import is successful, the function looks for the
     _bt_plugin_info attribute in the module object. If it's not found,
     an error is raised.

  d) The function then uses the inspect module to find all the classes
     in the module which contain the _bt_plugin_component_class
     attribute. All the native BT component class addresses are appended
     to a list which is set as the comp_class_addrs attribute of the
     plugin info object.

     _try_load_plugin_module() returns this plugin info object.

5. bt_plugin_python_create_all_from_file() calls
   bt_plugin_from_python_plugin_info() to convert the returned Python
   object to a bt_plugin object, which is returned to the user.

If anything goes wrong on the Python side during this call, and if
BABELTRACE_VERBOSE=1, the Python traceback is printed.

With the plugin above, we can run the converter like this to use its
sink component class:

    babeltrace --plugin-path python-plugins \
               -i ctf.fs -P /path/to/trace \
               -o my_plugin.MySink -p 'stuff="hello there!"'

We get something like this:

    >>> hello there! sched_switch
    >>> hello there! sys_open
    >>> hello there! sched_wakeup
    ...

It seems like Py_InitializeEx() and PyImport_ImportModule() can override
the current SIGINT handler, which is why we save the old handler before
calling those and then restore it afterwards. This seems to work.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd Babeltrace 2 Python bindings tests
Philippe Proulx [Sat, 4 Feb 2017 03:40:47 +0000 (22:40 -0500)] 
Add Babeltrace 2 Python bindings tests

This patch adds a testing infrastructure for the Python bindings of
Balbetrace, as well as tests for the bt2 package.

To run those tests, you need the tappy Python project
(https://github.com/python-tap/tappy). The configure script checks that
this project is available when you specify the new
--enable-python-bindings-tests option.

A test runner script, tests/utils/python/testrunner.py, loads the test
cases from a directory passed as its first command-line argument, sets
the TAP runner, and runs the tests, exiting with 0 if everything was
successful.

The Python binding tests are in tests/bindings/python/bt2 and are only
executed if the project is configured with --enable-python-bindings.
In this directory, testall.sh is generated from testall.sh.in to
call the test runner script with the appropriate paths, and set the
appropriate PYTHONPATH and LD_LIBRARY_PATH environment variables.

You can run testall.sh directly or with TESTALL_COVERAGE=1 to check the
coverage of the bt2 package with the Python `coverage` tool. You can
also set TESTALL_COVERAGE_HTML=1 to get an HTML report, or
TESTALL_COVERAGE_REPORT=1 to get a plain text report. The .coveragerc
file in this directory is a coverage configuration file which omits
certain files and exclude certain lines. The coverage of most modules
by the the tests is in the 90%-95% range as of this patch:

    __init__.py               100%
    clock_class.py            97%
    component.py              97%
    ctf_writer.py             63%
    event.py                  97%
    event_class.py            98%
    field_types.py            100%
    fields.py                 96%
    notification.py           79%
    notification_iterator.py  91%
    packet.py                 98%
    plugin.py                 30%
    stream.py                 92%
    stream_class.py           97%
    trace.py                  99%
    values.py                 95%

It is expected that ctf_writer.py be tested by the tests of the original
`babeltrace` package which will wrap the bt2 package in a future patch.

test_values.py and test_fields.py test that value and field objects
behave like Python native objects. For this, test methods are generated
to try each possible operator between each possible object. The result
is compared with the same operator applied to native Python objects (or
if the operation raises something, the compared operation must raise the
same thing).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd Babeltrace 2 Python bindings
Philippe Proulx [Sat, 4 Feb 2017 03:38:48 +0000 (22:38 -0500)] 
Add Babeltrace 2 Python bindings

This patch adds new Babeltrace 2 Python bindings to the Babeltrace
project.

Those bindings are compatible with Python 3 (only).

The new bindings still make use of SWIG to simplify the Python-to-native
and native-to-Python calls.

The new bindings, from Python's point of view, are available in the new
`bt2` package. This package imports (__init__.py does) everything that
is public from its modules, so that every public name is available as
bt2.something. This is considered more Pythonic than asking the user to
import specific modules from a given package.

The goal with this, to keep the "old" `babeltrace` package working, is
to make the `babeltrace` package a simple Python-only wrapper of the bt2
package (which offers much more, as you will discover in this commit
message).

Summary of features:

* All the current Babeltrace 2 APIs are wrapped:
  * Clock class
  * Component, component class, notification iterator, and notification
  * CTF writer, CTF writer clock, CTF writer stream
  * Event and event classe
  * Packet, stream, and stream class
  * Fields and field types
  * Plugin
  * Trace
  * Values
* Automatic BT reference count handling for the user (just like the
  `babeltrace` package does).
* Type checking of the arguments of each method/function (before it gets
  to SWIG, where the exception is not as obvious).
* Package exceptions:
  * Error
  * CreationError
  * FrozenError
  * UnsupportedFeature
  * TryAgain
  * Stop
  * IncompleteUserClassError
* Full support of user component classes.
* Package is as Pythonic as possible, with extensive use of collection
  ABCs, number and other protocols, iterators, properties, inheritance
  for the user, and exceptions.
* Easy to extend if we ever add new BT objects or APIs.
* The bindings only use the public Babeltrace 2 C API; they could be
  built outside the Babeltrace repository without altering the code.

Build system
============
Makefile.am does pretty much the same job as previously, although it is
organized so that it's easy to add Python modules and partial SWIG
interfaces. All the rules and commands are built from two simple lists.

SWIG
====
I created one SWIG interface file (.i) for each Babeltrace API. All the
native_bt*.i files are included at the end of native_bt.i. This is the
only input for SWIG.

native_bt.i does more than including partial interface files. It adds
rules to remove the bt_ and BT_ prefixes of all the wrapped functions
and enumeration items.

native_bt.i also adds a few custom typemaps to convert special arguments
back and forth between Python and the C API. For example,
`const char **BTOUTSTR` is a typemap to append a Python string (Unicode
object) to the current SWIG result tuple when the argument is named
as such, as in:

int bt_ctf_field_type_enumeration_get_mapping_signed(
        struct bt_ctf_field_type *enum_field_type, int index,
        const char **BTOUTSTR, int64_t *OUTPUT, int64_t *OUTPUT);

Note that, in example above, OUTPUT is a typemap provided by SWIG for
very simple types.

Another typemap is BTUUID to accept and return Babeltrace UUIDs as
Python `bytes` objects:

    BTUUID bt_ctf_clock_class_get_uuid(struct bt_ctf_clock_class *clock_class);

    int bt_ctf_clock_class_set_uuid(struct bt_ctf_clock_class *clock_class,
            BTUUID uuid);

Modules
=======
I'll now go into the details of each module of the bt2 package, in a
relevant order.

Most of the objects described below are comparable. Their compare
function usually start with a simple address comparison, and then falls
back to a rich comparison (sometimes implemented in Python if the
equivalent C function is missing).

utils
-----
Small utility functions: type checking, automatic exception raising,
power of two, etc.

object
------
bt_object API and reference counting.

Base class for a wrapped BT object (with reference counting), not
meant to be instantiated by the user.

Provides:

* self._ptr: SWIG pointer (native BT object), for the functions of
  the bt2 package (private).

* __init__(): called by subclass to wrap a SWIG pointer.

* addr(): public property which returns the address (integer, not the
  SWIG pointer object) of the object, mostly for debug purposes (for the
  user) and for a user to know if two bt2 objects actually wrap the
  same BT native object.

* _create_from_ptr(): class method to wrap a given SWIG pointer as an
  objet of a given class:

      event_class = EventClass._create_from_ptr(ptr)

* __repr__(): Shows the type of the object and its native address.

* __del__(): Puts its BT object reference (calls bt_put()).

object.py also contains _Freezable, a mixin for publicly freezable
objects.

values
------
bt_value API.

The classes in bt2.values are full Python wrappers of the native
bt_value types.

Features:

* BoolValue acts just like Python's bool.
* IntegerValue acts just like Python's int.
* FloatValue acts just like Python's float.
* StringValue acts just like Python's str.
* ArrayValue acts just like Python's list.
* MapValue acts just like Python's dict.
* bt_value_null is the equivalent of None.

In other words:

* All types are comparable and copyable (copy/deep copy).
* All the needed operators are implemented to make the value objects
  act like Python native objects.
* Number classes inherit ABCs in the numbers module.

There's also a bt2.create_value() function which returns a bt2.values
object from any value (bt2.values or native Python object).

I decided to wrap actual bt_value objects instead of always converting
from native Python objects to them and vice versa, because they can
still be shared in this case. Otherwise the conversion would remove this
sharing feature which is implicit with BT reference counting.

A few examples:

    my_int = bt2.IntegerValue(23)
    my_int += 283
    print(my_int)
    some_flt = bt2.FloatValue(45.3)
    print(my_int * some_flt)

    s = bt2.create_value('hello there')
    print(s[3:9])

    my_map = bt2.create_value({'ho': 23, 'meow': (4, 5, False, None)})
    print(my_map)
    print(my_map['meow'][1] >= 5)
    print(my_map.addr)

    for k, v in my_map.items():
        print('{}: {}'.format(k, v))

field_types
-----------
bt_ctf_field_type API.

This looks pretty much like the original field type objects of
the `babeltrace.writer` module, except for the following features:

* `Declaration` suffix is replaced with `FieldType` suffix to match
  the C API convention.

* Copy, deep copy, and comparison support.

* You can pass all the properties of an object at construction time:

      int_ft = bt2.IntegerFieldType(size=23, align=16, is_signed=True,
                                    base=8, mapped_clock_class=cc)

* Enumeration field type honors the sequence protocol:

      for mapping in enum_ft:
          print(mapping.name, mapping.lower, mapping.upper)

* Enumeration field type mapping iterator support, e.g.:

      for mapping in enum_ft.mappings_by_name('APPLE'):
          print(mapping.name, mapping.lower, mapping.upper)

  It's easy to add the mappings of another enumeration field type:

      enum_ft += other_enum_ft

* EnumerationFieldType inherits IntegerFieldType so that you can do:

      enum_ft = bt2.EnumerationFieldType(size=23, align=16,
                                         is_signed=True,
                                         base=bt2.Base.HEXADECIMAL,
                                         byte_order=bt2.ByteOrder.BIG_ENDIAN)
      print(enum_ft.size)
      enum_ft.is_signed = False

  instead of getting the underlying integer field type object manually.

* Structure and variant field types honor the mapping protocol:

      for name, ft in struct_ft:
          print(name, ft)

* You can set the `min_alignment` property of a structure field type
  (but you cannot get it), and you can get its `alignment` property
  (but you cannot set it). Those names represent exactly what they
  mean (less ambiguous than the C API equivalent IMO).

* You can instantiate a field object from a field type object by
  "calling" the field type object. This is closer to the concept of
  a class in the Python world:

      my_field = int_ft()

fields
------
bt_ctf_field API.

A bt2._Field is the result of instantiating a field type object. The
type (and all its subclasses) starts with an underscore because you
cannot instatiate them directly (possibly with an initial value):

    int_field = bt2.IntegerFieldType(32)(17)
    str_field = bt2.StringFieldType()('hello there')

Features:

* Copy, deep copy, and comparison support.
* IntegerField and EnumerationField act just like Python's int.
* FloatingPointNumberField acts just like Python's float.
* StringField acts just like Python's str.
* ArrayField and SequenceField honor the mutable sequence protocol.
* StructureField honors the mutable mapping protocol.

Field objects are just like value objects: they act like native Python
objects:

    int_field = bt2.IntegerFieldType(32)(152)
    int_field += 194
    print(int_field % 51)

    str_field = bt2.StringFieldType()('hello there')
    print(len(str_field))
    str_field += ' World!'
    print(str_field)

    print(struct_field['oh']['noes'][23])

    print(variant_field.selected_field)

    for mapping in enum_field.mappings:
        print(mapping.name, mapping.lower, mapping.upper)

clock_class
-----------
bt_ctf_clock_class API.

A straightforward clock class wrapper, pretty much equivalent to the
previous one (CTFWriter.Clock), except that:

* Copy, deep copy, and comparison support.

* You can pass all the properties of an object at construction time:

      cc = bt2.ClockClass('my_clock', frequency=18000000,
                          is_absolute=True, precision=500,
                          offset=bt2.ClockClassOffset(seconds=22,
                                                      cycles=187232))

* A clock offset is represented with a ClockClassOffset object.

* You can create a clock value from a clock class object with a given
  number of cycles:

      clock_val = cc.create_clock_value(234)

  This clock value object is copyable, deep-copyable, and comparable.
  You can get its number of cycles (raw value), its clock class,
  and the number of nanoseconds since Epoch:

      print(clock_val.ns_from_epoch())

event_class
-----------
bt_ctf_event_class API.

Features:

* Copy, deep copy, and comparison support.

* You can pass all the properties of an object at construction time:

      ec = bt2.EventClass('my_event', id=23, payload_field_type=ft)

* Parent stream class access (returns None if not set):

      print(ec.stream_class.id)

* Attributes property which honor the mutable mapping protocol:

      event_class.attributes['model.emf.uri'] = 'http://diamon.org/'

* Payload and context field type R/W properties.

* Call the class to instantiate an event:

      my_event = my_event_class()

stream_class
------------
bt_ctf_stream_class API.

Features:

* Copy, deep copy, and comparison support.

* You can pass all the properties of an object at construction time:

      sc = bt2.StreamClass(name='my_stream_class',
                           event_header_field_type=ev_header_ft,
                           event_classes=(ec1, ec2, ec3))

* Parent trace access (returns None if not set):

      print(sc.trace)

* A stream class object honors the mapping protocol to access its
  event class children by name:

      ec = sc['my_event']

      for ec_name, ec in sc.items():
          print(ec_name, ec.id)

* Packet context, event header, and stream event context field type R/W
  properties.

* Call the class to instantiate a stream:

      my_stream = my_stream_class('optional_name')

trace
-----
bt_ctf_trace API.

Features:

* Copy, deep copy, and comparison support.

* You can pass all the properties of an object at construction time:

      trace = bt2.Trace(name='my_trace',
                        native_byte_order=bt2.ByteOrder.LITTLE_ENDIAN,
                        env={'tracer_name': 'BestTracer', 'custom': 23},
                        packet_header_field_type=pkt_head_ft,
                        clock_classes=(cc1, cc2),
                        stream_classes=(sc1, sc2))

* A trace object honors the mapping protocol to access its stream
  class children by ID:

      sc = trace[23]

      for sc_id, sc in trace.items():
          print(sc_id, len(sc))

* Trace environment honors the mutable mapping protocol:

      trace.env['tracer_major'] = 1
      trace.env['tracer_minor'] = 2
      trace.env['uname_r'] = '4.7.2-1-ARCH'

      for k, v in trace.env.items():
          print(k, v)

* Trace clock classes honor the mapping protocol:

      cc = trace.clock_classes['my_clock']

      for cc_name, cc in trace.clock_classes.items():
          print(cc_name, cc.frequency)

* Packet header field type R/W property.

event
-----
bt_ctf_event API.

Features:

* Copy, deep copy, and comparison support.

* Event class, name, ID, and stream read-only properties.

* Event object implements __getitem__() to retrieve a field in different
  scopes:

      # can be found in context, if not in payload, for example
      my_event['cpu_id']

  This is the same behaviour as in the `babeltrace` package. Use the
  specific field properties instead of a field_with_scope() method:

      print(my_event.context_field['specific'])

* Packet property to set and get the event's packet:

      event.packet = my_packet

* Header, stream event context, context, and payload field R/W
  properties.

* You can assign a clock value mapped to a specific clock class and
  get it back:

      event.set_clock_value(some_clock_value)
      print(event.get_clock_value(some_cc).ns_from_epoch)

stream
------
bt_ctf_stream API.

This module defines a base class (_StreamBase) for _Stream (non-writer
stream) and _CtfWriterStream (writer stream).

Features:

* Copy, deep copy, and comparison support.

* You can create a packet from a non-writer stream:

      packet = stream.create_packet()

packet
------
bt_ctf_packet API.

Features:

* Copy, deep copy, and comparison support.

* Stream read-only property (gives back the stream object which
  created it).

* Packet context and packet header field R/W properties.

notification
------------
bt_notification API.

The classes in this module wrap their equivalent in the C API in a
pretty straightfoward way.

notification_iterator
---------------------
bt_notification_iterator API.

A notification iterator object is always created from a source/filter
component object:

    source_component.create_notification_iterator()

A notification iterator object has a next() method to go to the next
notification, and a `notification` property to get the current
notification:

    notif_iter.next()
    print(notif_iter.notification)

The next() method can raise:

* bt2.Stop: End of the iteration (inherits StopIteration).
* bt2.UnsupportedFeature: Unsupported feature.
* bt2.Error: Any other error.

A notification iterator also honors the iterator protocol, that is, you
can use it like any Python iterator:

    for notif in notif_iter:
        print(notif)

Note that the iteration can still raise bt2.UnsupportedFeature or
bt2.Error in this scenario (bt2.Stop stops the iteration: it's not
raised outside the iteration).

You can use the seek_to_time() method to make a notification iterator
seek to a specific time.

The `component` property of a notification iterator returns the original
source/filter component which was used to create it.

You can create your own notification iterator class (to be used by your
own source/filter component class) by inheriting
bt2.UserNotificationIterator. This asks you to write your own _next()
and _get() methods which are eventually called by
bt_notification_iterator_next() and
bt_notification_iterator_get_notification(). You can also define an
__init__() method, a _destroy() method, and a _seek_to_time() method.

Minimal user notification iterator class:

    class MyIterator(bt2.UserNotificationIterator):
        def _get(self):
            # ...

        def _next(self):
            # ...

Your _next() method can raise bt2.Stop to signal the end of the
iteration. If it raises anything else, bt_notification_iterator_next()
returns BT_NOTIFICATION_ITERATOR_STATUS_ERROR to its caller. Since
the C API user only gets a status from this function, any exception
value is lost during this translation. However the C next method could
still log this value and the traceback in verbose mode.

Your _get() method can raise anything so that the caller of
bt_notification_iterator_get_notification() gets an error status.

Complete user notification iterator class:

    class MyIterator(bt2.UserNotificationIterator):
        def __init__(self):
            # Called when the user calls
            # bt_component_source_create_notification_iterator() or
            # bt_component_filter_create_notification_iterator().
            # Anything you raise here makes this function return
            # NULL (creation error).

        def _get(self):
            # ...

        def _next(self):
            # ...

        def _seek_to_time(self, origin, time):
            # You can raise anything or bt2.UnsupportedFeature.
            # `origin` is one of the values of
            # bt2.NotificationIteratorSeekOrigin.

        def _destroy(self):
            # This is called when the actual native BT notification
            # iterator object is destroyed. Anything you raise here
            # is ignored. You cannot use __del__() for this for
            # implementation reasons.

You CANNOT manually instantiate a user notification iterator, e.g.:

    my_iter = MyIterator()

This makes no sense because a notification iterator is always created by
a source/filter component. It probably won't work anyway because
bt2.UserNotificationIterator.__new__() expects a SWIG pointer and your
__init__() probably does not.

component
---------
bt_component_class and bt_component APIs.

This is where the fun begins.

All component objects have the following properties:

* name: Component's name or None.
* component_class: Component class object.

Source components have:

* create_notification_iterator(): Returns a new notification
  iterator object.

Filter components have:

* create_notification_iterator(): Returns a new notification
  iterator object.
* add_notification_iterator(): Adds a notification iterator to the
  filter component.

Sink components have:

* consume(): Consumes notifications from its input notification
  iterators.
* add_notification_iterator(): Adds a notification iterator to the
  filter component.

A component class object has the following properties:

* name: Component class's name or None.
* description: Component class's description or None.

You can also call a component class object to create a component
object, with optional parameters and an optional component name:

    comp = comp_class(name='my_comp', params={'path': '/tmp/lel'})

The `params` argument is passed to bt2.create_value() so you can use
a direct *Value object or anything accepted by this utility function.

What is described above is the _generic_ part of components and
component classes. There's another part for user-defined component
classes. For a user of those classes, both generic and user-defined
classes expose the same interface. The relative complexity of how this
is achieved is justified by the great simplicity from the component
developer's perspective:

    class MySink(bt2.UserSinkComponent):
        def _consume(self):
            notif_iter = self._input_notification_iterators[0]
            notif = next(notif_iter)

            if isinstance(notif, bt2.TraceEventNotification):
                print(notif.event.name)

That's it: some kind of minimal sink component class. Note that
next(notif_iter) can raise bt2.Stop here which is passed to the eventual
caller of bt_component_sink_consume() as the BT_COMPONENT_STATUS_END
status.

Behind the scenes, bt2.UserSinkComponent uses _UserComponentType as its
metaclass. When the class itself is initialized, its metaclass checks if
the subclass has the required interface (depending on its base class,
bt2.UserSinkComponent in this case) and creates a bt_component_class
owned by the Python user class. This bt_component_class is associated to
the Python class thanks to a global GHashTable in the shared object
module (_native_bt.so). Both the key and the value are weak references.

The name of the created bt_component_class is the user class's name by
default (MySink above), but it can also be passed as a class argument.
The description of the created bt_component_class is the docstring of
the user class:

    class MySink(bt2.UserSinkComponent, name='another-name'):
        'this is a custom sink'

        def _consume(self):
            # ...

Source and filter user component classes need to specify a notification
iterator class to use when the user calls
bt_component_*_create_notification_iterator(). This is specified as
a class argument.

    class MyIterator(bt2.UserNotificationIterator):
        def __init__(self):
            # ...

        def _get(self):
            # ...

        def _next(self):
            # ...

        def _seek_to_time(self, origin, time):
            # ...

        def _destroy(self):
            # ...

    class MySource(bt2.UserSinkComponent,
                   notification_iterator_class=MyIterator):
        # no mandatory methods here for a source/filter component class

Note that, within the notification iterator methods, self.component
refers to the actual user Python object which was used to create the
iterator object. This is the way to access custom, component-wide data
when the notification iterator is created (self.component._whatever).

Optional methods for all user-defined component classes are:

    class AnyComponent(...):
        def __init__(self, params, name):
            # `params` is a *Value Python object (bt2.values module),
            # `name` is the optional (can be None) component name,
            # which you can also access as self.name at this point.

        def _destroy(self):
            # This is called when the actual native BT component
            # object is destroyed. Anything you raise here
            # is ignored. You cannot use __del__() for this for
            # implementation reasons.

Optional methods for filter and sink user-defined component classes
are:

    class FilterOrSinkComponent(...):
        def _add_notification_iterator(self, notif_iter):
            # This is called when a notification iterator is added to
            # the component (using bt_component_*_add_iterator()).

Additionally, the __init__() method of filter and sink component classes
can use the self._minimum_input_notification_iterator_count and
self._maximum_input_notification_iterator_count properties to set their
minimum and maximum number of allowed input notification iterators:

    class FilterOrSinkComponent(...):
        def __init__(self, params, name):
            self._maximum_input_notification_iterator_count = 10
            self._minimum_input_notification_iterator_count = 4

They can also use the self._input_notification_iterators property at the
appropriate time to get their connected input notification iterators.
This property honors the sequence protocol. For filter components, this
is most probably going to be used by the iterator class, as such:

    class MyIterator(bt2.UserNotificationIterator):
        def _get(self):
            # ...

        def _next(self):
            notif_iter = self.component._input_notification_iterators[0]
            # ...

The beauty of all this is that both a Python user and the C API side can
instantiate user components:

    Python:

        my_sink = MySink(params={'janine': 'sutto'})

        for _ in my_sink.consume():
            pass

    C API (provided you have access to the bt_component_class object
           created for the Python user class):

        my_sink = bt_component_create(my_sink_comp_class, NULL, params);

        while (true) {
            status = bt_component_sink_consume(my_sink);
            if (status == BT_COMPONENT_STATUS_END) {
                break;
            }
        }

This is possible thanks to the overridden metaclass's __call__() method:

* When a Python user instantiates a user-defined component class, the
  metaclass's __call__() method creates an uninitialized user component
  and calls bt_component_create_with_init_method_data(), giving to this
  function `self` (the uninitialized component).

  When the component initialization method is called with some init
  method data, it sets the bt_component pointer in the received Python
  object and calls its __init__() method so that its intialization
  happens within the bt_component_create_with_init_method_data() call
  (important because some functions cannot be called outside this
  function).

  If the user's __init__() method raises, the error is not cleared on
  the C side, so that the Python user who instantiates the component
  can catch the actual, original Python exception instead of getting
  a generic one.

  In this scenario, the created user component Python object OWNS its
  bt_component. The component is marked as NOT being owned by its
  bt_component:

      self._belongs_to_native_component = False

  The bt_component has the user Python object as its private data
  (borrowed reference).

* When a C user instantiates a user-defined Python component class, he
  calls bt_component_create(). Then the component initialization
  function for this class receives a NULL init method data and knows
  it is called from the C/generic side.

  The initialization method finds the corresponding Python component
  class thanks to the aforementioned global GHashTable. It calls it with
  the `__comp_ptr` keyword argument set to the native bt_component SWIG
  pointer and the `params` keyword argument set to the *Value object
  converted from the `params` parameter. This call (metaclass's
  __call__()), in this scenario, calls the user's __init__() method
  itself. This call returns a new component instance, which is set as
  the private data of the native bt_component.

  In this scenario, the created user component Python object as a
  borrowed reference to the native bt_component. The native bt_component
  OWNS the Python user's component:

      self._belongs_to_native_component = True

The self._belongs_to_native_component property is used for the following
situation:

    my_source = MySource()

    # At this point, my_source is a Python object which owns its
    # bt_component.

    notif_iter = my_source.create_notification_iterator()

    # notif_iter is a generic notification iterator (a dumb
    # bt_notification_iterator wrapper) here, not the actual user
    # Python notification iterator. This method only calls
    # bt_component_source_create_notification_iterator() and wraps the
    # returned pointer.

    del my_source

    # At this point, the Python reference count of the source component
    # object falls to zero. Its __del__() method is called. However
    # we don't want this object to be destroyed here, because it is
    # still needed by the user notification iterator. This __del__()
    # method, if self._belongs_to_native_component is false, inverts
    # the ownership, literally:
    #
    #     if not self._belongs_to_native_component:
    #         self._belongs_to_native_component = True
    #         native_bt.py3_component_on_del(self)
    #         native_bt.put(self._ptr)
    #
    # bt_py3_component_on_del() simply increments the given
    # Python object's reference count. With its reference count back
    # to 1, Python does not actually destroy the object. It is now
    # owned by the bt_component.

    del notif_iter

    # Now, the wrapper puts its bt_notification_iterator object. Its
    # reference count falls to zero. Its bt_component is put: its
    # reference count falls to zero. The user's (C) destroy method for
    # this component class decrements the reference count of its
    # private Python object (the same object referenced by my_source
    # above). __del__() is (possibly) called again, but is a no-op
    # now. Then the user's _destroy() method is called.

plugin
------
bt_plugin API.

You can create plugin objects with bt2.create_plugins_from_file().
This is the equivalent of bt_plugin_create_all_from_file(). You can
also use bt2.create_plugins_from_dir() which is the equivalent of
bt_plugin_create_all_from_dir().

The return value of those functions is a list of _Plugin objects.

Here's an example of printing all the event names of a CTF trace:

    import bt2
    import sys

    def print_all():
        plugins = bt2.create_plugins_from_file(sys.argv[1])
        fs_cc = plugins[0].source_component_class('fs')
        fs_comp = fs_cc(params={'path': sys.argv[2]})
        notif_iter = fs_comp.create_notification_iterator()

        for notif in notif_iter:
            if isinstance(notif, bt2.TraceEventNotification):
                print(notif.event.name)

    print_all()

You would run this script like this:

    python3 script.py /path/to/ctf-plugin.so /path/to/trace

You can access the properties of a plugin:

    print(plugin.path)
    print(plugin.name)
    print(plugin.description)
    print(plugin.author)
    print(plugin.license)
    print(plugin.version)

A plugin object honors the sequence protocol:

    for comp_class in plugin:
        print(comp_class.name, comp_class.description)

ctf_writer
----------
Everything in this module is exclusive to the CTF writer API:

* CtfWriterClock (bt_ctf_clock)
* _CtfWriterStream (bt_ctf_stream, CTF writer interface only)
* CtfWriter (bt_ctf_writer)

I removed the CTFWriter.Writer.create_stream() method because it's the
equivalent of this:

    writer.trace.add_stream_class(sc)
    stream = sc()

This returns a _CtfWriterStream object.

Also removed is CTFWriter.Writer.add_environment_field() which you can
do like this now:

    writer.trace.env['name'] = value

The CTFWriter.Writer.byte_order property is now the `native_byte_order`
property of the CTF writer's trace:

    writer.trace.native_byte_order = bt2.ByteOrder.BIG_ENDIAN

CtfWriter.add_clock() expects a CtfWriterClock object.

__init__
--------
This imports * from each module, thus exposing only the public names of
each one.

It also defines the package's exceptions. bt2.CreationError is raised
when an object cannot be created. bt2.FrozenError is raised when an
operation fails because the object is frozen. This is only raised for
bt2.values objects since this API has a status to indicate the exact
error. bt2.Error is a general error.

The package also does this:

    import bt2.native_bt as _native_bt
    import atexit

    atexit.register(_native_bt.py3_cc_exit_handler)
    _native_bt.py3_cc_init_from_bt2()

bt_py3_cc_init_from_bt2() is used to import some bt2 modules and objects
on the C side and the exit handler, bt_py3_cc_exit_handler(), puts those
objects.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agobt_ctf_event_set_clock_value() does not need a clock class
Philippe Proulx [Sat, 4 Feb 2017 08:37:54 +0000 (03:37 -0500)] 
bt_ctf_event_set_clock_value() does not need a clock class

Since a clock value has a clock class member, and you can
get it with bt_ctf_clock_value_get_class(), it's redundant
to specify both the clock class and the clock value when
you call bt_ctf_event_set_clock_value().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd bt_ctf_clock_value_get_class()
Philippe Proulx [Sat, 4 Feb 2017 08:18:06 +0000 (03:18 -0500)] 
Add bt_ctf_clock_value_get_class()

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoInstall notification headers in babeltrace/component/notification
Philippe Proulx [Sat, 4 Feb 2017 03:33:00 +0000 (22:33 -0500)] 
Install notification headers in babeltrace/component/notification

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agocomponent.c: return NULL when there's no name, not ""
Philippe Proulx [Thu, 2 Feb 2017 06:12:35 +0000 (01:12 -0500)] 
component.c: return NULL when there's no name, not ""

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agocomponent.c: iterator init method is optional
Philippe Proulx [Wed, 1 Feb 2017 19:15:49 +0000 (14:15 -0500)] 
component.c: iterator init method is optional

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoWriter fix: set packet size to 0 on flush failure
Jérémie Galarneau [Fri, 3 Feb 2017 02:21:26 +0000 (21:21 -0500)] 
Writer fix: set packet size to 0 on flush failure

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoWriter: only reset automatically-set fields
Jérémie Galarneau [Fri, 3 Feb 2017 02:21:01 +0000 (21:21 -0500)] 
Writer: only reset automatically-set fields

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoWriter: introduce try_set_structure_integer_field
Jérémie Galarneau [Fri, 3 Feb 2017 02:20:08 +0000 (21:20 -0500)] 
Writer: introduce try_set_structure_integer_field

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoWriter: set the discarded events's value before serializing
Jérémie Galarneau [Thu, 2 Feb 2017 17:57:57 +0000 (12:57 -0500)] 
Writer: set the discarded events's value before serializing

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoWriter: validating the packet header is not necessary
Jérémie Galarneau [Thu, 2 Feb 2017 17:54:49 +0000 (12:54 -0500)] 
Writer: validating the packet header is not necessary

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoTests: add empty packet writer test
Jérémie Galarneau [Fri, 3 Feb 2017 01:37:54 +0000 (20:37 -0500)] 
Tests: add empty packet writer test

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: only serialize a field if it is set
Jérémie Galarneau [Fri, 3 Feb 2017 01:37:27 +0000 (20:37 -0500)] 
Fix: only serialize a field if it is set

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: log structure field name on serialization failure
Jérémie Galarneau [Thu, 2 Feb 2017 17:23:09 +0000 (12:23 -0500)] 
Fix: log structure field name on serialization failure

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoTests: rename empty packet context test
Jérémie Galarneau [Thu, 2 Feb 2017 00:05:27 +0000 (19:05 -0500)] 
Tests: rename empty packet context test

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRename *create_iterator*() -> *create_notification_iterator*()
Philippe Proulx [Tue, 31 Jan 2017 07:50:22 +0000 (02:50 -0500)] 
Rename *create_iterator*() -> *create_notification_iterator*()

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoAdd bt_component_*_create_iterator_with_init_method_data()
Philippe Proulx [Tue, 31 Jan 2017 07:45:14 +0000 (02:45 -0500)] 
Add bt_component_*_create_iterator_with_init_method_data()

This is analogous to bt_component_create_with_init_method_data(),
but for notification iterators.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoRemove unused bt_component_class_filter_init_iterator_method
Philippe Proulx [Tue, 31 Jan 2017 07:44:11 +0000 (02:44 -0500)] 
Remove unused bt_component_class_filter_init_iterator_method

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoTests: close writer object before reading the trace produced
Jérémie Galarneau [Mon, 30 Jan 2017 23:47:04 +0000 (18:47 -0500)] 
Tests: close writer object before reading the trace produced

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
7 years agoFix: missing NULL check in ctf_fs_iterator_destroy_data
Jérémie Galarneau [Mon, 30 Jan 2017 23:31:18 +0000 (18:31 -0500)] 
Fix: missing NULL check in ctf_fs_iterator_destroy_data

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
This page took 0.065616 seconds and 4 git commands to generate.