X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=690c88a32680fc12bc4758f15628dc31a7e390f9;hp=949672266188b879f6faabe658d82c1890312a8b;hb=44c440bc5fe8219cc17d1b786d91fd83c4c9860a;hpb=c800eb3790218d2f33df01e77ec38cbd43cc02a1 diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index 94967226..690c88a3 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -30,1026 +30,95 @@ * http://www.efficios.com/ctf */ -/* For bt_get() */ -#include - -/* For bt_visitor */ -#include - -/* For bt_bool */ +/* For bt_bool, bt_uuid */ #include + #include #ifdef __cplusplus extern "C" { #endif -/** -@defgroup ctfirtraceclass CTF IR trace class -@ingroup ctfir -@brief CTF IR trace class. - -@code -#include -@endcode - -A CTF IR trace class is a descriptor of -traces. - -You can obtain a trace class in two different modes: - -- Normal mode: use bt_trace_create() to create a - default, empty trace class. -- CTF writer mode: use bt_writer_get_trace() to - get the trace class created by a given CTF writer object. - -A trace class has the following properties: - -- A \b name. -- A native byte order: all the - \link ctfirfieldtypes field types\endlink eventually part of the trace - class with a byte order set to #BT_BYTE_ORDER_NATIVE have this - "real" byte order. -- A \b UUID. -- An \b environment, which is a custom key-value mapping. Keys are - strings and values can be strings or integers. - -In the Babeltrace CTF IR system, a trace class contains zero or more -\link ctfirstreamclass stream classes\endlink, 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(). - -You can access the streams of a trace, that is, the streams which were -created from the trace's stream classes with bt_stream_create(), -with bt_trace_get_stream_by_index(). - -A trace class owns the trace packet header -\link ctfirfieldtypes field type\endlink, which represents the -\c trace.packet.header CTF scope. This field type describes the -trace packet header fields of the traces that this trace class -describes. - -The trace packet header field type \em must be a structure field type as -of Babeltrace \btversion. - -As per the CTF specification, the trace packet header field type \em -must contain a field named \c stream_id if the trace class contains more -than one stream class. - -As a reminder, here's the structure of a CTF packet: - -@imgpacketstructure - -A trace class also contains zero or more -\link ctfirclockclass CTF IR clock classes\endlink. - -@todo -Elaborate about clock classes irt clock values. - -As with any Babeltrace object, CTF IR trace 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 trace class parameter on -success: - -- bt_trace_add_stream_class() -- bt_writer_create_stream() - (\link ctfwriter CTF writer\endlink mode only) - -You cannot modify a frozen trace class: it is considered immutable, -except for: - -- Adding a stream class to it with - bt_trace_add_stream_class(). -- Adding a CTF IR clock class to it with bt_trace_add_clock_class(). -- \link refs Reference counting\endlink. - -@sa ctfirstreamclass -@sa ctfireventclass -@sa ctfirclockclass - -@file -@brief CTF IR trace class type and functions. -@sa ctfirtraceclass - -@addtogroup ctfirtraceclass -@{ -*/ - -/** -@struct bt_trace -@brief A CTF IR trace class. -@sa ctfirtraceclass -*/ struct bt_trace; struct bt_stream; struct bt_stream_class; -struct bt_clock_class; struct bt_field_type; struct bt_value; struct bt_packet_header_field; -/** -@brief User function type to use with - bt_trace_add_is_static_listener(). - -@param[in] trace_class Trace class which is now static. -@param[in] data User data as passed to - bt_trace_add_is_static_listener() when - you added the listener. - -@prenotnull{trace_class} -*/ typedef void (* bt_trace_is_static_listener)( - struct bt_trace *trace_class, void *data); - -/** -@brief User function type to use with - bt_trace_add_is_static_listener(). + struct bt_trace *trace, void *data); -@param[in] trace_class Trace class to which the listener was added. -@param[in] data User data as passed to - bt_trace_add_is_static_listener() when - you added the listener. - -@prenotnull{trace_class} -*/ typedef void (* bt_trace_listener_removed)( - struct bt_trace *trace_class, void *data); - -/** -@name Creation function -@{ -*/ - -/** -@brief Creates a default CTF IR trace class. - -On success, the trace packet header field type of the created trace -class is an empty structure field type. You can modify this default -trace packet header field type after the trace class is created with -bt_trace_get_packet_header_field_type() and -bt_trace_set_packet_header_field_type(). - -The created trace class has the following initial properties: - -- Name: none. You can set a name - with bt_trace_set_name(). -- UUID: none. You can set a UUID with - bt_trace_set_uuid(). -- Native byte order: #BT_BYTE_ORDER_UNSPECIFIED. - You can set a native byte order with - bt_trace_set_native_byte_order(). -- Environment: empty. You can add environment entries - with bt_trace_set_environment_field(), - bt_trace_set_environment_field_integer(), and - bt_trace_set_environment_field_string(). + struct bt_trace *trace, void *data); -@returns Created trace class, or \c NULL on error. - -@postsuccessrefcountret1 -*/ extern struct bt_trace *bt_trace_create(void); -/** @} */ - -/** -@name Properties functions -@{ -*/ - -/** -@brief Returns the name of the CTF IR trace class \p trace_class. - -On success, \p trace_class remains the sole owner of the returned -string. The returned string is valid as long as \p trace_class exists -and is not modified. - -@param[in] trace_class Trace class of which to get the name. -@returns Name of trace class \p trace_class, or - \c NULL if \p trace_class is unnamed or - on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} - -@sa bt_trace_set_name(): Sets the name of a given trace class. -*/ -extern const char *bt_trace_get_name(struct bt_trace *trace_class); - -/** -@brief Sets the name of the CTF IR trace class \p trace_class - to \p name. - -@param[in] trace_class Trace class of which to set the name. -@param[in] name Name of the trace class (copied on success). -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prehot{trace_class} -@postrefcountsame{trace_class} - -@sa bt_trace_get_name(): Returns the name of a given trace class. -*/ -extern int bt_trace_set_name(struct bt_trace *trace_class, - const char *name); - -/** -@brief Returns the native byte order of the CTF IR trace class - \p trace_class. - -@param[in] trace_class Trace class of which to get the default byte - order. -@returns Native byte order of \p trace_class, - or #BT_BYTE_ORDER_UNKNOWN on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} - -@sa bt_trace_set_native_byte_order(): Sets the native byte order of - a given trace class. -*/ -extern enum bt_byte_order bt_trace_get_native_byte_order( - struct bt_trace *trace_class); - -/** -@brief Sets the native byte order of the CTF IR trace class - \p trace_class to \p native_byte_order. - -\p native_byte_order \em must be one of: - -- #BT_BYTE_ORDER_LITTLE_ENDIAN -- #BT_BYTE_ORDER_BIG_ENDIAN -- #BT_BYTE_ORDER_NETWORK -- If the trace is not in CTF writer mode, - #BT_BYTE_ORDER_UNSPECIFIED. - -@param[in] trace_class Trace class of which to set the native byte - order. -@param[in] native_byte_order Native byte order of the trace class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prehot{trace_class} -@pre \p native_byte_order is either #BT_BYTE_ORDER_UNSPECIFIED (if the - trace is not in CTF writer mode), - #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN, or - #BT_BYTE_ORDER_NETWORK. -@postrefcountsame{trace_class} - -@sa bt_trace_get_native_byte_order(): Returns the native byte order of a - given trace class. -*/ -extern int bt_trace_set_native_byte_order(struct bt_trace *trace_class, - enum bt_byte_order native_byte_order); - -/** -@brief Returns the UUID of the CTF IR trace class \p trace_class. - -On success, the return value is an array of 16 bytes. - -@param[in] trace_class Trace class of which to get the UUID. -@returns UUID of trace class \p trace_class, or - \c NULL if \p trace_class has no UUID or on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} - -@sa bt_trace_set_uuid(): Sets the UUID of a given trace class. -*/ -extern const unsigned char *bt_trace_get_uuid( - struct bt_trace *trace_class); - -/** -@brief Sets the UUID of the CTF IR trace class \p trace_class to - \p uuid. - -\p uuid \em must be an array of 16 bytes. - -@param[in] trace_class Trace class of which to set the UUID. -@param[in] uuid UUID of the \p trace_class (copied on - success). -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{uuid} -@prehot{trace_class} -@pre \p uuid is an array of 16 bytes. -@postrefcountsame{trace_class} - -@sa bt_trace_get_uuid(): Returns the UUID of a given trace class. -*/ -extern int bt_trace_set_uuid(struct bt_trace *trace_class, - const unsigned char *uuid); - -/** -@brief Returns the number of entries contained in the environment of - the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of environment entries. -@returns Number of environment entries - contained in \p trace_class, or - a negative value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int64_t bt_trace_get_environment_field_count( - struct bt_trace *trace_class); - -/** -@brief Returns the field name of the environment entry at index - \p index in the CTF IR trace class \p trace_class. - -On success, the returned string is valid as long as this trace class -exists and is \em not modified. \p trace_class remains the sole owner of -the returned string. - -@param[in] trace_class Trace class of which to get the name of the - environment entry at index \p index. -@param[in] index Index of environment entry to find. -@returns Name of the environment entry at index \p index - in \p trace_class, or \c NULL on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of environment entries in - \p trace_class (see bt_trace_get_environment_field_count()). -@postrefcountsame{trace_class} - -@sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's - environment entry by index. -@sa bt_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -@sa bt_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern const char * -bt_trace_get_environment_field_name_by_index( - struct bt_trace *trace_class, uint64_t index); - -extern struct bt_value * -bt_trace_borrow_environment_field_value_by_index(struct bt_trace *trace_class, - uint64_t index); - -/** -@brief Returns the value of the environment entry at index - \p index in the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the value of the - environment entry at index \p index. -@param[in] index Index of the environment entry to find. -@returns Value of the environment entry at index \p index - in \p trace_class, or \c NULL on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of environment entries in - \p trace_class (see bt_trace_get_environment_field_count()). -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -@sa bt_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -static inline -struct bt_value *bt_trace_get_environment_field_value_by_index( - struct bt_trace *trace_class, uint64_t index) -{ - return bt_get(bt_trace_borrow_environment_field_value_by_index( - trace_class, index)); -} - -extern struct bt_value * -bt_trace_borrow_environment_field_value_by_name( - struct bt_trace *trace_class, const char *name); - -/** -@brief Returns the value of the environment entry named \p name - in the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the value of the - environment entry named \p name. -@param[in] name Name of the environment entry to find. -@returns Value of the environment entry named \p name - in \p trace_class, or \c NULL if there's no such - entry or on error. - -@prenotnull{trace_class} -@prenotnull{name} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's - environment entry by index. -@sa bt_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -static inline -struct bt_value * -bt_trace_get_environment_field_value_by_name( - struct bt_trace *trace_class, const char *name) -{ - return bt_get( - bt_trace_borrow_environment_field_value_by_name( - trace_class, name)); -} - -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. +extern bt_bool bt_trace_assigns_automatic_stream_class_id( + struct bt_trace *trace); -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by \p value. +extern int bt_trace_set_assigns_automatic_stream_class_id( + struct bt_trace *trace, bt_bool value); -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name. -@returns 0 on success, or a negative value on error. +extern const char *bt_trace_get_name(struct bt_trace *trace); -@prenotnull{trace_class} -@prenotnull{name} -@prenotnull{value} -@prehot{trace_class} -@pre \p value is an - \link bt_value_integer_create() integer value object\endlink - or a - \link bt_value_string_create() string value object\endlink. -@postrefcountsame{trace_class} -@postsuccessrefcountinc{value} +extern int bt_trace_set_name(struct bt_trace *trace, const char *name); -@sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's - environment entry by index. -@sa bt_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -*/ -extern int bt_trace_set_environment_field( - struct bt_trace *trace_class, const char *name, - struct bt_value *value); +extern bt_uuid bt_trace_get_uuid(struct bt_trace *trace); -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. +extern int bt_trace_set_uuid(struct bt_trace *trace, bt_uuid uuid); -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by a new -\link bt_value_integer_create() integer value object\endlink -containing \p value. +extern uint64_t bt_trace_get_environment_entry_count(struct bt_trace *trace); -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name. -@returns 0 on success, or a negative value on error. +extern void bt_trace_borrow_environment_entry_by_index( + struct bt_trace *trace, uint64_t index, + const char **name, struct bt_value **value); -@prenotnull{trace_class} -@prenotnull{name} -@prehot{trace_class} -@postrefcountsame{trace_class} +extern struct bt_value *bt_trace_borrow_environment_entry_value_by_name( + struct bt_trace *trace, const char *name); -@sa bt_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern int bt_trace_set_environment_field_integer( - struct bt_trace *trace_class, const char *name, +extern int bt_trace_set_environment_entry_integer( + struct bt_trace *trace, const char *name, int64_t value); -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. - -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by a new -\link bt_value_string_create() string value object\endlink -containing \p value. - -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name - (copied on success). -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prenotnull{value} -@prehot{trace_class} -@postrefcountsame{trace_class} - -@sa bt_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern int bt_trace_set_environment_field_string( - struct bt_trace *trace_class, const char *name, +extern int bt_trace_set_environment_entry_string( + struct bt_trace *trace, const char *name, const char *value); -/** @} */ - -/** -@name Contained field types functions -@{ -*/ - extern struct bt_field_type *bt_trace_borrow_packet_header_field_type( - struct bt_trace *trace_class); - -/** -@brief Returns the packet header field type of the CTF IR trace class - \p trace_class. - -@param[in] trace_class Trace class of which to get the packet - header field type. -@returns Packet header field type of \p trace_class, - or \c NULL if \p trace_class has no packet header field - type or on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -@post On success, if the return value is a field type, its - reference count is incremented. - -@sa bt_trace_set_packet_header_field_type(): Sets the packet - header field type of a given trace class. -*/ -static inline -struct bt_field_type *bt_trace_get_packet_header_field_type( - struct bt_trace *trace_class) -{ - return bt_get(bt_trace_borrow_packet_header_field_type(trace_class)); -} - -extern struct bt_packet_header_field *bt_trace_create_packet_header_field( struct bt_trace *trace); -/** -@brief Sets the packet header field type of the CTF IR trace class - \p trace_class to \p packet_header_type, or unsets the current packet - header field type from \p trace_class. - -If \p packet_header_type is \c NULL, then this function unsets the current -packet header field type from \p trace_class, effectively making \p trace_class -a trace without a packet header field type. - -As of Babeltrace \btversion, if \p packet_header_type is not \c NULL, -\p packet_header_type \em must be a CTF IR structure field type object. - -@param[in] trace_class Trace class of which to set the packet - header field type. -@param[in] packet_header_type Packet header field type, or \c NULL to unset - the current packet header field type. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prehot{trace_class} -@pre \p packet_header_type, if not \c NULL, is a CTF IR - structure field type. -@postrefcountsame{trace_class} -@post On success, if \p packet_header_type is not \c NULL, - the reference count of \p packet_header_type is incremented. - -@sa bt_trace_get_packet_header_field_type(): Returns the packet - header field type of a given trace class. -*/ -extern int bt_trace_set_packet_header_field_type(struct bt_trace *trace_class, +extern int bt_trace_set_packet_header_field_type(struct bt_trace *trace, struct bt_field_type *packet_header_type); -/** @} */ - -/** -@name Contained clock classes functions -@{ -*/ - -/** -@brief Returns the number of CTF IR clock classes contained in the - CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of contained clock classes. -@returns Number of contained clock classes - contained in \p trace_class, or a negative - value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int64_t bt_trace_get_clock_class_count( - struct bt_trace *trace_class); - -extern struct bt_clock_class *bt_trace_borrow_clock_class_by_index( - struct bt_trace *trace_class, uint64_t index); - -/** -@brief Returns the CTF IR clock class at index \p index in the CTF - IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the clock class - contained at index \p index. -@param[in] index Index of the clock class to find in - \p trace_class. -@returns Clock class at index \p index in \p trace_class, - or \c NULL on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of clock classes contained in - the trace class \p trace_class (see - bt_trace_get_clock_class_count()). -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_trace_get_clock_class_by_name(): Finds a clock class by name - in a given trace class. -@sa bt_trace_add_clock_class(): Adds a clock class to a trace class. -*/ -static inline -struct bt_clock_class *bt_trace_get_clock_class_by_index( - struct bt_trace *trace_class, uint64_t index) -{ - return bt_get(bt_trace_borrow_clock_class_by_index( - trace_class, index)); -} - -extern struct bt_clock_class *bt_trace_borrow_clock_class_by_name( - struct bt_trace *trace_class, const char *name); - -/** -@brief Returns the CTF IR clock class named \c name found in the CTF - IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the clock class - named \p name. -@param[in] name Name of the clock class to find in \p trace_class. -@returns Clock class named \p name in \p trace_class, - or \c NULL on error. - -@prenotnull{trace_class} -@prenotnull{name} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_trace_get_clock_class_by_index(): Returns the clock class contained - in a given trace class at a given index. -@sa bt_trace_add_clock_class(): Adds a clock class to a trace class. -*/ -static inline -struct bt_clock_class *bt_trace_get_clock_class_by_name( - struct bt_trace *trace_class, const char *name) -{ - return bt_get(bt_trace_borrow_clock_class_by_name(trace_class, name)); -} - -/** -@brief Adds the CTF IR clock class \p clock_class to the CTF IR - trace class \p trace_class. - -On success, \p trace_class contains \p clock_class. - -You can call this function even if \p trace_class or \p clock_class -are frozen. - -@param[in] trace_class Trace class to which to add \p clock_class. -@param[in] clock_class Clock class to add to \p trace_class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{clock_class} -@postrefcountsame{trace_class} -@postsuccessrefcountinc{clock_class} -@post On success, if \p trace_class is frozen, - \p clock_class is frozen. - -@sa bt_trace_get_clock_class_by_index(): Returns the clock class contained - in a given trace class at a given index. -@sa bt_trace_get_clock_class_by_name(): Finds a clock class by name - in a given trace class. -*/ -extern int bt_trace_add_clock_class(struct bt_trace *trace_class, - struct bt_clock_class *clock_class); - -/** @} */ - -/** -@name Stream class children functions -@{ -*/ - -/** -@brief Returns the number of stream classes contained in the - CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of children stream classes. -@returns Number of children stream classes - contained in \p trace_class, or a negative - value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int64_t bt_trace_get_stream_class_count( - struct bt_trace *trace_class); +extern uint64_t bt_trace_get_stream_class_count(struct bt_trace *trace); extern struct bt_stream_class *bt_trace_borrow_stream_class_by_index( - struct bt_trace *trace_class, uint64_t index); - -/** -@brief Returns the stream class at index \p index in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the stream class. -@param[in] index Index of the stream class to find. -@returns Stream class at index \p index, or \c NULL - on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of stream classes contained in - the trace class \p trace_class (see - bt_trace_get_stream_class_count()). -@postrefcountsame{trace_class} - -@sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID. -@sa bt_trace_add_stream_class(): Adds a stream class to a trace class. -*/ -static inline -struct bt_stream_class *bt_trace_get_stream_class_by_index( - struct bt_trace *trace_class, uint64_t index) -{ - return bt_get(bt_trace_borrow_stream_class_by_index( - trace_class, index)); -} + struct bt_trace *trace, uint64_t index); extern struct bt_stream_class *bt_trace_borrow_stream_class_by_id( - struct bt_trace *trace_class, uint64_t id); - -/** -@brief Returns the stream class with ID \c id found in the CTF IR - trace class \p trace_class. + struct bt_trace *trace, uint64_t id); -@param[in] trace_class Trace class of which to get the stream class. -@param[in] id ID of the stream class to find. -@returns Stream class with ID \p id, or \c NULL - on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_trace_get_stream_class_by_index(): Returns the stream class contained - in a given trace class at a given index. -@sa bt_trace_add_stream_class(): Adds a stream class to a trace class. -*/ -static inline -struct bt_stream_class *bt_trace_get_stream_class_by_id( - struct bt_trace *trace_class, uint64_t id) -{ - return bt_get(bt_trace_borrow_stream_class_by_id(trace_class, id)); -} - -/** -@brief Adds the CTF IR stream class \p stream_class to the - CTF IR trace class \p trace_class. - -On success, \p stream_class becomes the child of \p trace_class. - -You can only add a given stream class to one trace class. - -You can call this function even if \p trace_class is frozen. - -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 root field types of -\p stream_class and of all its currently contained -\link ctfireventclass CTF IR event classes\endlink. If any automatic -resolving fails, then this function fails. - -@param[in] trace_class Trace class to which to add \p stream_class. -@param[in] stream_class Stream class to add to \p trace_class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{stream_class} -@postrefcountsame{trace_class} -@postsuccessrefcountinc{stream_class} -@postsuccessfrozen{stream_class} - -@sa bt_trace_get_stream_class_by_index(): Returns the stream class contained - in a given trace class at a given index. -@sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID. -*/ -extern int bt_trace_add_stream_class(struct bt_trace *trace_class, - struct bt_stream_class *stream_class); - -/** @} */ - -/** -@name Stream children functions -@{ -*/ - -/** -@brief Returns the number of streams contained in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of children streams. -@returns Number of children streams - contained in \p trace_class, or a negative - value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int64_t bt_trace_get_stream_count(struct bt_trace *trace_class); +extern uint64_t bt_trace_get_stream_count(struct bt_trace *trace); extern struct bt_stream *bt_trace_borrow_stream_by_index( - struct bt_trace *trace_class, uint64_t index); - -/** -@brief Returns the stream at index \p index in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the stream. -@param[in] index Index of the stream to find. -@returns Stream at index \p index, or \c NULL - on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of streams contained in - the trace class \p trace_class (see - bt_trace_get_stream_count()). -@postrefcountsame{trace_class} -*/ -static inline -struct bt_stream *bt_trace_get_stream_by_index( - struct bt_trace *trace_class, uint64_t index) -{ - return bt_get(bt_trace_borrow_stream_by_index(trace_class, index)); -} - -/** @} */ - -/** -@name Misc. functions -@{ -*/ - -/** -@brief Returns whether or not the CTF IR trace class \p trace_class - is static. - -It is guaranteed that a static trace class will never contain new -streams, stream classes, or clock classes. A static class is always -frozen. - -This function returns #BT_TRUE if bt_trace_set_is_static() was -previously called on it. + struct bt_trace *trace, uint64_t index); -@param[in] trace_class Trace class to check. -@returns #BT_TRUE if \p trace_class is static, +extern struct bt_stream *bt_trace_borrow_stream_by_id( + struct bt_trace *trace, uint64_t id); -@sa bt_trace_set_is_static(): Makes a trace class static. -*/ -extern bt_bool bt_trace_is_static(struct bt_trace *trace_class); +extern bt_bool bt_trace_is_static(struct bt_trace *trace); -/** -@brief Makes the CTF IR trace class \p trace_class static. +extern int bt_trace_make_static(struct bt_trace *trace); -A static trace class is frozen and you cannot call any modifying -function on it: - -- bt_trace_add_stream_class() -- bt_trace_add_clock_class() -- bt_trace_set_environment_field() -- bt_trace_set_environment_field_integer() -- bt_trace_set_environment_field_string() -- bt_trace_add_is_static_listener() - -You cannot create a stream with bt_stream_create() with any of the -stream classes of a static trace class. - -@param[in] trace_class Trace class to make static. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -@postsuccessfrozen{trace_class} - -@sa bt_trace_is_static(): Checks whether or not a given trace class - is static. -@sa bt_trace_add_is_static_listener(): Adds a listener to a trace - class which is called when the trace class is made static. -*/ -extern int bt_trace_set_is_static(struct bt_trace *trace_class); - -/** -@brief Adds the listener \p listener to the CTF IR trace class - \p trace_class which is called when the trace is made static. - -\p listener is called with \p data, the user data, the first time -bt_trace_set_is_static() is called on \p trace_class. - -When the trace is destroyed, or when you remove the added listener with -bt_trace_remove_is_static_listener(), \p listener_removed is called -if it's not \c NULL. You can use \p listener_removed to free any dynamic -data which exists only for the added listener. You cannot call -any function which modifies \p trace_class during the execution of -\p listener_removed, including bt_trace_remove_is_static_listener(). - -This function fails if \p trace_class is already static: you need to -check the condition first with bt_trace_is_static(). - -On success, this function returns a unique numeric identifier for this -listener within \p trace. You can use this identifier to remove the -specific listener you added with -bt_trace_remove_is_static_listener(). - -@param[in] trace_class Trace class to which to add the - listener. -@param[in] listener Listener to add to \p trace_class. -@param[in] listener_removed Remove listener called when \p listener - is removed from \p trace_class, or - \c NULL if you don't need a remove - listener. -@param[in] data User data passed when \p listener or - \p listener_removed is called. -@returns A unique numeric identifier for this - listener on success (0 or greater), or a - negative value on error. - -@prenotnull{trace_class} -@prenotnull{listener} -@pre \p trace_class is not static. -@postrefcountsame{trace_class} - -@sa bt_trace_remove_is_static_listener(): Removes a "trace is - static" listener from a trace class previously added with this - function. -@sa bt_trace_is_static(): Checks whether or not a given trace class - is static. -@sa bt_trace_set_is_static(): Makes a trace class static. -*/ extern int bt_trace_add_is_static_listener( - struct bt_trace *trace_class, + struct bt_trace *trace, bt_trace_is_static_listener listener, - bt_trace_listener_removed listener_removed, void *data); - -/** -@brief Removes the "trace is static" listener identified by - \p listener_id from the trace class \p trace_class. - -@param[in] trace_class Trace class from which to remove the listener - identified by \p listener_id. -@param[in] listener_id Identifier of the listener to remove from - \p trace_class. -@returns 0 if this function removed the listener, or - a negative value on error. + bt_trace_listener_removed listener_removed, void *data, + uint64_t *listener_id); -@prenotnull{trace_class} -@pre \p listener_id is the identifier of a listener that you previously - added with bt_trace_add_is_static_listener() and did not - already remove with this function. -@postrefcountsame{trace_class} - -@sa bt_trace_add_is_static_listener(): Adds a listener to a trace - class which is called when the trace class is made static. -*/ extern int bt_trace_remove_is_static_listener( - struct bt_trace *trace_class, int listener_id); - -/** -@brief Accepts the visitor \p visitor to visit the hierarchy of the - CTF IR trace class \p trace_class. - -This function traverses the hierarchy of \p trace_class in pre-order -and calls \p visitor on each element. - -The trace class itself is visited first, then, for each children stream -class, the stream class itself, and all its children event classes. - -@param[in] trace_class Trace class to visit. -@param[in] visitor Visiting function. -@param[in] data User data. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{visitor} -*/ -extern int bt_trace_visit(struct bt_trace *trace_class, - bt_visitor visitor, void *data); - -/** @} */ - -/** @} */ + struct bt_trace *trace, uint64_t listener_id); #ifdef __cplusplus }