X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream-class.h;h=ca0b9ef954581a4b8a53b30b2675f68cae6f23ed;hp=225ea45079a28c4d023194975ea9acc39adb56db;hb=44c440bc5fe8219cc17d1b786d91fd83c4c9860a;hpb=c800eb3790218d2f33df01e77ec38cbd43cc02a1 diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h index 225ea450..ca0b9ef9 100644 --- a/include/babeltrace/ctf-ir/stream-class.h +++ b/include/babeltrace/ctf-ir/stream-class.h @@ -32,632 +32,113 @@ #include -/* For bt_get() */ -#include - -/* For bt_visitor */ -#include +/* For bt_bool */ +#include #ifdef __cplusplus extern "C" { #endif -/** -@defgroup ctfirstreamclass CTF IR stream class -@ingroup ctfir -@brief CTF IR stream class. - -@code -#include -@endcode - -@note -See \ref ctfwriterstreamclass which documents additional CTF IR stream -class functions exclusive to the CTF writer mode. - -A CTF IR stream class is a template that you -can use to create concrete \link ctfirstream CTF IR streams\endlink. - -A stream class has the following properties, both of which \em must -be unique amongst all the stream classes contained in the same -\link ctfirtraceclass CTF IR trace class\endlink: - -- A \b name. -- A numeric \b ID. - -In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink -contains zero or more stream classes, -and a stream class contains zero or more -\link ctfireventclass event classes\endlink. -You can add an event class -to a stream class with bt_stream_class_add_event_class(). -You can add a stream class to a trace class with -bt_trace_add_stream_class(). - -A stream class owns three \link ctfirfieldtypes field types\endlink: - -- An optional stream packet context field type, which - represents the \c stream.packet.context CTF scope. -- An optional stream event header field type, which - represents the \c stream.event.header CTF scope. -- An optional stream event context field type, which - represents the \c stream.event.context CTF scope. - -Those three field types \em must be structure field types as of -Babeltrace \btversion. - -As per the CTF specification, the event header field type \em must -contain a field named \c id if the stream class contains more than one -event class. - -As a reminder, here's the structure of a CTF packet: - -@imgpacketstructure - -Before you can create a stream from a stream class with -bt_stream_create(), you \em must add the prepared stream class to a -trace class by calling bt_trace_add_stream_class(). - -As with any Babeltrace object, CTF IR stream class objects have -reference -counts. See \ref refs to learn more about the reference counting -management of Babeltrace objects. - -The following functions \em freeze their stream class parameter on -success: - -- bt_trace_add_stream_class() -- bt_event_create() -- bt_writer_create_stream() - (\link ctfwriter CTF writer\endlink mode only) - -You cannot modify a frozen stream class: it is considered immutable, -except for: - -- Adding an event class to it with - bt_stream_class_add_event_class(). If the stream class's parent - \link ctfirtraceclass trace class\endlink is static, however, - you cannot call bt_stream_class_add_event_class() - (see bt_trace_is_static() and bt_trace_set_is_static()). -- \link refs Reference counting\endlink. - -@sa ctfirstream -@sa ctfireventclass -@sa ctfirtraceclass -@sa ctfwriterstreamclass - -@file -@brief CTF IR stream class type and functions. -@sa ctfirstreamclass - -@addtogroup ctfirstreamclass -@{ -*/ - -/** -@struct bt_stream_class -@brief A CTF IR stream class. -@sa ctfirstreamclass -*/ +struct bt_trace; struct bt_stream_class; struct bt_event_class; -struct bt_clock; +struct bt_clock_class; struct bt_event_header_field; struct bt_packet_context_field; -/** -@name Creation and parent access functions -@{ -*/ - -/** -@brief Creates a default CTF IR stream class named \p name­, or a - default unnamed stream class if \p name is \c NULL. - -On success, the packet context field type of the created stream class -has the following fields: - -- timestamp_begin: a 64-bit unsigned integer field type. -- timestamp_end: a 64-bit unsigned integer field type. -- content_size: a 64-bit unsigned integer field type. -- packet_size: a 64-bit unsigned integer field type. -- events_discarded: a 64-bit unsigned integer field type. - -On success, the event header field type of the created stream class -has the following fields: - -- code: a 32-bit unsigned integer field type. -- timestamp: a 64-bit unsigned integer field type. +extern struct bt_stream_class *bt_stream_class_create(struct bt_trace *trace); -You can modify those default field types after the stream class is -created with bt_stream_class_set_packet_context_field_type() and -bt_stream_class_set_event_header_field_type(). - -@param[in] name Name of the stream class to create (copied on success), - or \c NULL to create an unnamed stream class. -@returns Created default stream class, or \c NULL on error. - -@postsuccessrefcountret1 - -@sa bt_stream_class_create_empty(): Creates an empty stream class. -*/ -extern struct bt_stream_class *bt_stream_class_create(const char *name); +extern struct bt_stream_class *bt_stream_class_create_with_id( + struct bt_trace *trace, uint64_t id); extern struct bt_trace *bt_stream_class_borrow_trace( struct bt_stream_class *stream_class); -/** -@brief Returns the parent CTF IR trace class of the CTF IR stream - class \p stream_class. - -It is possible that the stream class was not added to a trace class -yet, in which case this function returns \c NULL. You can add a -stream class to a trace class with -bt_trace_add_stream_class(). - -@param[in] stream_class Stream class of which to get the parent - trace class. -@returns Parent trace class of \p stream_class, - or \c NULL if \p stream_class was not - added to a trace class yet or on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -@postsuccessrefcountretinc - -@sa bt_trace_add_stream_class(): Add a stream class to - a trace class. -*/ -static inline -struct bt_trace *bt_stream_class_get_trace( - struct bt_stream_class *stream_class) -{ - return bt_get(bt_stream_class_borrow_trace(stream_class)); -} - -/** @} */ - -/** -@name Properties functions -@{ -*/ - -/** -@brief Returns the name of the CTF IR stream class \p stream_class. - -On success, \p stream_class remains the sole owner of the returned -string. - -@param[in] stream_class Stream class of which to get the name. -@returns Name of stream class \p stream_class, or - \c NULL if \p stream_class is unnamed or - on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} - -@sa bt_stream_class_set_name(): Sets the name of a given - stream class. -*/ extern const char *bt_stream_class_get_name( struct bt_stream_class *stream_class); -/** -@brief Sets the name of the CTF IR stream class - \p stream_class to \p name, or resets the name of - \p stream_class. - -If \p name is not \c NULL, it must be unique amongst the names of all -the stream classes of the trace class to which you eventually add -\p stream_class. - -@param[in] stream_class Stream class of which to set the name. -@param[in] name Name of the stream class (copied on success), or - \c NULL to reset the name of \p stream_class - (make it unnamed). -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prehot{stream_class} -@postrefcountsame{stream_class} - -@sa bt_stream_class_get_name(): Returns the name of a given - stream class. -*/ -extern int bt_stream_class_set_name( - struct bt_stream_class *stream_class, const char *name); - -/** -@brief Returns the numeric ID of the CTF IR stream class \p stream_class. - -@param[in] stream_class Stream class of which to get the numeric ID. -@returns ID of stream class \p stream_class, or a - negative value on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} - -@sa bt_stream_class_set_id(): Sets the numeric ID of a given - stream class. -*/ -extern int64_t bt_stream_class_get_id( - struct bt_stream_class *stream_class); - -/** -@brief Sets the numeric ID of the CTF IR stream class - \p stream_class to \p id. - -\p id must be unique amongst the IDs of all the stream classes -of the trace class to which you eventually add \p stream_class. +extern int bt_stream_class_set_name(struct bt_stream_class *stream_class, + const char *name); -@param[in] stream_class Stream class of which to set the numeric ID. -@param[in] id ID of the stream class. -@returns 0 on success, or a negative value on error. +extern bt_bool bt_stream_class_assigns_automatic_event_class_id( + struct bt_stream_class *stream_class); -@prenotnull{stream_class} -@prehot{stream_class} -@pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX). -@postrefcountsame{stream_class} +extern int bt_stream_class_set_assigns_automatic_event_class_id( + struct bt_stream_class *stream_class, bt_bool value); -@sa bt_stream_class_get_id(): Returns the numeric ID of a given - stream class. -*/ -extern int bt_stream_class_set_id( - struct bt_stream_class *stream_class, uint64_t id); +extern bt_bool bt_stream_class_assigns_automatic_stream_id( + struct bt_stream_class *stream_class); -/** @} */ +extern int bt_stream_class_set_assigns_automatic_stream_id( + struct bt_stream_class *stream_class, bt_bool value); -/** -@name Contained field types functions -@{ -*/ +extern uint64_t bt_stream_class_get_id(struct bt_stream_class *stream_class); extern struct bt_field_type *bt_stream_class_borrow_packet_context_field_type( struct bt_stream_class *stream_class); -/** -@brief Returns the packet context field type of the CTF IR stream class - \p stream_class. - -@param[in] stream_class Stream class of which to get the packet - context field type. -@returns Packet context field type of \p stream_class, - or \c NULL if \p stream_class has no packet context - field type or on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -@post On success, if the return value is a field type, its - reference count is incremented. - -@sa bt_stream_class_set_packet_context_field_type(): Sets the packet - context field type of a given stream class. -*/ -static inline -struct bt_field_type *bt_stream_class_get_packet_context_field_type( - struct bt_stream_class *stream_class) -{ - return bt_get(bt_stream_class_borrow_packet_context_field_type( - stream_class)); -} - -extern -struct bt_packet_context_field *bt_stream_class_create_packet_context_field( - struct bt_stream_class *stream_class); - -/** -@brief Sets the packet context field type of the CTF IR stream class - \p stream_class to \p packet_context_type, or unsets the current packet - context field type from \p stream_class. - -If \p packet_context_type is \c NULL, then this function unsets the current -packet context field type from \p stream_class, effectively making -\p stream_class a stream class without a packet context field type. - -As of Babeltrace \btversion, if \p packet_context_type is not \c NULL, -\p packet_context_type \em must be a CTF IR structure field type object. - -@param[in] stream_class Stream class of which to set the packet - context field type. -@param[in] packet_context_type Packet context field type, or \c NULL to unset - the current packet context field type. -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prehot{stream_class} -@pre \p packet_context_type, if not \c NULL, is a CTF IR - structure field type. -@postrefcountsame{stream_class} -@post On success, if \p packet_context_type is not \c NULL, - the reference count of \p packet_context_type is incremented. - -@sa bt_stream_class_get_packet_context_field_type(): Returns the packet - context field type of a given stream class. -*/ extern int bt_stream_class_set_packet_context_field_type( struct bt_stream_class *stream_class, - struct bt_field_type *packet_context_type); + struct bt_field_type *field_type); extern struct bt_field_type * bt_stream_class_borrow_event_header_field_type( struct bt_stream_class *stream_class); -/** -@brief Returns the event header field type of the CTF IR stream class - \p stream_class. - -@param[in] stream_class Stream class of which to get the event header - field type. -@returns Event header field type of \p stream_class, - or \c NULL if \p stream_class has no event header field - type or on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -@post On success, if the return value is a field type, its - reference count is incremented. - -@sa bt_stream_class_set_event_header_field_type(): Sets the event - header field type of a given stream class. -*/ -static inline -struct bt_field_type *bt_stream_class_get_event_header_field_type( - struct bt_stream_class *stream_class) -{ - return bt_get(bt_stream_class_borrow_event_header_field_type( - stream_class)); -} - -/** -@brief Sets the event header field type of the CTF IR stream class - \p stream_class to \p event_header_type, or unsets the current event - header field type from \p stream_class. - -If \p event_header_type is \c NULL, then this function unsets the current -event header field type from \p stream_class, effectively making \p stream_class -a stream class without a event header field type. - -As of Babeltrace \btversion, if \p event_header_type is not \c NULL, -\p event_header_type \em must be a CTF IR structure field type object. - -@param[in] stream_class Stream class of which to set the event - header field type. -@param[in] event_header_type Event header field type, or \c NULL to unset - the current event header field type. -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prehot{stream_class} -@pre \p event_header_type, if not \c NULL, is a CTF IR - structure field type. -@postrefcountsame{stream_class} -@post On success, if \p event_header_type is not \c NULL, - the reference count of \p event_header_type is incremented. - -@sa bt_stream_class_get_event_header_field_type(): Returns the event - header field type of a given stream class. -*/ extern int bt_stream_class_set_event_header_field_type( struct bt_stream_class *stream_class, - struct bt_field_type *event_header_type); - -extern struct bt_event_header_field *bt_stream_class_create_event_header_field( - struct bt_stream_class *stream_class); + struct bt_field_type *field_type); extern struct bt_field_type * -bt_stream_class_borrow_event_context_field_type( +bt_stream_class_borrow_event_common_context_field_type( struct bt_stream_class *stream_class); -/** -@brief Returns the event context field type of the CTF IR stream class - \p stream_class. - -@param[in] stream_class Stream class of which to get the event context - field type. -@returns Event context field type of \p stream_class, - or \c NULL if \p stream_class has no event context field - type or on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -@post On success, if the return value is a field type, - its reference count is incremented. - - -@sa bt_stream_class_set_event_context_field_type(): Sets the event - context field type of a given stream class. -*/ -static inline -struct bt_field_type * -bt_stream_class_get_event_context_field_type( - struct bt_stream_class *stream_class) -{ - return bt_get(bt_stream_class_borrow_event_context_field_type( - stream_class)); -} - -/** -@brief Sets the event context field type of the CTF IR stream class - \p stream_class to \p event_context_type, or unsets the current event - context field type from \p stream_class. - -If \p event_context_type is \c NULL, then this function unsets the current -event context field type from \p stream_class, effectively making \p -stream_class a stream class without a event context field type. - -As of Babeltrace \btversion, if \p event_context_type is not \c NULL, -\p event_context_type \em must be a CTF IR structure field type object. - -@param[in] stream_class Stream class of which to set the packet - context field type. -@param[in] event_context_type Event context field type, or \c NULL to unset - the current event context field type. -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prehot{stream_class} -@pre \p event_context_type, if not \c NULL, is a CTF IR - structure field type. -@postrefcountsame{stream_class} -@post On success, if \p event_context_type is not \c NULL, - the reference count of \p event_context_type is incremented. - -@sa bt_stream_class_get_event_context_field_type(): Returns the event context - field type of a given stream class. -*/ -extern int bt_stream_class_set_event_context_field_type( +extern int bt_stream_class_set_event_common_context_field_type( struct bt_stream_class *stream_class, - struct bt_field_type *event_context_type); - -/** @} */ - -/** -@name Event class children functions -@{ -*/ - -/** -@brief Returns the number of event classes contained in the - CTF IR stream class \p stream_class. + struct bt_field_type *field_type); -@param[in] stream_class Stream class of which to get the number - of children event classes. -@returns Number of children event classes - contained in \p stream_class, or - a negative value on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -*/ -extern int64_t bt_stream_class_get_event_class_count( +extern uint64_t bt_stream_class_get_event_class_count( struct bt_stream_class *stream_class); extern struct bt_event_class *bt_stream_class_borrow_event_class_by_index( struct bt_stream_class *stream_class, uint64_t index); -/** -@brief Returns the event class at index \p index in the CTF IR stream - class \p stream_class. - -@param[in] stream_class Stream class of which to get the event class. -@param[in] index Index of the event class to find. -@returns Event class at index \p index, or \c NULL - on error. - -@prenotnull{stream_class} -@pre \p index is lesser than the number of event classes contained in the - stream class \p stream_class (see - bt_stream_class_get_event_class_count()). -@postrefcountsame{stream_class} -@postsuccessrefcountretinc - -@sa bt_stream_class_get_event_class_by_id(): Finds an event class - by ID. -*/ -static inline -struct bt_event_class *bt_stream_class_get_event_class_by_index( - struct bt_stream_class *stream_class, uint64_t index) -{ - return bt_get(bt_stream_class_borrow_event_class_by_index(stream_class, - index)); -} - extern struct bt_event_class *bt_stream_class_borrow_event_class_by_id( struct bt_stream_class *stream_class, uint64_t id); -/** -@brief Returns the event class with ID \c id found in the CTF IR stream - class \p stream_class. - -@param[in] stream_class Stream class of which to get the event class. -@param[in] id ID of the event class to find. -@returns Event class with ID \p id, or \c NULL - on error. - -@prenotnull{stream_class} -@postrefcountsame{stream_class} -@postsuccessrefcountretinc -*/ -static inline -struct bt_event_class *bt_stream_class_get_event_class_by_id( - struct bt_stream_class *stream_class, uint64_t id) -{ - return bt_get(bt_stream_class_borrow_event_class_by_id(stream_class, - id)); -} - -/** -@brief Adds the CTF IR event class \p event_class to the - CTF IR stream class \p stream_class. - -On success, \p event_class becomes the child of \p stream_class. - -You can only add a given event class to one stream class. - -You can call this function even if \p stream_class is frozen. Adding -event classes is the only operation that is permitted -on a frozen stream class. - -This function tries to resolve the needed -\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field -types that are found anywhere in the context or payload field -types of \p event_class. If any automatic resolving fails: - -- If the needed field type should be found in one of the root field - types of \p event_class or \p stream_class, this function fails. -- If \p stream_class is the child of a - \link ctfirtraceclass CTF IR trace class\endlink (it was added - with bt_trace_add_stream_class()), this function fails. -- If \p stream_class is not the child of a trace class yet, the - automatic resolving is reported to the next call to - bt_trace_add_stream_class() with \p stream_class. - -@param[in] stream_class Stream class to which to add \p event_class. -@param[in] event_class Event class to add to \p stream_class. -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prenotnull{event_class} -@prehot{event_class} -@postrefcountsame{stream_class} -@postsuccessrefcountinc{event_class} -@postsuccessfrozen{event_class} -*/ -extern int bt_stream_class_add_event_class( +extern int bt_stream_class_set_default_clock_class( struct bt_stream_class *stream_class, - struct bt_event_class *event_class); + struct bt_clock_class *clock_class); + +extern struct bt_clock_class *bt_stream_class_borrow_default_clock_class( + struct bt_stream_class *stream_class); -/** @} */ +extern bt_bool bt_stream_class_default_clock_is_always_known( + struct bt_stream_class *stream_class); -/** -@name Misc. function -@{ -*/ +extern bt_bool bt_stream_class_packets_have_discarded_event_counter_snapshot( + struct bt_stream_class *stream_class); -/** -@brief Accepts the visitor \p visitor to visit the hierarchy of the - CTF IR stream class \p stream_class. +extern int bt_stream_class_set_packets_have_discarded_event_counter_snapshot( + struct bt_stream_class *stream_class, bt_bool value); -This function traverses the hierarchy of \p stream_class in pre-order -and calls \p visitor on each element. +extern bt_bool bt_stream_class_packets_have_packet_counter_snapshot( + struct bt_stream_class *stream_class); -The stream class itself is visited first, and then all its children -event classes. +extern int bt_stream_class_set_packets_have_packet_counter_snapshot( + struct bt_stream_class *stream_class, bt_bool value); -@param[in] stream_class Stream class to visit. -@param[in] visitor Visiting function. -@param[in] data User data. -@returns 0 on success, or a negative value on error. +extern bt_bool bt_stream_class_packets_have_default_beginning_clock_value( + struct bt_stream_class *stream_class); -@prenotnull{stream_class} -@prenotnull{visitor} -*/ -extern int bt_stream_class_visit(struct bt_stream_class *stream_class, - bt_visitor visitor, void *data); +extern int bt_stream_class_set_packets_have_default_beginning_clock_value( + struct bt_stream_class *stream_class, bt_bool value); -/** @} */ +extern bt_bool bt_stream_class_packets_have_default_end_clock_value( + struct bt_stream_class *stream_class); -/** @} */ +extern int bt_stream_class_set_packets_have_default_end_clock_value( + struct bt_stream_class *stream_class, bt_bool value); #ifdef __cplusplus }