In an attempt to isolate the CTF writer API from the general API
(sometimes called the non-writer API), let's make the clock object a
compound object made of:
1. A clock class object, a new object which holds all the static
properties of a clock.
2. A single value.
You can only use the clock object with the functions of the CTF writer
API:
* bt_ctf_writer_add_clock()
* bt_ctf_stream_class_set_clock()
* bt_ctf_stream_class_get_clock()
The purpose of a clock object is to automate the setting of the
`timestamp` field in event headers part of a CTF writer object. The
clock object has nothing to do with the non-writer part of the API, that
is, the one you use to write BT component classes and plugins.
The functions above do this from now on:
* bt_ctf_writer_add_clock(): Calls bt_ctf_trace_add_clock_class() on
the clock class of the clock object parameter.
* bt_ctf_stream_class_set_clock(): Registers the clock object as the
current stream class's clock and maps the field named `timestamp`
in the current event header field type to this same clock class.
NOTE: If you set a custom event header field type after having called
bt_ctf_stream_class_set_clock(), this mapping is LOST.
When you call bt_ctf_stream_append_event(), the `timestamp` field of the
event header is automatically set (from the stream class's clock's
current value) if, and only if all the following conditions are
satisfied:
1. The event header field `timestamp` exists and is an integer field.
2. The stream's class has a registered clock (set with
bt_ctf_stream_class_set_clock()).
3. The event header field `timestamp` has its type mapped to a clock
class which is also the clock class of the stream's class's
registered clock.
4. The event header field `timestamp` is NOT set.
From now on you cannot set a stream class's clock and add this stream
class to a trace which was not created by a CTF writer. This enforces
the fact that bt_ctf_stream_class_set_clock() and
bt_ctf_stream_class_get_clock() are only part of the CTF writer API.
A clock _class_ has no value, although you can create individual clock
value objects linked to a specific clock class with
bt_ctf_clock_value_create(). Note that everything related to clock value
objects has zero effects on the CTF writer API.
What would be named bt_ctf_clock_class_*_offset() after this massive
renaming operation is named bt_ctf_clock_class_*_offset_cycles() for
those functions to be self-documented, and for them to have names that
are parallel with bt_ctf_clock_class_*_offset_s().
bt_ctf_field_type_integer_*_mapped_clock() functions are renamed
to bt_ctf_field_type_integer_*_mapped_clock_class().
Component classes must now include `babeltrace/ctf-ir/clock-class.h`
to deal with clock class objects.
Programs which use the CTF writer API must still include
`babeltrace/ctf-writer/clock.h`.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>