X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream-class.h;h=94d7c9b889507870757bdaba6305f3a33d107e1a;hb=3dca22768a95bef664012559aa9ac977091de6ac;hp=1db7ec5796ebd2f57bcc4dbea663e40cfb225cc2;hpb=2fc615974989b0c3dfbd0702341c06bc614dc022;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h index 1db7ec57..94d7c9b8 100644 --- a/include/babeltrace/ctf-ir/stream-class.h +++ b/include/babeltrace/ctf-ir/stream-class.h @@ -31,6 +31,8 @@ */ #include + +/* For bt_visitor */ #include #ifdef __cplusplus @@ -42,9 +44,13 @@ extern "C" { @ingroup ctfir @brief CTF IR stream class. +@code +#include +@endcode + @note -See \ref ctfirwriterstreamclass which documents additional CTF IR stream -class functions exclusive to the CTF IR writer mode. +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. @@ -61,9 +67,9 @@ 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_ctf_stream_class_add_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_ctf_trace_add_stream_class(). +bt_trace_add_stream_class(). A stream class owns three \link ctfirfieldtypes field types\endlink: @@ -86,8 +92,8 @@ As a reminder, here's the structure of a CTF packet: @imgpacketstructure Before you can create a stream from a stream class with -bt_ctf_stream_create(), you \em must add the prepared stream class to a -trace class by calling bt_ctf_trace_add_stream_class(). +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 @@ -97,22 +103,25 @@ management of Babeltrace objects. The following functions \em freeze their stream class parameter on success: -- bt_ctf_trace_add_stream_class() -- bt_ctf_event_create() -- bt_ctf_writer_create_stream() - (\link ctfirwriter CTF IR writer\endlink mode only) +- 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_ctf_stream_class_add_event_class(). + 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 ctfirwriterstreamclass +@sa ctfwriterstreamclass @file @brief CTF IR stream class type and functions. @@ -123,13 +132,13 @@ except for: */ /** -@struct bt_ctf_stream_class +@struct bt_stream_class @brief A CTF IR stream class. @sa ctfirstreamclass */ -struct bt_ctf_stream_class; -struct bt_ctf_event_class; -struct bt_ctf_clock; +struct bt_stream_class; +struct bt_event_class; +struct bt_clock; /** @name Creation and parent access functions @@ -156,16 +165,18 @@ has the following fields: - timestamp: a 64-bit unsigned integer field type. You can modify those default field types after the stream class is -created with bt_ctf_stream_class_set_packet_context_type() and -bt_ctf_stream_class_set_event_header_type(). +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 (can be \c NULL to - create an unnamed stream class). -@returns Created stream class, or \c NULL on error. +@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_ctf_stream_class *bt_ctf_stream_class_create(const char *name); +extern struct bt_stream_class *bt_stream_class_create(const char *name); /** @brief Returns the parent CTF IR trace class of the CTF IR stream @@ -174,7 +185,7 @@ extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name); 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_ctf_trace_add_stream_class(). +bt_trace_add_stream_class(). @param[in] stream_class Stream class of which to get the parent trace class. @@ -183,13 +194,14 @@ bt_ctf_trace_add_stream_class(). added to a trace class yet or on error. @prenotnull{stream_class} +@postrefcountsame{stream_class} @postsuccessrefcountretinc -@sa bt_ctf_trace_add_stream_class(): Add a stream class to +@sa bt_trace_add_stream_class(): Add a stream class to a trace class. */ -extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace( - struct bt_ctf_stream_class *stream_class); +extern struct bt_trace *bt_stream_class_get_trace( + struct bt_stream_class *stream_class); /** @} */ @@ -212,33 +224,36 @@ string. @prenotnull{stream_class} @postrefcountsame{stream_class} -@sa bt_ctf_stream_class_set_name(): Sets the name of a given +@sa bt_stream_class_set_name(): Sets the name of a given stream class. */ -extern const char *bt_ctf_stream_class_get_name( - struct bt_ctf_stream_class *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. + \p stream_class to \p name, or resets the name of + \p stream_class. -\p name must be unique amongst the names of all the stream classes -of the trace class to which you eventually add \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). +@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} -@prenotnull{name} @prehot{stream_class} @postrefcountsame{stream_class} -@sa bt_ctf_stream_class_get_name(): Returns the name of a given +@sa bt_stream_class_get_name(): Returns the name of a given stream class. */ -extern int bt_ctf_stream_class_set_name( - struct bt_ctf_stream_class *stream_class, const char *name); +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. @@ -250,11 +265,11 @@ extern int bt_ctf_stream_class_set_name( @prenotnull{stream_class} @postrefcountsame{stream_class} -@sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given +@sa bt_stream_class_set_id(): Sets the numeric ID of a given stream class. */ -extern int64_t bt_ctf_stream_class_get_id( - struct bt_ctf_stream_class *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 @@ -269,13 +284,14 @@ of the trace class to which you eventually add \p stream_class. @prenotnull{stream_class} @prehot{stream_class} +@pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX). @postrefcountsame{stream_class} -@sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given +@sa bt_stream_class_get_id(): Returns the numeric ID of a given stream class. */ -extern int bt_ctf_stream_class_set_id( - struct bt_ctf_stream_class *stream_class, uint32_t id); +extern int bt_stream_class_set_id( + struct bt_stream_class *stream_class, uint64_t id); /** @} */ @@ -291,42 +307,52 @@ extern int bt_ctf_stream_class_set_id( @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 on error. + or \c NULL if \p stream_class has no packet context + field type or on error. @prenotnull{stream_class} -@postsuccessrefcountretinc +@postrefcountsame{stream_class} +@post On success, if the return value is a field type, its + reference count is incremented. -@sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet +@sa bt_stream_class_set_packet_context_field_type(): Sets the packet context field type of a given stream class. */ -extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type( - struct bt_ctf_stream_class *stream_class); +extern struct bt_field_type *bt_stream_class_get_packet_context_field_type( + 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. + \p stream_class to \p packet_context_type, or unsets the current packet + context field type from \p stream_class. -As of Babeltrace \btversion, \p packet_context_type \em must be a -CTF IR structure field type object. +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. +@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} -@prenotnull{packet_context_type} @prehot{stream_class} -@preisstructft{packet_context_type} +@pre \p packet_context_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{packet_context_type} +@post On success, if \p packet_context_type is not \c NULL, + the reference count of \p packet_context_type is incremented. -@sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet +@sa bt_stream_class_get_packet_context_field_type(): Returns the packet context field type of a given stream class. */ -extern int bt_ctf_stream_class_set_packet_context_type( - struct bt_ctf_stream_class *stream_class, - struct bt_ctf_field_type *packet_context_type); +extern int bt_stream_class_set_packet_context_field_type( + struct bt_stream_class *stream_class, + struct bt_field_type *packet_context_type); /** @brief Returns the event header field type of the CTF IR stream class @@ -335,90 +361,109 @@ extern int bt_ctf_stream_class_set_packet_context_type( @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 on error. + or \c NULL if \p stream_class has no event header field + type or on error. @prenotnull{stream_class} -@postsuccessrefcountretinc +@postrefcountsame{stream_class} +@post On success, if the return value is a field type, its + reference count is incremented. -@sa bt_ctf_stream_class_set_event_header_type(): Sets the event +@sa bt_stream_class_set_event_header_field_type(): Sets the event header field type of a given stream class. */ -extern struct bt_ctf_field_type * -bt_ctf_stream_class_get_event_header_type( - struct bt_ctf_stream_class *stream_class); +extern struct bt_field_type * +bt_stream_class_get_event_header_field_type( + struct bt_stream_class *stream_class); /** @brief Sets the event header field type of the CTF IR stream class - \p stream_class to \p event_header_type. + \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, \p event_header_type \em must be a -CTF IR structure field type object. +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. +@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} -@prenotnull{event_header_type} @prehot{stream_class} -@preisstructft{event_header_type} +@pre \p event_header_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{event_header_type} +@post On success, if \p event_header_type is not \c NULL, + the reference count of \p event_header_type is incremented. -@sa bt_ctf_stream_class_get_event_header_type(): Returns the event +@sa bt_stream_class_get_event_header_field_type(): Returns the event header field type of a given stream class. */ -extern int bt_ctf_stream_class_set_event_header_type( - struct bt_ctf_stream_class *stream_class, - struct bt_ctf_field_type *event_header_type); +extern int bt_stream_class_set_event_header_field_type( + struct bt_stream_class *stream_class, + struct bt_field_type *event_header_type); /** -@brief Returns the per-stream class event context field type of the - CTF IR stream class \p 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 per-stream - class event context field type. -@returns Per-stream class event context field type of - \p stream_class, or \c NULL on error. +@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} -@postsuccessrefcountretinc +@postrefcountsame{stream_class} +@post On success, if the return value is a field type, + its reference count is incremented. + -@sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream - class event context field type of a given stream class. +@sa bt_stream_class_set_event_context_field_type(): Sets the event + context field type of a given stream class. */ -extern struct bt_ctf_field_type * -bt_ctf_stream_class_get_event_context_type( - struct bt_ctf_stream_class *stream_class); +extern struct bt_field_type * +bt_stream_class_get_event_context_field_type( + struct bt_stream_class *stream_class); /** -@brief Sets the per-stream class event context field type of the CTF - IR stream class \p stream_class to \p event_context_type. +@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, \p event_context_type \em must be a -CTF IR structure field type object. +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 - per-stream class event context - field type. -@param[in] event_context_type Per-stream class event context context - field type. +@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} -@prenotnull{event_context_type} @prehot{stream_class} -@preisstructft{event_context_type} +@pre \p event_context_type, if not \c NULL, is a CTF IR + structure field type. @postrefcountsame{stream_class} -@postsuccessrefcountinc{event_context_type} +@post On success, if \p event_context_type is not \c NULL, + the reference count of \p event_context_type is incremented. -@sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream - class event context field type of a given stream class. +@sa bt_stream_class_get_event_context_field_type(): Returns the event context + field type of a given stream class. */ -extern int bt_ctf_stream_class_set_event_context_type( - struct bt_ctf_stream_class *stream_class, - struct bt_ctf_field_type *event_context_type); +extern int bt_stream_class_set_event_context_field_type( + struct bt_stream_class *stream_class, + struct bt_field_type *event_context_type); /** @} */ @@ -440,8 +485,8 @@ extern int bt_ctf_stream_class_set_event_context_type( @prenotnull{stream_class} @postrefcountsame{stream_class} */ -extern int bt_ctf_stream_class_get_event_class_count( - struct bt_ctf_stream_class *stream_class); +extern int64_t bt_stream_class_get_event_class_count( + struct bt_stream_class *stream_class); /** @brief Returns the event class at index \p index in the CTF IR stream @@ -455,37 +500,15 @@ extern int bt_ctf_stream_class_get_event_class_count( @prenotnull{stream_class} @pre \p index is lesser than the number of event classes contained in the stream class \p stream_class (see - bt_ctf_stream_class_get_event_class_count()). + bt_stream_class_get_event_class_count()). @postrefcountsame{stream_class} @postsuccessrefcountretinc -@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class +@sa bt_stream_class_get_event_class_by_id(): Finds an event class by ID. -@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class - by name. */ -extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class( - struct bt_ctf_stream_class *stream_class, int index); - -/** -@brief Returns the event class named \c name 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] name Name of the event class to find. -@returns Event class named \p name, or \c NULL - on error. - -@prenotnull{stream_class} -@prenotnull{name} -@postrefcountsame{stream_class} -@postsuccessrefcountretinc - -@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class - by ID. -*/ -extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name( - struct bt_ctf_stream_class *stream_class, const char *name); +extern struct bt_event_class *bt_stream_class_get_event_class_by_index( + struct bt_stream_class *stream_class, uint64_t index); /** @brief Returns the event class with ID \c id found in the CTF IR stream @@ -499,12 +522,9 @@ extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name( @prenotnull{stream_class} @postrefcountsame{stream_class} @postsuccessrefcountretinc - -@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class - by name. */ -extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id( - struct bt_ctf_stream_class *stream_class, uint32_t id); +extern struct bt_event_class *bt_stream_class_get_event_class_by_id( + struct bt_stream_class *stream_class, uint64_t id); /** @brief Adds the CTF IR event class \p event_class to the @@ -518,6 +538,20 @@ 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. @@ -529,9 +563,9 @@ on a frozen stream class. @postsuccessrefcountinc{event_class} @postsuccessfrozen{event_class} */ -extern int bt_ctf_stream_class_add_event_class( - struct bt_ctf_stream_class *stream_class, - struct bt_ctf_event_class *event_class); +extern int bt_stream_class_add_event_class( + struct bt_stream_class *stream_class, + struct bt_event_class *event_class); /** @} */ @@ -558,17 +592,13 @@ event classes. @prenotnull{stream_class} @prenotnull{visitor} */ -extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class, - bt_ctf_visitor visitor, void *data); +extern int bt_stream_class_visit(struct bt_stream_class *stream_class, + bt_visitor visitor, void *data); /** @} */ /** @} */ -// TODO: document for writer -extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock( - struct bt_ctf_stream_class *stream_class); - #ifdef __cplusplus } #endif