Add bt2c::join()

This new function template joins the strings of some container with
some delimiter.

The container needs a forward iterator and its elements need the data()
and size() methods.

The container may be empty.

For example:

    int main()
    {
        std::cout << bt2c::join(std::vector<std::string> {
            "salut", "meow", "mix"
        }, ", ") << '\n';
    }

will print

    salut, meow, mix

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Id3ff90cf3b2fa4336b71860dbe3c0dff83668607
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12735

Add `ctf::src::Ctf1MetadataStreamParser` class (TSDL)

This patch adds the `ctf::src::Ctf1MetadataStreamParser` class which is
a concrete TSDL metadata stream parser inheriting
`ctf::src::MetadataStreamParser`.

parseSection() requires one or more complete root blocks of TSDL
contents.

`ctf::src::Ctf1MetadataStreamParser` also implements the static
ctf::src::Ctf1MetadataStreamParser::parse() which considers a whole
metadata stream. While this static method currently doesn't add anything
to creating a parser and calling parseSection() once, it could
eventually contain more validation knowing that the metadata stream was
completely parsed.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: I55e0f2f05d64a0acc5949029e315aeefae424dda
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8000
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12734

Add `ctf::src::MetadataStreamParser` abstract base class

This is an abstract base class for any metadata stream parser.

Parse a metadata stream section with parseSection() (defers to the
virtual _parseSection() method).

Get the resulting, current trace class and metadata stream UUID with
traceCls() and metadataStreamUuid().

The constructor accepts an optional self component pointer so that
parseSection() may finalize the trace class after calling the
version-specific _parseSection().

The trace class finalization method finalizes a `ctf::src` CTF IR trace
class after its creation or when it gets new data stream classes or
event record classes. The method:

• Sets the value saving indexes of dependencies (field classes) and the
  saved value index of dependent (dynamic-length, optional, and variant)
  field classes.

  It also links the dependent field classes to their dependencies by
  weak pointer.

• Reconfigures the clock classes of the trace class.

• Normalizes the offsets of the clock classes of the trace class so that
  the cycle part is less than the frequency.

• With a self component pointer, translates the contained objects to
  their trace IR equivalents.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Change-Id: I24e175447f759220de5943ccb49c7888a5934ce5
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12733

cpp-common/bt2/trace-ir.hpp: use "common event context"

This is easier to read.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Iabfe3b3a44dcdfad03be47c3cb69b64fb729e91c
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12732

cpp-common/bt2/field{,-class}.hpp: adapt to latest libbabeltrace2 API

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ia4dbbd5c35a482e3dff634d8e99192b0d1c08784
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12731

cpp-common/bt2/trace-ir.hpp: adapt to latest libbabeltrace2 API

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I0dd81df640da63f1e6a1bdac43d4b89e86f36c6b
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12730

cpp-common/bt2/clock-class.hpp: adapt to latest libbabeltrace2 API

Read anything related to the origin with the new origin() method which
returns a clock origin view from which you may get the namespace, name,
UID, and whether or not it's unknown or the Unix epoch.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ib44547fd60580ab9aea3c0cb3492542749d3a5da
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12729

cpp-common/bt2: add support to get / set trace UID

Wrap bt_trace_set_uid and bt_trace_get_uid.

Change-Id: I610c426424214334fb210421809adae3e214c4e3
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10154
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12728

lib: add support for bit array flags

Implement support for flags on bit array field classes, in order to
be able to add support for the fixed-length bit map field class (as
specified by CTF2-SPEC-2.0 [1]) in the CTF component classes.

A flag is a mapping between bit positions in a fixed-length bit map
field and a textual label.  A flag is considered active for a given
field if any of the bits in the flag's bit positions is set in the
field.  Flags may have overlapping bit positions, meaning that a single
bit can activate multiple flags.

Add the following public functions operating on bit array field classes:

 🥑 bt_field_class_bit_array_add_flag
 🥑 bt_field_class_bit_array_get_flag_count
 🥑 bt_field_class_bit_array_borrow_flag_by_index_const
 🥑 bt_field_class_bit_array_borrow_flag_by_label_const
 🥑 bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer

Add the bt_field_class_bit_array_flag type.  Then, add the following
public functions operating on it:

 🥑 bt_field_class_bit_array_flag_get_label
 🥑 bt_field_class_bit_array_flag_borrow_index_ranges_const

Add the following public function operating on a bit array field:

 🥑 bt_field_bit_array_get_active_flag_labels

The
`bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer`
function returns an array of label through an output parameter of type
`bt_field_class_bit_array_flag_label_array`.  The storage for it is
owned by the field class, so the result is only valid until the next
call to the function (or until the field class gets destroyed).  This
behavior is copied from the enum field class.

Philippe updated the documentation.

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Change-Id: Ib88f3aecf692ea8b6453c0308fa7735fd40e55a9
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12727
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

lib: add bt_clock_class_has_same_identity function

Add the bt_clock_class_has_same_identity utility function, which tells
if two clock classes have the same identify.

The criteria for whether two clock classes have the same identity are
the same as in CTF 2:

    Two clock classes which satisfy all the following conditions are
    said to have the same identity:

     - Both share the same namespace property value, or both don’t have
       any namespace property.
     - Both have a name property and share the same value.
     - Both have a uid property and share the same value.

Philippe updated the documentation.

Change-Id: I55e4e13274d413a15873099045f14690feab09c4
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10749
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12726

lib: add clock class accuracy property

With the intent of supporting CTF 2, add the accuracy property to clock
classes.

 - Add the bt_clock_class_{g,s}et_accuracy getter and setter, both of
   which are restricted to MIP >= 1.
 - Add the accuracy field to struct bt_clock_class.
 - Make lib-logging print the accuracy of a clock class, if set.

Philippe updated the documentation.

Change-Id: I199ea6d339fcb0142847825c3d12ae526564814d
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10711
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12725

lib: make clock class precision optional

With the intent of supporting CTF 2, make the precision property of
clock classes optional under MIP 1.

 - Change the precision field of struct bt_clock_class to
   bt_property_uint.
 - Adjust lib-logging to omit the precision if not set.
 - Change bt_clock_class_create to make the precision property available
   with MIP 0, so that the precision will always be available with MIP
   0 (still with an initial value of 0).
 - Restrict bt_clock_class_get_precision to MIP 0.
 - Add bt_clock_class_get_opt_precision, which returns a
   bt_property_availability value.  Note that
   bt_clock_class_get_opt_precision can be used with MIP 0, it will
   always return BT_PROPERTY_AVAILABILITY_AVAILABLE.

Not done in this patch: adapt the Python bindings.

Philippe updated the documentation.

Change-Id: I1daf6627fda741f854d85ad6ff6f4ad132591662
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10710
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12724

lib: add event class UID property

Add a UID property to event class objects.  This is needed to
support CTF 2.

Philippe updated the documentation.

Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Change-Id: Iae20d1d9835de2a04b02493c824e486e6fed7dcf
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10698
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12723

lib: add stream class UID property

Add a UID property to stream class objects.  This is needed to
support CTF 2.

Philippe updated the documentation.

Change-Id: Iac6f88ada28f0e97cf3082fd753df0867cb772d0
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10696
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12722

lib: add trace namespace property

Add a new namespace property for trace objects.  This is needed to
support CTF 2.

Philippe updated the documentation.

Change-Id: I9c382879a3181aab2859a4c41cfbb21c4f6928aa
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10695
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12721

lib: add clock class namespace and UID properties

Add the namespace and UID properties to clock class objects.  This is
needed to support CTF 2.

Philippe updated the documentation.

Change-Id: I9b6ee8f78581ca8ebfa8b1ceca0d1fe50178c1b3
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10677
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12720

lib: add bt_trace_class_get_graph_mip_version

Add bt_trace_class_get_graph_mip_version, which returns the MIP version
for the graph the trace class is in.

This will be necessary for the Python bindings functions dealing with
trace IR that need to change their behavior according to the MIP
version.  Right now, the MIP version can be obtained from a self
component.  But some Python functions (for instance
_TraceClass.create_variant_field_class) only have a IR object to work
with, and it's not possible to get the self component from there.
Adding a function to get the self component from a trace class was
considered, but it was deemed to complex because of object lifetime and
refcount cycle issues.

Philippe updated the documentation.

Change-Id: Ie31be7d31baf1242bad3927021de7c949f281247
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10155
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12719

Add ctf::src::normalizeClkOffset()

Also, use it in `visitor-generate-ir.cpp` instead of the local
function.

Change-Id: I5073a901f8c4c434ad35e102aaeb145a30055506
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12718
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

Implement CTF 2 JSON requirements

This patch implements all the CTF 2 JSON requirements.

The internal "public" API is the `Ctf2JsonAnyFragmentValReq` PImpl class
which validates a single CTF 2 fragment. That's all the CTF 2 metadata
stream parser will need.

Here's an example:

Code:
    Ctf2JsonAnyFragValReq {}.validate(*bt2c::parseJson(jsonText));

JSON text:
    {
      "type": "data-stream-class",
      "namespace": "lol",
      "name": "salut",
      "packet-context-field-class": {
        "type": "structure",
        "member-classes": [
          {
            "name": "meow",
            "field-class": {
              "type": "null-terminated-string"
            }
          },
          {
            "name": "lel",
            "field-class": "uint16"
          },
          {
            "name": "meow",
            "field-class": {
              "type": "dynamic-length-array",
              "length-field-location": {"path": ["lel"]},
              "element-field-class": {
                "type": "fixed-length-signed-integer",
                "length": 23,
                "byte-order": "little-endian",
                "alignment": 24,
                "attributes": {}
              }
            }
          }
        ]
      }
    }

Exception message:
    [1:1] Invalid data stream class fragment:
    [5:33] In object property `packet-context-field-class`:
    [5:33] Invalid scope field class:
    [5:33] Invalid structure field class:
    [7:23] In object property `member-classes`:
    [18:7] In array element #3:
    [18:7] Invalid structure field member class:
    [20:24] In object property `field-class`:
    [20:24] Invalid dynamic-length array field class:
    [23:34] In object property `element-field-class`:
    [23:34] Invalid fixed-length signed integer field class:
    [27:26] In object property `alignment`:
    [27:26] Invalid alignment: 24 is not a power of two.

I'd say that Ctf2JsonAnyFragValReq::validate() can validate 95 % of a
CTF 2 metadata stream. See its class comment to learn what it can't do.

There are a few clang-format off/on comments because I hate what it does
with nested brace-enclosed lists.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ic622a099a1e0aa5daa896cdfa910d24b817a9a5f
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12717

`ctf` plugin: add `ctf::src::MsgIter` class

Original patch by Simon.

Philippe's changes over original patch (no functional change intended):

• Conform to the Babeltrace 2 coding style for new C++11 code and to
  some naming conventions of the common part of the `ctf` plugin.

• Add many public and internal comments.

• Rename `Quirks` class to `MsgIterQuirks`.

  Also, rename the quirks to the generic `pktEndDefClkValZero`,
  `eventRecordDefClkValGtNextPktBeginDefClkVal`, and
  `eventRecordDefClkValLtPktBeginDefClkVal` names to decouple this API
  from specific tracers.

• Remove `MsgIterItemVisitor`.

  Instead, MsgIter::_handleItem() dispatches the item to a specific
  handling method based on its numeric type.

  Move the relevant members of `MsgIterItemVisitor` into
  `MsgIter` itself.

• In `_StackFrame`, rename everything named "field" to "sub-field" so as
  to remove some ambiguity.

• Add MsgIter::_stackTop*() helper methods which defer to the
  corresponding method on the top stack frame.

• Add MsgIter::_stackPush() and MsgIter::_stackPop() helper methods.

• Add MsgIter::_addMsgToQueue() helper method.

• Only log item details when the `TRACE` level is enabled.

• Handle `PktMagicNumberItem`: validate the magic number value.

• Handle `MetadataStreamUuidItem`: validate the UUID.

  The `MsgIter` constructor now accepts an `expectedMetadataStreamUuid`
  parameter (optional UUID) which is the expected metadata stream UUID
  to compare to.

• Handle variable-length integer field items, adding the
  MsgIter::_handleUIntFieldItem() and MsgIter::_handleSIntFieldItem()
  helper method templates to do so.

• Handle BLOB field items.

  A new data member, `_mCurBlobFieldDataOffset`, tracks the current BLOB
  field data offset to write to when handling the next
  `BlobFieldSectionItem` (we can't append to a BLOB field like when
  handling `StrFieldSubstrItem`).

• Handle optional field items, adding a member
  to `MsgIter::_StackFrame::_Field`.

• In MsgIter::_StackFrame::goToNextSubField(), unconditionally increment
  `_mSubFieldIndex`: curSubField() doesn't care about `_mSubFieldIndex`
  for the variant/option field cases anyway.

  Therefore, make curSubFieldAndGoToNextSubField() reuse curSubField()
  and goToNextSubField() to remove some almost duplicate code.

• Handle UTF-16 and UTF-32 string data.

Change-Id: If2dd82b43f4d19a16ec4420c13c9a3686034766d
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8227
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12716

cpp-common/bt2c: add `UnicodeConv` class

Add the `UnicodeConv` class, which currently implements conversion
from (UTF-16, UTF-32) × (BE, LE) to UTF-8.

The `UnicodeConv` class uses `g_iconv` from GLib internally to make
the conversions.  It has a vector member that is used as an output
buffer.  Public conversion methods accept a span of
`const std::uint8_t`, and return a span `std::uint8_t` which is a view
on that internal vector.

Add a test which:

✤ Converts some hardcoded UTF-16 and UTF-32 strings to UTF-8 and
  verifies the result against a reference UTF-8 string.

✤ Feeds the UTF-16 and UTF-32 conversion methods with truncated strings
  and verifies that they throw and append specific causes to the error
  of the current thread.

Change-Id: I962bd49261a3d9779ed6a24a26c7800a24beb719
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12715

Fix: use `OptionalBorrowedObject::hasObject()` in `CommonOptionField::hasField()`

This is needed since `OptionalBorrowedObject::operator bool()` is
explicit.

Change-Id: Iabd899be72607b1d5eb1a42dec919c14d0e33868
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12714
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2: add `CommonBlobField` and `CommonDynamicBlobField`

Use `CommonBlobField::data()` to access the data pointer and data length
(bytes) of the BLOB field as a `bt2s::span`. A `BlobField::data()`
returns `bt2s::span<std::uint8_t>` while `ConstBlobField::data()`
returns `bt2s::span<const std::uint8_t>`.

Use `CommonDynamicBlobField::length()` to set the length of a dynamic
BLOB field (like `CommonDynamicArrayField::length()`).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I3d9f9417e262a5fbbc9b7bb8f3d690d6628f7988
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12713

src.ctf.fs: Add `readPktProps()`

Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: I0e98db658cc50e44bc8d77c8dea53c1984af28aa
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8190
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12712

src.ctf.fs: Add `LoggingItemVisitor`

While developing, I found it useful to print the sequence of items seen
by a given visitor, so I would make the various visitor methods print
some information.  Instead of re-implementing it in the various
visitors, I eventually extracted the functionality in its own visitor
(the one this patch adds).

This visitor logs details about the visited items.  Indentation is used
to represent the items that are logically nested in other ones.  For
example, everything between a ScopeBeginItem / ScopeEndItem pair gets
nested.

The logging is done unconditionally.  The intent is that the caller uses
something like:

  if (BT_LOG_ON_TRACE) {
      item.accept(loggingVisitor);
  }

to log at a given log level.

Philippe's changes:

* Add usage comments to `logging-item-visitor.hpp`.

* Move enumerator-to-string functions to `logging-item-visitor.cpp`.

* Move templates and everything `static` to `logging-item-visitor.cpp`.

* Log more details about some items.

* Reduce code redundancy.

* Use the standard Babeltrace 2 log statement format (therefore removing
  indentation).

* Log with BT_CLOGT() instead of BT_CLOGD().

Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ie8a95217564bfbaa59f78793d7ba0b47aad1d882
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8202
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12711

Cleanup: src.ctf.fs: remove unused decoder functions

Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: I8c2610883c8730a36e3e4336c2dc48b67d3e6236
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8038
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12710

src.ctf.*: add old CTF IR const functions

Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: I73f825b4127cff772904579c90806bd367a7fe36
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8012
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12709

src.ctf.fs: implement `MetadataStreamDecoder` class

This class offers a `decode()` method that decodes a potentially
packetized metadata stream as a `std::string`.

After decoding a buffer, the `pktInfo()` method may return packet
information of the packetized metadata stream.

Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: Iee867271fe6493b19c4bd77151409886b7c01ed9
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8050
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12257

src/plugins/ctf/common/src: add item sequence iterator API

This patch adds the item sequence iterator API, internal to the `ctf`
plugin, to be used by the source components (`src.ctf.fs`
and `src.ctf.lttng-live`).

An item sequence iterator can decode a sequence of packets using:

• A medium, which provides binary stream data to the iterator.
• A CTF IR trace class, which describes how to decode said data.

This makes it possible to completely decode CTF data streams without
ever needing to create trace IR objects. In other words, it's a
standalone CTF decoding library which, minus a few utilities borrowed
from the Babeltrace project, could even be reused in other projects.

The value of an item sequence iterator is an item. The item sequence
iterator doesn't actually create items as it advances: it has one
instance of each concrete item class and sets a pointer to one of those
as it advances (it's a single-pass input iterator).

Seek a specific packet beginning with the seekPkt() method.

Methods which make the iterator decode may append a cause to the error
of the current thread and throw `bt2c::Error`.

┌──────────────────────────────────────────────────────────────────────┐
│ NOTE: Currently, this isn't an STL-compliant iterator class: you     │
│ can't copy an instance and you can't get an end iterator, because    │
│ there's no item sequence (container) class (you need to check        │
│ whether or not the next() method returns `nullptr`). Also, the       │
│ typical STL type aliases such as `value` and `reference` aren't part │
│ of the class.                                                        │
└──────────────────────────────────────────────────────────────────────┘

This API and its implementation are inspired by the yactfr
(<https://github.com/eepp/yactfr>) element sequence iterator API,
conveniently written by the same author 😉.

Please read the class comments of `ctf::src::ItemSeqIter` and
`ctf::src::Medium` to learn how to use this API and how it
works internally.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I423cc934d2425331a09f16ba40fbeb6b5496ff3a
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7966
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12256

cpp-common/bt2c/std-int.hpp: use dedicated enum. instead of `bool`

This makes the code clearer, for example

    bt2c::StdIntT<32, bt2c::Signedness::Signed>

vs.

    bt2c::StdIntT<32, true>

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Icbb718dd36e11d5e072c7fc4b58fc2d4ca090d58
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12708

src.ctf.*: add `ctf::src::NullCpFinder`

An instance of this new class keeps a temporary code unit of length
`CodeUnitLenV` bytes to help finder a null codepoint (U+0000) in
contiguous buffers (especially when the encoded codepoint spans more
than one buffer).

See the comment of the new class to learn more.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I80feb4402cc0256d7c48c357ca23e355c4322ce0
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12707

Add bt2c::reverseFixedLenIntBits()

This new function reverses the first N least significant bits of a
64-bit integer value, sign-extending if needed, and returns the result.

I basically read [1], which shows the version of Knuth, and adapted that
code to our coding style and requirements.

[1]: https://matthewarcus.wordpress.com/2012/11/18/reversing-a-64-bit-word/

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ib67fd5e8b94e0a82f46527534d47617c87013418
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12706

Add `cpp-common/bt2c/aliases.hpp` to contain common aliases

The first one is

    using ConstBytes = bt2s::span<const std::uint8_t>;

which we need at various locations.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ic6cdaeca4b63c89bea8f51c7bb45f168039bd40f
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12705
CI-Build: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>

Add CTF IR classes specific to `src.ctf.*`

This patch uses the `ctf::ir` API to expose a source-specific CTF IR API
under the `ctf::src` namespace, to be used by both the `src.ctf.fs` and
the `src.ctf.lttng-live` component classes.

This specific CTF IR API augments the common `ctf::ir` API with user
mixins to add the following:

• Any field class has a "deep type".

  See the comment of `ctf::src::FcDeepType` to understand why we need
  such an enumeration.

• The field class, clock class, event record class, data stream class,
  and trace class classes have an optional equivalent libbabeltrace2
  class object.

  This is a bridge between the CTF IR world and the libbabeltrace2 world
  to be able to create corresponding libbabeltrace2 messages when
  decoding a data stream with the CTF IR classes.

  If a field class has no equivalent libbabeltrace2 class, then the
  values of its instances aren't transported through messages as
  field objects.

• A clock class object may hold its equivalent libbabeltrace2 class
  (owned, shared reference).

• A trace class object may hold its equivalent libbabeltrace2 class
  (owned, shared reference).

• Boolean and integer field classes have an optional "key value"
  saving index.

  See the comment of the `ctf::src::KeyValSavingIndexes` alias to
  learn more.

• Dynamic-length, optional, and variant field classes have a saved
  key value index.

  Again, see the comment of `ctf::src::KeyValSavingIndexes` to
  learn more.

• Field class and field location mixins have an optional text
  location member.

  This will help with precise metadata stream error reporting.

• A trace class contains the maximum number of saved key values for
  its instance.

  Once more, see the comment of `ctf::src::KeyValSavingIndexes` to
  learn more.

The new API adds templateless aliases for all the configurable CTF IR
types, for example `src::ctf::FixedLenIntFc`.

The new API also offers user mixin agnostic functions to create all its
CTF IR objects. For example, call ctf::src::createDynLenBlobFc() to
create a `ctf::src` dynamic-length BLOB field class.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I854d5562778e05f4c438a4e937758bbce114f951
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7840
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12255
Tested-by: jenkins <jenkins@lttng.org>
CI-Build: Simon Marchi <simon.marchi@efficios.com>

Increase wise_enum limit to 512 enumerators

This is to support upcoming big enumerations.

This updated header was generated using the `create_generated.py` script
of the wise_enum 3.1.0 release as such:

    $ python3 create_generated.py 512 wise_enum_generated.h

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: If2391420fb58f4d2bfa98c4b09ba32300538d4fe
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12704
Tested-by: jenkins <jenkins@lttng.org>
CI-Build: Simon Marchi <simon.marchi@efficios.com>

cpp-common: add observable.hpp

Add the `Observable` class, which implements the observer pattern.  See
comments in the new file for details on usage.

Change-Id: I1f7a3faead9350f1f1217ffcf431fdcd3ddedab9
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12254
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

Add common `ctf::ir` CTF IR classes

This patch adds common CTF IR class templates to the new
`src/plugins/ctf/common/metadata/ctf-ir.hpp` header.

The purpose of those new class templates is to have a common CTF IR
class hierarchy for all the `ctf` plugin component classes. This CTF IR
model is based on the CTF 2 model.

Although the file looks intimidating, it's pretty straightforward:

• The class hierarchy, under the `ctf::ir` namespace, (omitting template
  parameters) is as such:

      TraceCls
      DataStreamCls
      EventRecordCls
      ClkCls
      FieldLoc
      StructFieldMemberCls
      VariantFcOpt
      Fc
        FixedLenBitArrayFc
          FixedLenBitMapFc
          FixedLenBoolFc
          FixedLenFloatFc
          FixedLenIntFc
            FixedLenUIntFc
            FixedLenSIntFc
        VarLengthIntFc
          VarLengthUIntFc
          VarLengthSIntFc
        StrFc
          NullTerminatedStrFc
          NonNullTerminatedStrFc
            StaticLenStrFc
            DynLenStrFc
        BlobFc
          StaticLenBlobFc
          DynLenBlobFc
        ArrayFc
          StaticLenArrayFc
          DynLenArrayFc
        StructFc
        OptionalFc
          OptionalWithBoolSelFc
          OptionalWithIntSelFc
            OptionalWithUIntSelFc
            OptionalWithSIntSelFc
        VariantFc
          VariantWithUIntSelFc
          VariantWithSIntSelFc

• Each class template has the `UserMixinsT` template parameter.

  `UserMixinsT` is expected to be a user mixin container, a type
  defining the following nested types (user mixins):

  ‣ `ClkCls`
  ‣ `DataStreamCls`
  ‣ `DynLenArrayFc`
  ‣ `DynLenBlobFc`
  ‣ `DynLenStrFc`
  ‣ `EventRecordCls`
  ‣ `Fc`
  ‣ `FieldLoc`
  ‣ `FixedLenBitArrayFc`
  ‣ `FixedLenBitMapFc`
  ‣ `FixedLenBoolFc`
  ‣ `FixedLenIntFc`
  ‣ `FixedLenUIntFc`
  ‣ `OptionalFc`
  ‣ `OptionalWithBoolSelFc`
  ‣ `OptionalWithSIntSelFc`
  ‣ `OptionalWithUIntSelFc`
  ‣ `StaticLenArrayFc`
  ‣ `StaticLenBlobFc`
  ‣ `StaticLenStrFc`
  ‣ `StructFc`
  ‣ `StructFieldMemberCls`
  ‣ `TraceCls`
  ‣ `VariantFcOpt`
  ‣ `VariantWithSIntSelFc`
  ‣ `VariantWithUIntSelFc`
  ‣ `VarLenIntFc`
  ‣ `VarLenUIntFc`

• Most class templates inherit a given user mixin. For example,
  `FixedLenBoolFc` inherits `UserMixinsT::FixedLenBoolFc`. This makes it
  possible for the user to inject data and methods into the class while
  keeping the hierarchy and common features.

• A class template which inherits a user mixin M has a constructor which
  accepts an instance of M by value to initialize this part of
  the object.

  If a class template C which inherits a user mixin also inherits
  another class template inheriting another user mixin, then the
  constructor of C accepts both mixins. For example,
  FixedLenUIntFc::FixedLenUIntFc() accepts three mixins: field class,
  fixed-length bit array field class, and fixed-length integer
  field class.

• `Fc` has the typical asXyz() and isXyz() methods.

  To make isXyz() methods more efficient, `FcType` enumerators are
  bitwise compositions of `FcTypeTraits` values (traits/features).

• The `FcVisitor` and `ConstFcVisitor` base classes are available to
  visit field classes through the virtual Fc::accept() methods.

• There are a few internal mixins to share common members:

  `WithAttrsMixin`:
      Optional attributes.

  `WithPrefDispBaseMixin`:
      Preferred display base.

  `WithMappingsMixin`:
      Integer mappings.

  `WithLibCls`:
      libbabeltrace2 class.

  `UIntFcMixin`:
      Unsigned integer field roles.

  `StaticLenFcMixin`:
      Integral length.

  `DynLenFcMixin`:
      Length field location.

• The API offers `DefUserMixins` which defines empty user mixins to act
  as a base user mixin container structure.

Now, this is how you would use this API:

• Define your own user mixin container structure which inherits
  `ctf::ir::DefUserMixins`, defining the user mixins you need to add
  data and methods to specific common classes.

• Define aliases for each `ctf::ir` class template you need, using your
  user mixin container structure as the `UserMixinsT`
  template parameter.

• Create convenient object creation functions to construct specific CTF
  IR objects from parameters, hiding the internal user mixin details.

As an example, this builds and works as expected:

    #include <string>
    #include <iostream>

    #include "plugins/ctf/common/metadata/ctf-ir.hpp"

    // user mixin container
    struct MyMixins : ctf::ir::DefUserMixins
    {
        // structure field class mixin
        class StructFc
        {
        public:
            explicit StructFc(std::string favoriteKebSinger) :
                _mFavoriteKebSinger {std::move(favoriteKebSinger)}
            {
            }

            const std::string& favoriteKebSinger() const noexcept
            {
                return _mFavoriteKebSinger;
            }

        private:
            std::string _mFavoriteKebSinger;
        };
    };

    // custom object aliases
    using MyNullTerminatedStrFc = ctf::ir::NullTerminatedStrFc<MyMixins>;
    using MyStructFc = ctf::ir::StructFc<MyMixins>;
    using MyTraceCls = ctf::ir::TraceCls<MyMixins>;

    int main()
    {
        // create structure field class, constructing a `MyMixins::StructFc`
        MyStructFc::MemberClasses memberClasses;

        memberClasses.emplace_back(
            MyMixins::StructFieldMemberCls {}, "meow",
            bt2c::makeUnique<MyNullTerminatedStrFc>(MyMixins::Fc {}));

        auto pktHeaderFc = bt2c::makeUnique<MyStructFc>(
            MyMixins::Fc {},
            MyMixins::StructFc {"Claude Dubois"},
            std::move(memberClasses)
        );

        // create trace class
        MyTraceCls tc {
            MyMixins::TraceCls {},
            bt2s::nullopt, bt2s::nullopt, bt2s::nullopt,
            {}, std::move(pktHeaderFc)
        };

        // read custom user property
        std::cout << tc.pktHeaderFc()->favoriteKebSinger() << '\n';
    }

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ib4785c9a2f675bdc1415b149e9b57de1339f475e
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7708
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12253
CI-Build: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>

cpp-common: Add Blob, StaticBlob, and DynamicBlob FC

This commit copies the implementation of the static and dynamic array
field class wrappers.

The FieldClassType enum size is specified to 64 bits to accommodate for
enumerator value larger than 32 bits. (e.g.
BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITHOUT_LENGTH_FIELD)

Here is the clang++ error
In file included from ../../../../src/cpp-common/bt2/trace-ir.hpp:19:
  ../../../../src/cpp-common/bt2/field-class.hpp:170:20: error: enumerator value evaluates to 2684354560, which cannot be narrowed to type 'int' [-Wc++11-narrowing]
      DynamicBlob = BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB,
                    ^
  ../../../../src/cpp-common/bt2/field-class.hpp:171:41: error: enumerator value evaluates to 6979321856, which cannot be narrowed to type 'int' [-Wc++11-narrowing]
      DynamicBlobWithoutLengthField = BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITHOUT_LENGTH_FIELD,
                                      ^
  ../../../../src/cpp-common/bt2/field-class.hpp:172:38: error: enumerator value evaluates to 11274289152, which cannot be narrowed to type 'int' [-Wc++11-narrowing]
      DynamicBlobWithLengthField = BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITH_LENGTH_FIELD,
                                   ^

Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Change-Id: I0a8f14e811e80ef71edbe1e20e2cfcfac1df80b3
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7620
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12703
Tested-by: jenkins <jenkins@lttng.org>
CI-Build: Simon Marchi <simon.marchi@efficios.com>

src/cpp-common/bt2: wrap variant with selector field loc. FC API

This patch adds what's needed to the C++ libbabeltrace2 wrappers to
wrap:

* bt_field_class_variant_with_selector_field_borrow_selector_field_location_const()
* bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
* bt_field_class_variant_with_selector_field_location_integer_signed_create()

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Id644771aa9537be21d73ba6cfe97a287c19f7240
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8019
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12702
Tested-by: jenkins <jenkins@lttng.org>
CI-Build: Simon Marchi <simon.marchi@efficios.com>

src/cpp-common/bt2: wrap option with selector field loc. FC API

This patch adds what's needed to the C++ libbabeltrace2 wrappers to
wrap:

* bt_field_class_option_with_selector_field_borrow_selector_field_location_const()
* bt_field_class_option_without_selector_field_location_create()
* bt_field_class_option_with_selector_field_location_bool_create()
* bt_field_class_option_with_selector_field_location_integer_unsigned_create()
* bt_field_class_option_with_selector_field_location_integer_signed_create()

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Iaf20856ee2533a061560abf79c91a69b2dab20b5
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8018
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12701
CI-Build: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>

src/cpp-common/bt2: wrap dynamic array with length field loc. FC API

This patch adds what's needed to the C++ libbabeltrace2 wrappers to
wrap:

* bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const()
* bt_field_class_array_dynamic_without_length_field_location_create()
* bt_field_class_array_dynamic_with_length_field_location_create()

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I7d731807165e22de9ec97d9cd83ec75e02c759b1
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8017
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12700
Tested-by: jenkins <jenkins@lttng.org>
CI-Build: Simon Marchi <simon.marchi@efficios.com>

src/cpp-common/bt2: add field location support

This patch adds the `bt2::ConstFieldLocation` wrapper class as well as
bt2::TraceClass::createFieldLocation().

I didn't implement a `bt2::CommonFieldLocation` template class because a
field location is immutable anyway, so we only need the const version.
bt2::TraceClass::createFieldLocation() returns a shared const field
location.

bt2::TraceClass::createFieldLocation() accepts a span of strings (either
`const char * const` or `const std::string`) to make the interface a
little nicer than a raw array of `const char *` and a matching size.
Creating a field location is a slow-path operation anyway.

Also adding bt2::wrap() accepting `const bt_field_location *`.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I160052c5a787114b52062aa87908c94a2af40f32
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8016
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12699

src/cpp-common/bt2/trace-ir.hpp: add nameSpace() methods where needed

The bt2::CommonEventClass::nameSpace() and
bt2::CommonStreamClass::nameSpace() methods make it possible to set and
get the namespace of event classes and stream classes (new feature
starting with MIP 1).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I6bd37d130fe8aaa8180181e41127e1ebfeb1ea4b
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8003
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12698

`ctf` plugin: add `ctf::IntRangeSet` class template

This new class template is conceptually the same as the libbabeltrace2
equivalent (`bt2::CommonIntegerRangeSet`), but it's templated and avoids
having to make libbabeltrace2 function calls to access data.

That being said, the contains() and intersects() methods don't have
their libbabeltrace2 equivalent.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I494dd1b236463eaf7c24d1143ed21afdd5e498b0
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7923
Reviewed-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12252

`ctf` plugin: add `ctf::IntRange` class template

This new class template is conceptually the same as the libbabeltrace2
equivalent (`bt2::ConstIntegerRange`), but it's templated and avoids
having to make libbabeltrace2 function calls to access data.

That being said, the contains() and intersects() methods don't have
their libbabeltrace2 equivalent.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ic2ab4b4b8dd97bce8dc69a1a7331fed8a46d9254
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7922
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12251

src/cpp-common: add JSON value requirement aliases

This patch defines JSON value requirement aliases of the generic value
requirement class templates (`val-req.hpp`) to validate JSON values.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I10226d38af706ed6547ac265d9e0d7e4c399179a
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7534
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12697

Add `bt2c::ValReq` class template system

This set of class templates makes it possible to get basic requirement
classes to validate JSON-like value objects, that is, a system of null,
boolean, unsigned/signed integer, real, string, array, and object value
objects.

All the class templates accept a `ValT` parameter which is the base type
of the objects to validate, as well as `ValOpsT`, a structure which
defines specific value operations. See the `bt2c::ValReq` class template
comment to learn the requirements of `ValOpsT`.

Having class templates will make it possible to create both:

• JSON value requirements, to validate a CTF2‑SPEC‑2.0 [1] metadata
  stream within the `ctf` plugin.

• libbabeltrace2 value object (`bt2::ConstValue`) requirements, to
  validate component initialization parameters, for example.

A value requirement (`bt2c::ValReq` instance; omitting the namespace for
the rest of this message) is an object which offers the validate()
method to validate some value object.

The current concrete requirement class templates are (validating some
value V):

`ValHasTypeReq`:
`AnyIntValReq`:
`UIntValReq`:
    Validates the type of V.

`SIntValReq`:
    Validates the type of V (unsigned or signed integer) and that the
    raw value of V is between -9,223,372,036,854,775,808 and
    9,223,372,036,854,775,807.

`IntValInRangeReq`:
    Validates the type of V and that the raw value of the integer value
    object V is within a given range.

`ScalarValInSetReq`:
    Validates the type of V and that the raw value of the scalar value
    object V is an element of a given set.

`ArrayValReq`:
    Validates the type of V, that the size of V is within a given range,
    and, optionally, that all the elements of V satisfy a given value
    requirement.

`ObjValReq`:
    Validates the type of V and that the properties of V satisfy a given
    set of property requirements (no missing mandatory property, no
    unknown property if not allowed, valid property value).

ValReq::validate() throws `TextParseError` using the text location
of the value (provided by `ValOpsT`) to validate when it fails.

`ArrayValReq` and `ObjValReq` accept zero or more shared value
requirements: a user of this API may extend `ValReq` to create a custom
value requirement (just implement the virtual _validate() method). A
custom value requirement may reuse existing value requirements
internally.

Each value requirement class C has its static shared() method which
accepts the same parameters as the constructor(s) of C and returns a
`ValReq::SP` instance. Those shared() methods are helpers to make the
usage site clearer, for example (assuming some custom aliases for
specific value object types):

    MyUIntValInRangeReq::shared(0, 255)

    // vs.

    std::make_shared<MyUIntValInRangeReq>(0, 255)

Of course this system is not meant to semantically validate some value.
Even JSON Schema [2], which barectf pushes to its limit for example [3],
cannot do that. But those value requirement classes can certainly remove
a lot of redundant code.

Here are a few examples of value requirement object construction and
corresponding error messages to grasp how to use this API (assume some
custom aliases starting with `Json`):

Simple type check:
    Code:
        JsonValHasTypeReq {ValType::Str}

    Error example:
        [1:1] Expecting a string.

Exactly `true`:
    Code:
        JsonBoolValInSetReq {true}

    Error examples:
        [1:1] Expecting a boolean.

        [1:1] Unexpected value `false`: expecting `true`.

Byte:
    Code:
        JsonUIntValInRangeReq {0, 255}

    Error examples:
        [1:1] Expecting an unsigned integer.

        [1:1] Integer 256 is too large: expecting at most 255.

Display base:
    Code:
        JsonUIntValInSetReq {{2, 8, 10, 16}}

    Error examples:
        [1:1] Expecting an unsigned integer.

        [1:1] Unexpected value 5: expecting 2, 8, 10, or 16.

Choice amongst three strings:
    Code:
        JsonStrValInSetReq {JsonStrValInSetReq::Set {
            "Patrick", "Alec", "Annie"
        }}

    Error examples:
        [1:1] Expecting a string.

        [1:1] Unexpected value `Yves`: expecting `Alec`, `Annie`, or
              `Patrick`.

CTF 2 UUID:
    Code:
        JsonArrayValReq {
            16,
            JsonUIntValInRangeReq::shared(0, 255)
        }

    Error examples:
        [1:1] Expecting an array.

        [1:1] Size of array (2) is too small: expecting at least 16
              elements.

        [1:1] Size of array (19) is too large: expecting at most 16
              elements.

        [1:36] In array element #11:
        [1:36] Expecting an unsigned integer.

        [1:42] In array element #13:
        [1:42] Integer 257 is too large: expecting at most 255.

CTF2-SPECRC-5.0 field location:
    Code:
        JsonArrayValReq {
            2, nonstd::nullopt,
            JsonValHasTypeReq::shared(ValType::Str)
        }

    Error examples:
        [1:1] Expecting an array.

        [1:1] Size of array (1) is too small: expecting at least 2
              elements.

        [1:11] In array element #2:
        [1:11] Expecting a string.

CTF2-SPECRC-5.0 clock class fragment:
    Code:
        JsonObjValReq {
            {
                {"type", {
                    JsonStrValInSetReq::shared("clock-class"),
                    true
                }},

                {"frequency", {
                    JsonUIntValInRangeReq::shared(1, nonstd::nullopt),
                    true
                }},

                {"name", {
                    JsonValHasTypeReq::shared(ValType::Str)
                }},

                {"description", {
                    JsonValHasTypeReq::shared(ValType::Str)
                }},

                {"uuid", {
                    JsonArrayValReq::shared(
                        16,
                        JsonUIntValInRangeReq::shared(0, 255)
                    )
                }},

                {"origin-is-unix-epoch", {
                    JsonValHasTypeReq::shared(ValType::Bool)
                }},

                {"offset", {
                    JsonObjValReq::shared({
                        {"seconds", {
                            JsonValHasTypeReq::shared(ValType::UInt)
                        }},

                        {"cycles", {
                            JsonValHasTypeReq::shared(ValType::UInt)
                        }},
                    })
                }},

                {"precision", {
                    JsonValHasTypeReq::shared(ValType::UInt)
                }},

                {"user-attributes", {
                    JsonValHasTypeReq::shared(ValType::Obj)
                }},

                {"extensions", {
                    JsonValHasTypeReq::shared(ValType::Obj)
                }},
            }
        }

    Error examples:
        [1:1] Expecting an object.

        [1:1] Missing mandatory object property `type`.

        [1:1] Missing mandatory object property `frequency`.

        [1:22] Unknown object property `meow`.

        [1:10] In object property `type`:
        [1:10] Unexpected value `salut`: expecting `clock-class`.

        [1:38] In object property `frequency`:
        [1:32] Expecting an unsigned integer.

        [1:54] In object property `offset`:
        [1:63] Unknown object property `meow`.

        [1:54] In object property `offset`:
        [1:66] In object property `seconds`:
        [1:66] Expecting an unsigned integer.

        [1:50] In object property `uuid`:
        [1:63] In array element #5:
        [1:63] Integer 301 is too large: expecting at most 255.

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html
[2]: https://json-schema.org/
[3]: https://github.com/efficios/barectf/tree/stable-3.0/barectf/schemas/config

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I71630fc51dafb79dd5ece10efbcf86f3f5933199
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8207
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12696

plugins: make text and utils component classes report support for MIP 1

Make the following component classes report they support MIP 1
(everything from the text and utils plugins):

 - sink.text.details
 - source.text.dmesg
 - sink.text.pretty
 - sink.utils.counter
 - sink.utils.dummy
 - filter.utils.muxer
 - filter.utils.trimmer

Change-Id: Ic2a6d3fbb2ac511d048d7b26de5811a64f24cc69
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7551
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7575

src.text.pretty: handle BLOB fields

Make the `src.text.pretty` components handle BLOB fields, by naively
printing all bytes in hex (without a 0x prefix).  Example output:

    da-ec-name: { blob_without_len = { 23 69 6e 63 6c 75 64 65 20 3c } }

It would be nice to limit the number of bytes dumped (and provide an
option to control it), because at some point it's useless for the user
to dump thousands of bytes on one line.  But this is enough to say that
the `src.text.pretty` component class supports BLOB field classes (and
MIP 1).

Change-Id: Ia83e6429336d71082c35aa11153c9646e98e9bce
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7581
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7574

graph/mip: make bt_get_greatest_operative_mip_version compute operative MIP version

bt_get_greatest_operative_mip_version is currently implemented assuming
that the only existing MIP version is 0.  It only checks that all
component descriptors support version 0, and then returns 0 as the
computed operative MIP version.

Since the library now supports MIP versions 0 and 1,
bt_get_greatest_operative_mip_version needs to actually compute the
greatest commonly supported version.  Implement something that will work
for any number of MIP versions.

Change validate_operative_mip_version_in_array to
get_supported_mip_version_ranges, make it is solely reponsible for
calling the component class' get_supported_mip_versions method and
append the resulting range set to the `supported_ranges` array.  Or, if
the component class doesn't implement that method, append a range set
with only `[0, 0]`.

Once this is done, we have an array with range sets representing the
supported MIP versions for each soon-to-be component.  Compute (in the
new function find_greatest_compatible_mip_version) the greatest commonly
supported version, if any.

Change-Id: Ief0fe9d3323b4e150fa08282531b55ef15be75cf
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7579
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7572

sink.text.details: handle missing variant field class option name

Starting with MIP 1, a variant field class option name is optional.
Handle this in `write.c`, showing "Unnamed" with the
"none"/"missing"/"empty" color.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I5990c6268d1bad21ca59220397af95a722b02b43
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8048
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12695

sink.text.details: show event class namespace

If the event class has namespace (a property introduced with MIP 1),
show it when dumping the event class info.

Example output:

    Event class `da-ec-name` (Namespace `da-ec-namespace`, ID 0):

Change-Id: Ief4363545a6379c16e229b29d8a2e0b121b4777f
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7531
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12694

sink.text.details: show stream class namespace

If the stream class has a namespace (a property introduced with MIP 1),
show it when dumping the stream class info.

Add a `with-stream-class-namespace` parameter to the component class,
controlling whether to show the namespace or not.

Example output:

    Trace class:
      Stream class `da-name` (Namespace `da-namespace`, ID 0):

Philippe updated the manual page to document the
`with-stream-class-namespace` parameter.

Change-Id: I1a3854d266f8f7a87be09ed44c70e03ac9cc6912
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7529
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12693

sink.text.details: handle BLOB field class type

Make the `sink.text.details` component class handle the BLOB field class
type, introduced in MIP 1.

When dumping the field class details, print the names of the new field
classes.  For the static BLOB field class, print the static length
value (similar to static arrays).

For BLOB fields:

 - if it is empty, print "Empty" (like a few other existing field kinds)
 - if it is not empty, print bytes as hex (without the 0x prefix), 16
   bytes per line.  This is similar to what `od -t x1` outputs, minus
   the address/offset column.

The output looks like this.  The field class part:

        static_blob: Static BLOB (Length 1)
        blob_without_len: Dynamic BLOB (no length field)
        blob_with_len: Dynamic BLOB (with length field)

The field part:

    static_blob: Length 1:
      fe
    blob_without_len: Length 2048:
      46 72 6f 6d 20 36 34 64 62 36 31 36 36 35 65 32
      38 62 62 63 39 63 62 64 32 62 64 32 62 34 39 31
      <snip>
    blob_with_len: Empty

Change-Id: Iae1f12e8b8d4d3a0612b935ddd45072dbc26df24
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7502
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
CI-Build: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12692

sink.text.details: handle field classes with field locations

Handle MIP 1 variant, option and dynamic array field classes.  They
have field locations instead of field paths.

The format used by write_field_location is based on write_field_path.

Change-Id: Ic2f6e1ed233a34ea4cc647f50eaf4027b9e5bff8
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7500
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12691

lib: make variant field class option name optional with MIP > 0

CTF2-SPEC-2.0 [1] calls for optionally named variant field class
option, therefore libbabeltrace2 should support this.

Before this patch, having a variant field class option name is a
precondition. This patch relaxes said precondition when the MIP version
is greater than zero.

Note that a structure field member class must still have a name.

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I7f6da1276f75e4c42f1e99c8d0ce1333c9bfee5f
Reviewed-on: https://review.lttng.org/c/babeltrace/+/8047
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12690

lib: add namespace property to event classes

Add the namespace property to event classes, with the intent to support
namespace properties on event record classes in CTF2‑SPEC‑2.0 [1].

Copy everything from the existing name property, and rename it to
"namespace."

Both new public functions have a `MIP >= 1` pre-condition check.

Philippe updated the documentation.

[1] https://diamon.org/ctf/CTF2-SPEC-2.0.html

Change-Id: I644446087b6071f2ccc70027b079615f3a33a2a7
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7381
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12689

lib: add namespace property to stream classes

Add the namespace property to stream classes, with the intent to support
namespace properties on data stream classes in CTF2‑SPEC‑2.0 [1].

Copy everything from the existing name property, and rename it to
"namespace."

Both new public functions have a `MIP >= 1` pre-condition check.

Philippe updated the documentation.

[1] https://diamon.org/ctf/CTF2-SPEC-2.0.html

Change-Id: Ibdfc9c924fc6347f5020c5ba06f14a7737cbf76b
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7380
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12688

lib: add BLOB field class types

Add support for BLOB field classes and fields, with the intent of
supporting CTF2‑SPEC‑2.0's BLOB field class types [1].

A BLOB is a sequence of binary data included as-is in the trace.

A BLOB field class has a media type property, which describes the kind
of content its instances hold.

There are three variations of a BLOB field class, analogous to the array
field classes:

 - static length BLOB
 - dynamic length BLOB without a length field
 - dynamic length BLOB with a length field

Static length BLOBs have a fixed length, set in the field class.

Dynamic length BLOBs have a variable length, set in each field instance
of the field class.

Dynamic length BLOBs with a length field have a length field location,
set in the field class, pointing to a preceding field that holds the
length of the BLOB.

Philippe updated the documentation.

[1] https://diamon.org/ctf/CTF2-SPEC-2.0.html#blob-fc

Change-Id: Ib9d7bd12d598fbc6b7ed5d80d8cdfcf294e4254d
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7350
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12687

src/cpp-common: add bt2c::bt2ValueFromJsonVal() function

This patch adds the bt2c::bt2ValueFromJsonVal() function which
converts a JSON value object (`bt2c::JsonVal`) to a Babeltrace 2
value object (`bt2::Value::Shared`, wrapping a shared `bt_value *`).

The JSON value classes are a superset of the Babeltrace 2 value ones:
there's a dedicated `bt2c::JsonNullVal` class, whereas
libbabeltrace2 uses a null value singleton, and `bt2c::JsonVal`
has a text location member.

This is part of an effort to support CTF2‑SPEC‑2.0 [1]. This function
will be useful to convert JSON user attributes to Babeltrace 2 values
directly (this step doesn't need validation).

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: If3f0859202aa2ef329048ca5775883059e2b6e50
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7486
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12686

src/cpp-common: make `bt2c::JsonVal` visitable

This patch adds the bt2c::JsonVal::accept() method which accepts a JSON
value visitor (`bt2c::JsonValVisitor`), dispatching to the virtual
bt2c::JsonVal::_accept() method.

This is part of an effort to support CTF2‑SPEC‑2.0 [1].

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I75462799f9433ee868b618ecba4ba63b5822b96c
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7485
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12685

src/cpp-common: add bt2c::parseJson() functions (value mode)

This patch adds two new versions of bt2c::parseJson() which accept the
same parameters as the current "listener mode" versions, except for a
missing listener, and return some resulting
JSON value (`bt2c::JsonVal`).

This is part of an effort to support CTF2‑SPEC‑2.0 [1]. It will be
easier to convert CTF 2 metadata stream fragments using JSON value
objects than using the listener mode version of bt2c::parseJson()
directly.

`baseOffset` is also added to the offset of a text location when
creating the text location of any JSON value object to create. This will
be needed when parsing a CTF 2 fragment: the line and column numbers are
local to the fragment, but the offset is from the beginning of the whole
metadata stream. Kind of confusing, but I wouldn't know what an RS byte
means in terms of lines/columns anyway (different text editor could
interpret it in different ways).

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I3e9662f6632d10f11c08c178342785886f664797
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7480
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12684

src/cpp-common: add `bt2c::JsonVal` class and derived classes

This patch adds a simple set of classes to contain decoded JSON values.

All the new classes inherit the abstract base `JsonVal`. A `JsonVal`
instance contains its type (enumeration) as well as a text location
(`TextLoc`) which indicates where the JSON value is located within some
original JSON text.

The complete class hierarchy is:

    JsonVal
      JsonNullVal
      JsonBoolVal
      JsonSIntVal
      JsonUIntVal
      JsonRealVal
      JsonStrVal
      JsonCompoundVal (template)
        ArrayJsonVal
        ObjJsonVal

In reality, `JsonNullVal`, `JsonBoolVal`, `JsonSIntVal`, `JsonUIntVal`,
`JsonRealVal`, and `JsonStrVal` are aliases of `JsonScalarVal` with
specific template parameters.

Each of the classes above has its own inner `UP` alias which is the type
of a unique pointer to a specific `const` JSON value.

`json-val.hpp` also offers various createJsonVal() functions which rely
on their parameter count and types to create specific JSON values.

Here's a simple usage example using default text locations:

    bt2c::JsonArrayVal::Container vals;

    // Append JSON signed integer value
    vals.push_back(bt2c::createJsonVal(23LL, bt2c::TextLoc {}));

    // Append JSON boolean value
    vals.push_back(bt2c::createJsonVal(true, bt2c::TextLoc {}));

    // Append JSON null value
    vals.push_back(bt2c::createJsonVal(bt2c::TextLoc {}));

    // Append JSON string value
    vals.push_back(bt2c::createJsonVal("salut la gang",
                                       bt2c::TextLoc {}));

    // Create JSON array value, moving `vals`
    auto arrayJsonVal = bt2c::createJsonVal(std::move(vals),
                                            bt2c::TextLoc {});

    // Inspect JSON array value, printing only JSON signed int. values
    for (auto& val : *arrayJsonVal) {
        // Type of `val` is `const Json::UP&`
        if (val->isSInt()) {
            std::cout << *val->asSInt() << std::endl;
        }
    }

This is part of an effort to support CTF2‑SPEC‑2.0 [1]. It will be
easier to convert CTF 2 metadata stream fragments using JSON value
objects than using the listener mode version of bt2c::parseJson()
directly.

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I35a431f881da33f516513529d1bec8bb2a905e26
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7466
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12683

src/cpp-common: add bt2c::parseJson() functions (listener mode)

This patch adds the bt2c::parseJson() functions in `parse-json.hpp`.

Those functions wrap the file-internal `bt2c::internal::JsonParser`
class of which an instance can parse a single JSON value, calling
specific methods of a JSON event listener as it processes. Internally,
`bt2c::internal::JsonParser` uses a string scanner (`bt2c::StrScanner`).

In searching for a simple JSON parsing solution, I could not find, as of
this date, any project which satisfies the following requirements out of
the box:

• Is well known, well documented, and well tested.

• Has an MIT-compatible license.

• Parses both unsigned and signed 64-bit integers (range
  -9,223,372,036,854,775,808 to 18,446,744,073,709,551,615).

• Provides an exact text location (offset, line number, column number)
  on parsing error (through logging and the message of an error cause).

• Provides an exact text location (offset, line number, column number)
  for each parsed value.

I believe the text locations are essential as this JSON parser will be
used to decode CTF2‑SPEC‑2.0 [1] metadata streams: because Babeltrace 2
will be a reference implementation of CTF 2, it makes sense to make an
effort to pinpoint the exact location of syntactic and semantic errors.

More specifically:

• JSON for Modern C++ (by Niels Lohmann) [2] doesn't support text
  location access, although there's a pending pull request (draft as of
  this date) to add such support [3].

• The exceptions of JsonCpp [4] don't contain a text location, only
  a message.

• SimpleJSON [5] doesn't offer text location access and seems to be an
  archived project.

• RapidJSON [6] doesn't offer text location access.

• yajl [7] could offer some form of text location access (offset, at
  least) with yajl_get_bytes_consumed(), remembering the last offset on
  our side, although I don't know how nice it would play
  with whitespaces.

  That being said, regarding integers, the `yajl_callbacks`
  structure [8] only contains a `yajl_integer` function pointer which
  receives a `long long` value (no direct 64-bit unsigned integer
  support). It's possible to set the `yajl_number` callback for any
  number, but the `yajl_double` callback gets disabled in that case, and
  the callback receives a string which needs further parsing on our
  side: this is pretty much what's implemented `bt2c::StrScanner`
  anyway.

At this point I stopped searching as I already had a working and tested
string scanner and, as you can see, without comments, `parse-json.hpp`
is only 231 lines of effective code and satisfies all the
requirements above.

You can test bt2c::parseJson() with a simple program like this:

    #include <iostream>
    #include <cstring>

    #include "parse-json.hpp"

    struct Printer
    {
        void onNull(const bt2c::TextLoc&)
        {
            std::cout << "null\n";
        }

        template <typename ValT>
        void onScalarVal(const ValT& val, const bt2c::TextLoc&)
        {
            std::cout << val << '\n';
        }

        void onArrayBegin(const bt2c::TextLoc&)
        {
            std::cout << "[\n";
        }

        void onArrayEnd(const bt2c::TextLoc&)
        {
            std::cout << "]\n";
        }

        void onObjBegin(const bt2c::TextLoc&)
        {
            std::cout << "{\n";
        }

        void onObjKey(const std::string& key,
                      const bt2c::TextLoc&)
        {
            std::cout << key << ": ";
        }

        void onObjEnd(const bt2c::TextLoc&)
        {
            std::cout << "}\n";
        }
    };

    int main(const int, const char * const * const argv)
    {
        Printer printer;

        bt2c::parseJson(argv[1], printer);
    }

Then:

    $ ./test-parse-json 23
    $ ./test-parse-json '"\u03c9 represents angular velocity"'
    $ ./test-parse-json '{"salut": [23, true, 42.4e-9, {"meow": null}]}'
    $ ./test-parse-json 18446744073709551615
    $ ./test-parse-json -9223372036854775808

Also try some parsing errors:

    $ ./test-parse-json '{"salut": [false, 42.4e-9, "meow": null}]}'
    $ ./test-parse-json 18446744073709551616
    $ ./test-parse-json -9223372036854775809
    $ ./test-parse-json '"invalid \u8dkf codepoint"'

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html
[2]: https://github.com/nlohmann/json
[3]: https://github.com/nlohmann/json/pull/3165
[4]: https://github.com/open-source-parsers/jsoncpp
[5]: https://github.com/nbsdx/SimpleJSON
[6]: https://rapidjson.org/
[7]: https://github.com/lloyd/yajl
[8]: https://lloyd.github.io/yajl/yajl-2.1.0/structyajl__callbacks.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Id32c2b64723ca50b044369c424fe046c0a183cce
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7411
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12682

src/cpp-common: add `bt2c::StrScanner` class

This patch adds the `bt2c::StrScanner` class, defined in
`str-scanner.hpp` and implemented in `str-scanner.cpp`.

A string scanner is a simple lexical scanner. This one is a
stripped-down version of yactfr's `yactfr::internal::StrScanner`,
stripped-down because yactfr uses this to parse TSDL, therefore it needs
more features.

What's left for the `bt2c::StrScanner` version is:

tryScanLitStr():
    Tries to scan a double-quoted literal string, possibly containing
    escape sequences.

tryScanConstInt():
    Tries to scan a constant unsigned or signed decimal integer string.

tryScanConstReal():
    Tries to scan a real number string.

tryScanToken():
    Tries to scan an exact string.

skipWhitespaces():
    Skips the next whitespaces.

See the specific comments in `str-scanner.hpp` for more details.

I could have used the `GScanner` API [1], as we do to parse the value of
the `--params` CLI option of `babeltrace2`, but:

• `yactfr::internal::StrScanner` is already working, tested,
  and documented.

  `bt2c::StrScanner` is a much lighter version of it.

• Should we ever make an effort to remove the GLib dependency, this part
  will already be done.

• The `GScanner` API doesn't support `\u` escape sequences in literal
  strings (needed for JSON strings) out of the box, so we'd need this
  part on our side anyway.

`bt2c::StrScanner` could eventually replace `GScanner` elsewhere in the
tree, but it would require a few more features (which already exist
in `yactfr::internal::StrScanner`, that is).

This is part of an effort to implement a JSON parser to
support CTF2‑SPEC‑2.0 [2].

[1]: https://docs.gtk.org/glib/struct.Scanner.html
[2]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I8317917124218618278611794f32a67be4b9a6dd
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7410
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12681

cpp-common/bt2c: add `Regex`

Add `Regex`, a class wrapping some features of `GRegex` (from glib).

The constructor aborts if the regex pattern fails to compile.  There is
a single `match()` method that returns whether or not the given string
matches the regex.

Change-Id: Ia4cb1542efa91fcf3849d82d047c871d9bf2dbd2
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12837
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2c/logging.hpp: add text location logging

This patch makes a `bt2c::Logger` instance hold a text location string
format (`bt2c::TextLocStrFmt`) and adds the logTextLoc(),
logErrorTextLocAndThrow(), and logErrorTextLocAndRethrow() methods which
accept a text location (`bt2c::TextLoc`) and make its equivalent
formatted string a prefix of the log message, for example:

    [13:38 @ 4776 bytes] Failed to parse this and that.

Because the text location string format member is specific to the text
location logging methods, it has an arbitrary default value
(`TextLocStrFmt::LineColNosAndOffset`) at construction time. You may
change it at any time with the textLocStrFmt() method.

Also adding the typical BT_CPPLOG*() macros to use the new methods with
`__FILE__`, `__func__`, and `__LINE__`.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I74c716929da2ef4cdd915c97811a466475539514
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12680

src/cpp-common: add bt2c::textLocStr() function

This new function formats a text location (`bt2c::TextLoc`) according
to some format amongst:

`bt2c::TextLocStrFmt::Offset`:
    Offset only.

`bt2c::TextLocStrFmt::LineColNosAndOffset`:
    Line/column numbers and offset.

`bt2c::TextLocStrFmt::LineColNos`:
    Line/column numbers only.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I8afeb43a71c7103135f903f7d4eeb73ccf9e24c3
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12679

src/cpp-common: add `bt2c::TextLoc` class

This patch adds the `bt2c::TextLoc` class, defined in `text-loc.hpp` and
implemented in `text-loc.cpp`.

A text location is a location within some text: an offset (in bytes), a
line number, and a column number.

This is part of an effort to implement a JSON parser to
support CTF2‑SPEC‑2.0 [1].

[1]: https://diamon.org/ctf/CTF2-SPEC-2.0.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ice9cab35041f1637d220deb6af8f52dbfc8cd290
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7408
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12678

lib: add enum bt_resolve_field_xref_status

Add the bt_resolve_field_xref_status enumeration, and use it throughout
the resolve-field-path.c file to make error handling more explicit, and
clearer, in my opinion.

Change-Id: I51ddb22ac41dde0f58ca2e5d7fb90267984412e9
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7304
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7328

lib: rename bt_resolve_field_path_context to bt_resolve_field_xref_context

In preparation to sharing some code with the field location resolving,
rename bt_resolve_field_path_context to bt_resolve_field_xref_context,
which will be used by both kinds of field cross-reference resolving.
Move it to its own file, which will be included by both.

Change-Id: Ia6b7e9fa9de76d16fa0244a66597c3a1bfb30271
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7303
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7327

lib: add new clock class origin API

Add the new API set define the origin of clock classes.  The origin is
now defined as a (namespace, name, unique-id) tuple.

If all three tuple elements are NULL, it means the origin is unknown or
undefined.  Otherwise, the origin is defined, and the name and unique-id
be non-NULL (namespace may be NULL).  There is one well-known origin,
the UNIX epoch, which is represented with the tuple
("babeltrace.org,2020", "unix-epoch", "").

The new API functions are (the numbers in square brackets represent the
MIP versions where these functions are allowed):

 - bt_clock_class_set_origin_unknown [0, 1]
 - bt_clock_class_set_origin_unix_epoch [0, 1]
 - bt_clock_class_set_origin [1]
 - bt_clock_class_get_origin_namespace [1]
 - bt_clock_class_get_origin_name [1]
 - bt_clock_class_get_origin_uid [1]

The existing function bt_clock_class_set_origin_is_unix_epoch (which
accepts a boolean) can still be used with MIP 1.  If passed true, it is
equivalent to bt_clock_class_set_origin_unix_epoch.  If passed false, it
is equivalent to bt_clock_class_set_origin_unknown.

The existing function bt_clock_class_origin_is_unix_epoch can still be
used with MIP 1.

Implementation-wise, replace the origin_is_unix_epoch boolean in struct
clock_class with the tuple of three strings.  The behavior of the API
for MIP 0 doesn't change, even if the underlying implementation does.
With MIP 0, the user is still restricted to set or get whether the
origin is the UNIX epoch or is unknown, and can't access the individual
components of the origin.

Philippe updated the documentation.

Change-Id: I1225b89a679952e877583ec8147008928a16eb45
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12677
Tested-by: jenkins <jenkins@lttng.org>

lib: restrict bt_clock_class_{g,s}et_uuid to MIP 0

Change-Id: Id689c9b470f03837355216a56e8e44b2724fd7cd
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12676
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

lib: record MIP version in clock class

Record the graph's MIP version in struct bt_clock_class, so that we can
check in in clock class API functions.

Change-Id: I88b6a2f79c24706a5e9eae9199ff7c3862afc0dc
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12675
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

lib: add bt_trace_{get,set}_uid

In MIP 1, the trace UID replaces the trace UUID.  A trace UID is an
arbitrary string.  When the trace UID is unset, its value is NULL.

 - Add bt_trace_get_uid and bt_trace_set_uid, to be used with MIP >= 1.

 - Make bt_trace_get_uuid and bt_trace_set_uuid only available with
   MIP == 0.

 - Add BT_ASSERT_PRE_UID_NON_NULL, for use in bt_trace_set_uid.

 - Handle the trace UID in lib-logging.c:format_trace.

 - Free the UID in destroy_trace.

Philippe updated the documentation.

Change-Id: I3d84a9e6f04d632d187c8adfc4d625ce4c4357c0
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/9972
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

lib: add field location-related functions

For each API function accepting a bt_field_class to refer to a length or
selector field, to create a variant, dynamic array or option field
class, add one or more equivalent ones accepting a bt_field_location.
For symmetry between the various field classes, go with separate
functions for "with" and "without" length/selector field locations,
rather than having one function that can take a NULL field location.

Add functions to borrow a field location from a variant, option or
dynamic array field class.

All the new functions have preconditions to require MIP version >= 1.
All the old functions dealing with field paths have preconditions to
require MIP version == 0.

Philippe updated the documentation.

Variants
--------

The existing bt_field_class_variant_create function deduces the type of
variant (without selector, with unsigned int selector, with signed int
selector) by looking at the selector field class' type.  This is not
possible by looking at a selector field location, since the field
class(es) the field location points to is/are not known at this time.
So, introduce three new functions to create a variant field class
(without, with unsigned, with signed).

Dynamic arrays
--------------

For symmetry with the other field classes, go with two separate
functions for with a length field location and without a length field
location, rather than a single function that can accept a NULL field
location.

Options
-------

For consistency in the naming with the other field classes, add the
bt_field_class_option_without_selector_field_location_create function.
It is functionally equivalent to the existing
bt_field_class_option_without_selector_create function.  Add three other
functions to match the three existing ones (with bool, with unsigned,
with signed).

Change-Id: Ib2df27fedc9aab3fefee3bd6d4dfb41fc359654b
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7302
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7208

lib: add logging format specifier for bt_field_location

Add the `format_field_location` function, to format a bt_field_location
object in logging messages.  Add the format specifier `L`, to format
bt_field_location objects in lib-logging format strings.

Change-Id: Ia874bea6a110e051cc19a0250e5cd831888f849f
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7317
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7296

lib: add field location API

Add API functions to create field location objects.

Field locations are created using bt_field_location_create.  The caller
must pass a trace class, which is used to verify that the MIP version
of the graph is >= 1.  The caller passes a (root) scope, and an array of
components, which are the names to get from the root of the scope to the
desired field.

Accessor functions are:

 - bt_field_location_get_scope
 - bt_field_location_get_component_count
 - bt_field_location_get_component_by_index

They are intended to be used by a component consuming a trace.

Philippe updated the documentation.

Change-Id: Iad554ce39e13194bd9cc056c2d6d43ba8b87effe
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7316
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7199

lib: add MIP 1 pre-conditions for functions taking a selector / length field class

MIP 1 deprecates referring to selector and length fields by passing a
field class pointer.

Add pre-condition checks for all functions that accept a selector or
length field class, to verify that the graph's MIP version is 0.

Add new macros in assert-cond.h to check for MIP version equality.

Philippe updated the documentation.

Change-Id: I980d8117c7460f79cfe802e2aba90eee71bc807a
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7315
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7198

lib: record effective MIP version in field and trace classes

We will need access to the MIP version in order to add MIP version
preconditions in various functions.

Change-Id: I47ecd962eb56826ea677fdeaa0dc28f7192eac7a
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7314
CI-Build: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7210

lib: increase maximal MIP version number

We are going to introduce MIP version 1, so adjust
bt_get_maximal_mip_version accordingly.

Change-Id: I6d698d252dbcd60c81b9355bc378e0a4fc7f425e
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7313
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7197

ctf: silence some -Wnull-dereference errors

Building with gcc 14.1.1 (Arch Linux package 14.1.1+r58+gfc9fb69ad62-1),
I get some `-Wnull-dereference` errors that seem bogus:

      CXX      plugins/ctf/fs-src/fs.lo
    In file included from /usr/include/c++/14.1.1/memory:78,
                     from /home/simark/src/babeltrace/src/cpp-common/bt2c/glib-up.hpp:10,
                     from /home/simark/src/babeltrace/src/plugins/ctf/fs-src/fs.cpp:19:
    In member function 'std::__uniq_ptr_impl<_Tp, _Dp>::pointer std::__uniq_ptr_impl<_Tp, _Dp>::release() [with _Tp = ctf_fs_trace; _Dp = std::default_delete<ctf_fs_trace>]',
        inlined from 'std::__uniq_ptr_impl<_Tp, _Dp>& std::__uniq_ptr_impl<_Tp, _Dp>::operator=(std::__uniq_ptr_impl<_Tp, _Dp>&&) [with _Tp = ctf_fs_trace; _Dp = std::default_delete<ctf_fs_trace>]' at /usr/include/c++/14.1.1/bits/unique_ptr.h:185:7,
        inlined from 'std::__uniq_ptr_data<_Tp, _Dp, <anonymous>, <anonymous> >& std::__uniq_ptr_data<_Tp, _Dp, <anonymous>, <anonymous> >::operator=(std::__uniq_ptr_data<_Tp, _Dp, <anonymous>, <anonymous> >&&) [with _Tp = ctf_fs_trace; _Dp = std::default_delete<ctf_fs_trace>; bool <anonymous> = true; bool <anonymous> = true]' at /usr/include/c++/14.1.1/bits/unique_ptr.h:237:24,
        inlined from 'std::unique_ptr<_Tp, _Dp>& std::unique_ptr<_Tp, _Dp>::operator=(std::unique_ptr<_Tp, _Dp>&&) [with _Tp = ctf_fs_trace; _Dp = std::default_delete<ctf_fs_trace>]' at /usr/include/c++/14.1.1/bits/unique_ptr.h:408:19,
        inlined from 'int ctf_fs_component_create_ctf_fs_trace(ctf_fs_component*, bt2::ConstArrayValue, const char*, bt_self_component*)' at /home/simark/src/babeltrace/src/plugins/ctf/fs-src/fs.cpp:1415:44:
    /usr/include/c++/14.1.1/bits/unique_ptr.h:211:17: error: potential null pointer dereference [-Werror=null-dereference]
      211 |         pointer __p = _M_ptr();
          |                 ^~~

      CXX      plugins/ctf/lttng-live/viewer-connection.lo
    In file included from /usr/include/c++/14.1.1/bits/stl_tempbuf.h:61,
                     from /usr/include/c++/14.1.1/memory:66,
                     from /home/simark/src/babeltrace/src/cpp-common/bt2s/make-unique.hpp:10,
                     from /home/simark/src/babeltrace/src/plugins/ctf/lttng-live/viewer-connection.cpp:16:
    In function 'void std::_Construct(_Tp*, _Args&& ...) [with _Tp = char; _Args = {}]',
        inlined from 'static _ForwardIterator std::__uninitialized_default_n_1<true>::__uninit_default_n(_ForwardIterator, _Size) [with _ForwardIterator = char*; _Size = long unsigned int]' at /usr/include/c++/14.1.1/bits/stl_uninitialized.h:666:23,
        inlined from 'static _ForwardIterator std::__uninitialized_default_n_1<true>::__uninit_default_n(_ForwardIterator, _Size) [with _ForwardIterator = char*; _Size = long unsigned int]' at /usr/include/c++/14.1.1/bits/stl_uninitialized.h:660:9,
        inlined from '_ForwardIterator std::__uninitialized_default_n(_ForwardIterator, _Size) [with _ForwardIterator = char*; _Size = long unsigned int]' at /usr/include/c++/14.1.1/bits/stl_uninitialized.h:712:20,
        inlined from '_ForwardIterator std::__uninitialized_default_n_a(_ForwardIterator, _Size, allocator<_Tp>&) [with _ForwardIterator = char*; _Size = long unsigned int; _Tp = char]' at /usr/include/c++/14.1.1/bits/stl_uninitialized.h:779:44,
        inlined from 'void std::vector<_Tp, _Alloc>::_M_default_append(size_type) [with _Tp = char; _Alloc = std::allocator<char>]' at /usr/include/c++/14.1.1/bits/vector.tcc:863:35,
        inlined from 'void std::vector<_Tp, _Alloc>::resize(size_type) [with _Tp = char; _Alloc = std::allocator<char>]' at /usr/include/c++/14.1.1/bits/stl_vector.h:1016:21,
        inlined from 'lttng_live_get_one_metadata_status lttng_live_get_one_metadata_packet(lttng_live_trace*, std::vector<char>&)' at /home/simark/src/babeltrace/src/plugins/ctf/lttng-live/viewer-connection.cpp:1028:16:
    /usr/include/c++/14.1.1/bits/stl_construct.h:119:7: error: null pointer dereference [-Werror=null-dereference]
      119 |       ::new((void*)__p) _Tp(std::forward<_Args>(__args)...);
          |       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Silence the warning at these specific spots to get the build going.

Change-Id: Ia46b4f420cfdd00202d0b915825ac3b995128291
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12776
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

tests/lib: convert `test-plugins` to C++

Convert the code to C++.  Re-write using the bt2 wrappers, use {fmt} for
string formatting.

Change-Id: I9b1925d6a2143ed1e23a5d1c0f70e35f143ff206
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12828
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

tests/lib: compile `test-plugins` as C++

Change-Id: Iecc2fcb29c0b2f4405739c9e0964094ebdf8886d
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12832
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2: add shared() methods on component classes

Change-Id: I5d2e264904bb54b65a41fb0dfe653fb7eb3e54b2
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12838
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

cpp-common/bt2c: add {fmt} formatter for `bt2::ConstValue`

I found this useful for debugging, but I suppose it could be used for
logging as well.

Change-Id: I83b8af3ed706c64f2f66347cf085d0291c9c09fe
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12831
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2: add `findAllPluginsFromFile()`

Add `findAllPluginsFromFile()`, a wrapper around
`bt_plugin_find_all_from_file()`.

Change-Id: I4794afe368dcb99c4c2441de58d9497d2cf40f38
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12830
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: cpp-common/bt2: make QueryExecutor take ConstValue params

Query executors can take values of any kind, not specifically map
values.  From the doc [1]:

    Unlike the params parameter of the
    bt_graph_add_*_component_*_port_added_listener() functions (see
    Graph), this parameter does not need to be a map value.

Change `ConstMapValue` to `ConstValue`.

[1] https://babeltrace.org/docs/v2.0/libbabeltrace2/group__api-qexec.html#gafb5d324988c2870d66d96c1eeda6f87a

Change-Id: I370182c4aa5df8957c025f59018e359463674156
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12829
CI-Build: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2: add plugin accessors to `bt2::ConstPluginSet`

Add the functionality to index and iterate a plugin set to get
plugins.

Change-Id: Ibfece01a234813a7571f26fd6b00cc4e319689a5
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12827
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests: remove problematic (and unnecessary) type annotation

With Python 3.4, we get:

    smarchi@ci-node-sles12sp5-amd64-1b-01:~/src/babeltrace> tests/utils/run-in-py-env.sh /usr/bin/python3 /home/smarchi/src/babeltrace/tests/data/plugins/src.ctf.lttng-live/lttng_live_server.py /home/smarchi/src/babeltrace/tests/data/plugins/src.ctf.lttng-live/list-sessions.json --port-file /tmp/test-live-list-sessions-server-port.AYNVeY --trace-path-prefix /home/smarchi/src/babeltrace/tests/data/ctf-traces
      File "/home/smarchi/src/babeltrace/tests/data/plugins/src.ctf.lttng-live/lttng_live_server.py", line 807
        self._creation_timestamp: int = creation_timestamp
                                ^
    SyntaxError: invalid syntax

This annotation is not necessary anyway, it can be inferred from the
right-hand side.

Change-Id: Ia613b1e6d2d2a7e5d7629f847db71b440a35d1fb
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12809
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>

Change syntax of some initialization lists to please g++ 4.8

Fixes errors of this kind:

      CXX      plugins/ctf/fs-src/data-stream-file.lo
    In file included from /home/smarchi/src/babeltrace/src/plugins/ctf/fs-src/data-stream-file.cpp:20:0:
    /home/smarchi/src/babeltrace/src/plugins/ctf/fs-src/data-stream-file.hpp: In constructor 'ctf_fs_ds_file_group::ctf_fs_ds_file_group(ctf_fs_trace*, ctf_stream_class*, uint64_t, ctf_fs_ds_index)':
    /home/smarchi/src/babeltrace/src/plugins/ctf/fs-src/data-stream-file.hpp:129:88: error: could not convert 'std::move<ctf_fs_ds_index&>((* & indexParam))' from 'std::remove_reference<ctf_fs_ds_index&>::type {aka ctf_fs_ds_index}' to 'std::vector<ctf_fs_ds_index_entry>'
             stream_id(streamInstanceId), ctf_fs_trace {trace}, index {std::move(indexParam)}
                                                                                            ^

It looks like g++ 4.8 thinks that we want to initialize the fields of
`ctf_fs_ds_index`, instead of calling the constructor.

Change-Id: I0c081506d75de4c5556917d7be85f079f6bd996d
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12795
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

cpp-common/bt2c: adjust syntax of operator"" to please g++ 4.8

Fixes:

      CXX      plugins/ctf/fs-src/data-stream-file.lo
    In file included from /home/smarchi/src/babeltrace/src/plugins/ctf/fs-src/data-stream-file.hpp:20:0,
                     from /home/smarchi/src/babeltrace/src/plugins/ctf/fs-src/data-stream-file.cpp:20:
    /home/smarchi/src/babeltrace/src/cpp-common/bt2c/data-len.hpp:179:23: error: missing space between '""' and suffix identifier
     static inline DataLen operator""_bits(const unsigned long long val) noexcept
                           ^

Change-Id: Iab7ab1273f13dd55735310f786a0bb4df63c967c
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12794
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

.gitignore: add some more IDE / tools related file

Change-Id: I223c98e0b94dceb879dbf9273e7bc3c23e17f780
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12774
Tested-by: jenkins <jenkins@lttng.org>

Re-format with clang-format 16

Change-Id: I5ea29c62b4fb8be6cd00acae8e75b4fa6c292325
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12536
Tested-by: Philippe Proulx <eeppeliteloop@gmail.com>

Normalize C/C++ include guards

Fix all C/C++ include guards so that they satisfy
`tools/check-include-guard.py`:

    $ tools/check-include-guards.sh &> /dev/null && echo 🎆
    🎆

Change-Id: I9cce2f459b08dec0ddf4dc05c3c85f2809dca943
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12633

tools: add include guard check script

Add `tools/check-include-guard.py`, whose task is to verify that the
include guards in a given file is formatted as we want.  Example:

    $ ./tools/check-include-guard.py ./src/plugins/ctf/fs-sink/fs-sink-trace.hpp
    In `#ifndef BABELTRACE_PLUGIN_CTF_FS_SINK_FS_SINK_TRACE_H` include guard line: expecting `#ifndef BABELTRACE_PLUGINS_CTF_FS_SINK_FS_SINK_TRACE_HPP`

`tools/check-include-guard.py` supports the `--fix` option, which makes
it try to fix the include guards in-place (mostly useful for that
initial pass where we have a lot of stuff to fix).

Add `tools/check-include-guards.sh`, whose task is to find all the
files we want to check include guards for, and call
`tools/check-include-guard.py` on them.

Limitations:

 - Only tested on GNU/Linux

Change-Id: I7a376fdcf50f92bda20ab50e529d73bcd2faeb03
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12632

doc/api/libbabeltrace2/DoxygenLayout.xml: use `topics` tab

It looks like the Doxygen project decided [1] to use the "topic"
terminology instead of "module" to avoid confusion with C++20 modules.

Add a `topics` tab to `DoxygenLayout.xml` because otherwise that
navigation tab won't show up.

Leaving `modules` for older Doxygen versions.

Also changing all the "module" terms to "API"/"page" in the actual
documentation to completely part from the old "module" Doxygen concept.

[1]: https://github.com/doxygen/doxygen/commit/6d80fc7e5d03c259b1a7280972e0b28884217655

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I6f535c42c2bd5f55e5727a3245a2d744b28c187c
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12630

test-field.sh: make sure bt_run_in_py_env() and bt_cli() succeed

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I26c033a56d2c214087db058bdc19d20312a6f0e1
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12535
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>

tests/utils/utils.sh: bt_diff(): validate that both files exist

Otherwise bt_diff() returns 0 (happy) with a nonexistent file.

This change reveals that `tests/plugins/src.ctf.fs/field/test-field.sh`
passes, but for the wrong reason: run_python() doesn't exist (I replaced
it with bt_run_in_py_env() a while ago), therefore that line doesn't
create any expectation file and bt_diff() returns 0. Change it to
use bt_run_in_py_env().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I259123f5c0946ece7f58e4ef185313bf26354b46
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12534
Tested-by: jenkins <jenkins@lttng.org>

common: remove `prio-heap.{c,h}`

Change-Id: Iec4f0a14efceb21aa67bedd58153e14bdd9662d9
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12538
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Tested-by: jenkins <jenkins@lttng.org>