lib: add unsigned and signed integer value API
This patch replaces the integer value API with the more specific
unsigned and signed integer value API. This opens the whole unsigned
64-bit set for component initialization parameters, query parameters,
queyr results, and, eventually, custom metadata attributes. This is also
more in line with the field API, which has both the unsigned and signed
versions.
Library
=======
The API is simply split in two, where an unsigned integer value contains
a `uint64_t` raw value and a signed integer value is the equivalent of
the previous integer value (`int64_t` raw value).
The types are `BT_VALUE_TYPE_UNSIGNED_INTEGER` and
`BT_VALUE_TYPE_SIGNED_INTEGER`.
There's no interaction between unsigned and signed integer values, in
that, for example, you cannot compare an unsigned integer value with a
signed integer value with bt_value_compare().
Behind the scenes, I kept a single `struct bt_value_integer` for
simplicity. It contains a union of `uint64_t` and `int64_t`. Most
functions call a generic unsigned version, casting to `uint64_t` when
necessary. For example, there's a common bt_value_integer_compare()
which compares the `uint64_t` values.
CLI
===
Before this patch, the `--params` option's format makes any integer
constant a signed integer value object. With this patch, you can create
an unsigned integer value by prepending the constant with `+`. For
example:
hello=+293, meow=+0x388ab88fd, uint-zero=+0
I wanted to use the `U` suffix, like in C/C++, but the GLib lexical
scanner won't allow a constant to be followed by an identifier without a
whitespace.
The documentation about the format of `--params` is updated for the
CLI's `--help` option and in the man pages.
Plugins
=======
It's up to each plugin to accept, for a given parameter, an unsigned
integer value, a signed integer value, or both. A plugin can be very
strict and it's not a bad thing: there are situations where an unsigned
integer is conceptually required.
The individual changes are:
`src.ctf.fs`:
In the `trace-info` query result, create unsigned integer values for
the `id` (stream ID) and `class-id` (stream class ID) entries. A CTF
metadata ID is never negative.
`src.ctf.lttng-live`:
In the `sessions` query result, the `timer-us`, `stream-count`, and
`client-count` entries are still signed integer values. They could
probably be unsigned, but I want to confirm this with developers
more involved with this component class before doing the change. For
the moment, the query operation is unchanged.
`sink.utils.counter`:
The `step` initialization parameter is now expected to be an
unsigned integer value. This is never negative.
I also made the initialization refuse parameters when they don't
have the expected type. There are new `logging.c` and `logging.h`
files for this component class because I used logging to communicate
said errors.
Library tests
=============
The integer value tests now test the signed value API.
I added equivalent unsigned value object tests.
Python bindings
===============
`_IntegerValue` is now the base class of `UnsignedIntegerValue` and
`SignedIntegerValue`. `_IntegerValue` contains the whole public
interface, using template methods with specialized parts defined in
subclasses.
`_IntegerValue` is imported in the `bt2` package for this use case:
if isinstance(val, bt2._IntegerValue):
do_something_with(val)
because `int(val)` is always valid.
The bt2.create_value() function still creates a `SignedIntegerValue`
object with an `int` value. This is the safest, as there's no way to
know that this value will be changed to a negative value in the future,
before the value object is frozen. For example, this would not be
possible with a conversion to an `UnsignedIntegerValue`:
val = bt2.create_value(47)
val.value = -23
whereas it is possible with a `SignedIntegerValue`. You can still
explicitly create an unsigned integer value:
counter_comp = my_graph.add_component(counter_cls, 'counter', {
'step': bt2.UnsignedIntegerValue(29)
});
Python bindings tests
=====================
`test_value.py` is updated to also test the `UnsignedIntegerValue`
class. _inject_numeric_testing_methods() now accepts an optional
`has_neg` parameter which, if false, does not inject tests which involve
negative integer values.
There is a common `_TestIntegerValue` class which
`SignedIntegerValueTestCase` and `UnsignedIntegerValueTestCase` inherit.
The tests are almost the same, but `SignedIntegerValueTestCase` adds a
few tests related to negative values. Both specific test cases set the
`_CLS` class attribute to the value object class to test, either
`UnsignedIntegerValue` or `SignedIntegerValue`.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ic96ef9e1e16883cb5c59844c6ba5a060936efdb0
Reviewed-on: https://review.lttng.org/c/babeltrace/+/1257
Tested-by: jenkins
29 files changed:
This page took 0.02792 seconds and 4 git commands to generate.