X-Git-Url: https://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream-class.h;h=175bb68850f5db89964fe55f924fff7c231a1720;hb=839d52a5c5c1fdd66cee9bf7d06c0c0acdd4c2a3;hp=d2b16dede3ed7714f36da0438cf14d509f38b908;hpb=4cdafd515891b2541a078030c4cfc1a17c6f2315;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h index d2b16ded..175bb688 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 @@ -47,8 +49,8 @@ extern "C" { @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. @@ -65,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: @@ -90,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 @@ -101,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. @@ -127,19 +132,41 @@ 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 @{ */ +/** +@brief Creates an empty CTF IR stream class named \p name, or an + unnamed empty stream class if \p name is \c NULL. + +On success, the packet context, event header, and event context field +types are empty structure field types. You can modify those default +field types after the stream class is created with +bt_stream_class_set_packet_context_type(), +bt_stream_class_set_event_header_type(), and +bt_stream_class_set_event_context_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 empty stream class, or \c NULL on error. + +@postsuccessrefcountret1 + +@sa bt_stream_class_create(): Creates a default stream class. +*/ +extern struct bt_stream_class *bt_stream_class_create_empty( + const char *name); + /** @brief Creates a default CTF IR stream class named \p name­, or a default unnamed stream class if \p name is \c NULL. @@ -160,16 +187,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_type() and +bt_stream_class_set_event_header_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 @@ -178,7 +207,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. @@ -190,11 +219,11 @@ bt_ctf_trace_add_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); /** @} */ @@ -217,33 +246,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. @@ -255,11 +287,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 @@ -274,13 +306,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); /** @} */ @@ -296,43 +329,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} @postrefcountsame{stream_class} -@postsuccessrefcountretinc +@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_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_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_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_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 @@ -341,92 +383,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} @postrefcountsame{stream_class} -@postsuccessrefcountretinc +@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_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_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. -As of Babeltrace \btversion, \p event_header_type \em must be a -CTF IR structure field type object. +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. +@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_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_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} @postrefcountsame{stream_class} -@postsuccessrefcountretinc +@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_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_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_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_type( + struct bt_stream_class *stream_class, + struct bt_field_type *event_context_type); /** @} */ @@ -448,8 +507,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 @@ -463,37 +522,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 @@ -507,12 +544,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 @@ -535,10 +569,10 @@ types of \p event_class. If any automatic resolving fails: 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_ctf_trace_add_stream_class()), this function fails. + 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_ctf_trace_add_stream_class() with \p stream_class. + 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. @@ -551,9 +585,9 @@ types of \p event_class. If any automatic resolving fails: @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); /** @} */ @@ -580,16 +614,18 @@ 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); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_stream_class bt_stream_class +#define bt_ctf_stream_class_create bt_stream_class_create +#define bt_ctf_stream_class_add_event_class bt_stream_class_add_event_class +#define bt_ctf_stream_class_get_packet_context_type bt_stream_class_get_packet_context_type #ifdef __cplusplus }