X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fevent.h;h=46211aaefca930ee2e9b1fbe7deeb12a9c4e7759;hb=094ff7c009937bb23c056333baffe734308a6b06;hp=850f4b7df6396d26ed0c9df2d157d3685c12fb9f;hpb=c2f29fb98a1e9088434fe8872d68695afd8e9dd3;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/event.h b/include/babeltrace/ctf-ir/event.h index 850f4b7d..46211aae 100644 --- a/include/babeltrace/ctf-ir/event.h +++ b/include/babeltrace/ctf-ir/event.h @@ -30,14 +30,19 @@ * http://www.efficios.com/ctf */ +/* For bt_get() */ +#include + #include #include -#include #ifdef __cplusplus extern "C" { #endif +struct bt_value; +struct bt_clock_class; + /** @defgroup ctfirevent CTF IR event @ingroup ctfir @@ -67,28 +72,28 @@ As a reminder, here's the structure of a CTF packet: You can create a CTF IR event \em from a \link ctfireventclass CTF IR event class\endlink with -bt_ctf_event_create(). The event class you use to create an event +bt_event_create(). The event class you use to create an event object becomes its parent. If the \link ctfirtraceclass CTF IR trace class\endlink of an event object (parent of its \link ctfirstreamclass CTF IR stream class\endlink, which is the parent of its event class) was created by a -\link ctfirwriter CTF IR writer\endlink object, then the only possible +\link ctfwriter CTF writer\endlink object, then the only possible action you can do with this event object is to append it to a \link ctfirstream CTF IR stream\endlink with -bt_ctf_stream_append_event(). Otherwise, you can create an event +bt_stream_append_event(). Otherwise, you can create an event notification with bt_notification_event_create(). The event you pass to this function \em must have an attached packet object first. You can attach a \link ctfirpacket CTF IR packet object\endlink to an -event object with bt_ctf_event_set_packet(). +event object with bt_event_set_packet(). A CTF IR event has a mapping of \link ctfirclockvalue CTF IR clock values\endlink. A clock value is an instance of a specific \link ctfirclockclass CTF IR clock class\endlink when the event is emitted. You can set an event object's clock value with -bt_ctf_event_set_clock_value(). +bt_event_set_clock_value(). As with any Babeltrace object, CTF IR event objects have reference @@ -111,18 +116,18 @@ immutable, except for \link refs reference counting\endlink. */ /** -@struct bt_ctf_event +@struct bt_event @brief A CTF IR event. @sa ctfirevent */ -struct bt_ctf_event; -struct bt_ctf_clock; -struct bt_ctf_clock_value; -struct bt_ctf_event_class; -struct bt_ctf_field; -struct bt_ctf_field_type; -struct bt_ctf_stream_class; -struct bt_ctf_packet; +struct bt_event; +struct bt_clock; +struct bt_clock_value; +struct bt_event_class; +struct bt_field; +struct bt_field_type; +struct bt_stream_class; +struct bt_packet; /** @name Creation and parent access functions @@ -137,9 +142,20 @@ struct bt_ctf_packet; \link ctfirstreamclass CTF IR stream class\endlink. On success, the four fields of the created event object are not set. You -can set them with bt_ctf_event_set_header(), -bt_ctf_event_set_stream_event_context(), -bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field(). +can set them with bt_event_set_header(), +bt_event_set_stream_event_context(), +bt_event_set_context(), and bt_event_set_payload(). + +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 and in the root field types of the +parent stream class of \p event_class. If any automatic resolving fails, +this function fails. This means that, if any dynamic field type need +a field type which should be found in the trace packet header root +field type, and if the parent stream class of \p event_class was not +added to a \link ctfirtraceclass CTF IR trace class\endlink yet +with bt_trace_add_stream_class(), then this function fails. @param[in] event_class CTF IR event class to use to create the CTF IR event. @@ -149,15 +165,16 @@ bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field(). @pre \p event_class has a parent stream class. @postsuccessrefcountret1 */ -extern struct bt_ctf_event *bt_ctf_event_create( - struct bt_ctf_event_class *event_class); +extern struct bt_event *bt_event_create(struct bt_event_class *event_class); + +extern struct bt_event_class *bt_event_borrow_class(struct bt_event *event); /** @brief Returns the parent CTF IR event class of the CTF IR event \p event. This function returns a reference to the event class which was used to -create the event object in the first place with bt_ctf_event_create(). +create the event object in the first place with bt_event_create(). @param[in] event Event of which to get the parent event class. @returns Parent event class of \p event, @@ -167,15 +184,20 @@ create the event object in the first place with bt_ctf_event_create(). @postrefcountsame{event} @postsuccessrefcountretinc */ -extern struct bt_ctf_event_class *bt_ctf_event_get_class( - struct bt_ctf_event *event); +static inline +struct bt_event_class *bt_event_get_class(struct bt_event *event) +{ + return bt_get(bt_event_borrow_class(event)); +} + +extern struct bt_packet *bt_event_borrow_packet(struct bt_event *event); /** @brief Returns the CTF IR packet associated to the CTF IR event \p event. This function returns a reference to the event class which was set to -\p event in the first place with bt_ctf_event_set_packet(). +\p event in the first place with bt_event_set_packet(). @param[in] event Event of which to get the associated packet. @returns Packet associated to \p event, @@ -186,11 +208,14 @@ This function returns a reference to the event class which was set to @postrefcountsame{event} @postsuccessrefcountretinc -@sa bt_ctf_event_set_packet(): Associates a given event to a given +@sa bt_event_set_packet(): Associates a given event to a given packet. */ -extern struct bt_ctf_packet *bt_ctf_event_get_packet( - struct bt_ctf_event *event); +static inline +struct bt_packet *bt_event_get_packet(struct bt_event *event) +{ + return bt_get(bt_event_borrow_packet(event)); +} /** @brief Associates the CTF IR event \p event to the CTF IR packet @@ -200,7 +225,7 @@ The \link ctfirstreamclass CTF IR stream class\endlink of the parent \link ctfirstream CTF IR stream\endlink of \p packet \em must be the same as the parent stream class of the \link ctfireventclass CTF IR event class\endlink returned -by bt_ctf_event_get_class() for \p event. +by bt_event_get_class() for \p event. You \em must call this function to create an event-packet association before you call bt_notification_event_create() with \p event. @@ -209,6 +234,7 @@ On success, this function also sets the parent stream object of \p event to the parent stream of \p packet. @param[in] event Event to which to associate \p packet. +@param[in] packet Packet to associate to \p event. @returns 0 on success, or a negative value on error. @prenotnull{event} @@ -218,11 +244,13 @@ On success, this function also sets the parent stream object of stream class of \p event. @postsuccessrefcountretinc -@sa bt_ctf_event_get_packet(): Returns the associated packet of a +@sa bt_event_get_packet(): Returns the associated packet of a given event object. */ -extern int bt_ctf_event_set_packet(struct bt_ctf_event *event, - struct bt_ctf_packet *packet); +extern int bt_event_set_packet(struct bt_event *event, + struct bt_packet *packet); + +extern struct bt_stream *bt_event_borrow_stream(struct bt_event *event); /** @brief Returns the parent CTF IR stream associated to the CTF IR event @@ -235,8 +263,11 @@ extern int bt_ctf_event_set_packet(struct bt_ctf_event *event, @postrefcountsame{event} @postsuccessrefcountretinc */ -extern struct bt_ctf_stream *bt_ctf_event_get_stream( - struct bt_ctf_event *event); +static inline +struct bt_stream *bt_event_get_stream(struct bt_event *event) +{ + return bt_get(bt_event_borrow_stream(event)); +} /** @} */ @@ -245,6 +276,8 @@ extern struct bt_ctf_stream *bt_ctf_event_get_stream( @{ */ +extern struct bt_field *bt_event_borrow_header(struct bt_event *event); + /** @brief Returns the stream event header field of the CTF IR event \p event. @@ -259,19 +292,23 @@ extern struct bt_ctf_stream *bt_ctf_event_get_stream( @postrefcountsame{event} @postsuccessrefcountretinc -@sa bt_ctf_event_get_header(): Sets the stream event header +@sa bt_event_get_header(): Sets the stream event header field of a given event. */ -extern struct bt_ctf_field *bt_ctf_event_get_header( - struct bt_ctf_event *event); +static inline +struct bt_field *bt_event_get_header(struct bt_event *event) +{ + return bt_get(bt_event_borrow_header(event)); +} /** @brief Sets the stream event header field of the CTF IR event - \p event to \p header. + \p event to \p header, or unsets the current stream event header field + from \p event. -The field type of \p header, as returned by bt_ctf_field_get_type(), -\em must be equivalent to the field type returned by -bt_ctf_stream_class_get_event_header_type() for the parent stream class +If \p header is not \c NULL, the field type of \p header, as returned by +bt_field_get_type(), \em must be equivalent to the field type returned by +bt_stream_class_get_event_header_type() for the parent stream class of \p event. @param[in] event Event of which to set the stream event header @@ -280,19 +317,22 @@ of \p event. @returns 0 on success, or a negative value on error. @prenotnull{event} -@prenotnull{header} @prehot{event} -@pre \p header has a field type equivalent to the field type returned by - bt_ctf_stream_class_get_event_header_type() for the parent - stream class of \p event. +@pre \p header, if not \c NULL, has a field type equivalent to + the field type returned by bt_stream_class_get_event_header_type() + for the parent stream class of \p event. @postrefcountsame{event} -@postsuccessrefcountinc{header} +@post On success, if \p header is not \c NULL, + the reference count of \p header is incremented. -@sa bt_ctf_event_get_header(): Returns the stream event header field +@sa bt_event_get_header(): Returns the stream event header field of a given event. */ -extern int bt_ctf_event_set_header(struct bt_ctf_event *event, - struct bt_ctf_field *header); +extern int bt_event_set_header(struct bt_event *event, + struct bt_field *header); + +extern struct bt_field *bt_event_borrow_stream_event_context( + struct bt_event *event); /** @brief Returns the stream event context field of the CTF IR event @@ -308,204 +348,139 @@ extern int bt_ctf_event_set_header(struct bt_ctf_event *event, @postrefcountsame{event} @postsuccessrefcountretinc -@sa bt_ctf_event_set_stream_event_context(): Sets the stream event - context field of a given event. +@sa bt_event_set_stream_event_context(): Sets the stream event context + field of a given event. */ -extern struct bt_ctf_field *bt_ctf_event_get_stream_event_context( - struct bt_ctf_event *event); +static inline +struct bt_field *bt_event_get_stream_event_context(struct bt_event *event) +{ + return bt_get(bt_event_borrow_stream_event_context(event)); +} /** @brief Sets the stream event context field of the CTF IR event - \p event to \p context. + \p event to \p context, or unsets the current stream event context field + from \p event. -The field type of \p context, as returned by bt_ctf_field_get_type(), -\em must be equivalent to the field type returned by -bt_ctf_stream_class_get_event_context_type() for the parent stream class +If \p context is not \c NULL, the field type of \p context, as returned by +bt_field_get_type(), \em must be equivalent to the field type returned by +bt_stream_class_get_event_context_type() for the parent stream class of \p event. -@param[in] event Event of which to set the stream event context - field. +@param[in] event Event of which to set the stream event context field. @param[in] context Stream event context field. @returns 0 on success, or a negative value on error. @prenotnull{event} -@prenotnull{context} @prehot{event} -@pre \p context has a field type equivalent to the field type returned - by bt_ctf_stream_class_get_event_context_type() for the parent - stream class of \p event. +@pre \p context, if not \c NULL, has a field type equivalent to + the field type returned by bt_stream_class_get_event_context_type() + for the parent stream class of \p event. @postrefcountsame{event} -@postsuccessrefcountinc{context} +@post On success, if \p context is not \c NULL, the reference + count of \p context is incremented. -@sa bt_ctf_event_get_stream_event_context(): Returns the stream event - context field of a given event. +@sa bt_event_get_stream_event_context(): Returns the stream event context + field of a given event. */ -extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event *event, - struct bt_ctf_field *context); +extern int bt_event_set_stream_event_context(struct bt_event *event, + struct bt_field *context); + +extern struct bt_field *bt_event_borrow_context(struct bt_event *event); /** -@brief Returns the event context field of the CTF IR event - \p event. +@brief Returns the event context field of the CTF IR event \p event. -@param[in] event Event of which to get the event context - field. -@returns Event context field of \p event, or \c NULL if - the event context field is not set or on error. +@param[in] event Event of which to get the context field. +@returns Event context field of \p event, or \c NULL if the + event context field is not set or on error. @prenotnull{event} @postrefcountsame{event} @postsuccessrefcountretinc -@sa bt_ctf_event_set_event_context(): Sets the event context field of a - given event. +@sa bt_event_set_context(): Sets the event context field of a given + event. */ -extern struct bt_ctf_field *bt_ctf_event_get_event_context( - struct bt_ctf_event *event); +static inline +struct bt_field *bt_event_get_context(struct bt_event *event) +{ + return bt_get(bt_event_borrow_context(event)); +} /** -@brief Sets the event context field of the CTF IR event - \p event to \p context. +@brief Sets the event context field of the CTF IR event \p event to \p context, + or unsets the current event context field from \p event. -The field type of \p context, as returned by bt_ctf_field_get_type(), -\em must be equivalent to the field type returned by -bt_ctf_event_class_get_context_type() for the parent event class -of \p event. +If \p context is not \c NULL, the field type of \p context, as returned by +bt_field_get_type(), \em must be equivalent to the field type returned by +bt_event_class_get_context_type() for the parent class of \p event. -@param[in] event Event of which to set the event context field. +@param[in] event Event of which to set the context field. @param[in] context Event context field. @returns 0 on success, or a negative value on error. @prenotnull{event} -@prenotnull{context} @prehot{event} -@pre \p context has a field type equivalent to the field type returned - by bt_ctf_event_class_get_context_type() for the parent - event class of \p event. +@pre \p context, if not \c NULL, has a field type equivalent to + the field type returned by bt_event_class_get_context_type() for the + parent class of \p event. @postrefcountsame{event} -@postsuccessrefcountinc{context} +@post On success, if \p context is not \c NULL, the reference + count of \p context is incremented. -@sa bt_ctf_event_get_event_context(): Returns the event context field of - a given event. +@sa bt_event_get_context(): Returns the context field of a given event. */ -extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event, - struct bt_ctf_field *context); +extern int bt_event_set_context(struct bt_event *event, + struct bt_field *context); + +extern struct bt_field *bt_event_borrow_payload(struct bt_event *event); /** -@brief Returns the event payload field of the CTF IR event - \p event. +@brief Returns the payload field of the CTF IR event \p event. -@param[in] event Event of which to get the event payload - field. -@returns Event payload field of \p event, or \c NULL if - the event payload field is not set or on error. +@param[in] event Event of which to get the payload field. +@returns Payload field of \p event, or \c NULL if the payload + field is not set or on error. @prenotnull{event} @postrefcountsame{event} @postsuccessrefcountretinc -@sa bt_ctf_event_set_payload_field(): Sets the event payload field of a - given event. +@sa bt_event_set_payload(): Sets the payload field of a given + event. */ -extern struct bt_ctf_field *bt_ctf_event_get_payload_field( - struct bt_ctf_event *event); +static inline +struct bt_field *bt_event_get_payload(struct bt_event *event) +{ + return bt_get(bt_event_borrow_payload(event)); +} /** -@brief Sets the event payload field of the CTF IR event - \p event to \p payload. +@brief Sets the payload field of the CTF IR event \p event to \p payload, + or unsets the current event payload field from \p event. -The field type of \p payload, as returned by bt_ctf_field_get_type(), -\em must be equivalent to the field type returned by -bt_ctf_event_class_get_payload_type() for the parent event class -of \p event. +If \p payload is not \c NULL, the field type of \p payload, as returned by +bt_field_get_type(), \em must be equivalent to the field type returned by +bt_event_class_get_payload_type() for the parent class of \p event. -@param[in] event Event of which to set the event payload field. +@param[in] event Event of which to set the payload field. @param[in] payload Event payload field. @returns 0 on success, or a negative value on error. @prenotnull{event} -@prenotnull{payload} @prehot{event} -@pre \p payload has a field type equivalent to the field type returned - by bt_ctf_event_class_get_payload_type() for the parent - event class of \p event. +@pre \p payload, if not \c NULL, has a field type equivalent to + the field typereturned by bt_event_class_get_payload_type() for the + parent class of \p event. @postrefcountsame{event} -@postsuccessrefcountinc{payload} - -@sa bt_ctf_event_get_payload_field(): Returns the event payload field of - a given event. -*/ -extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event, - struct bt_ctf_field *payload); +@post On success, if \p payload is not \c NULL, the reference + count of \p payload is incremented. -/** -@cond DOCUMENT -*/ - -/* - * TODO: Doxygenize. - * - * bt_ctf_event_get_payload: get an event's field. - * - * Returns the field matching "name". bt_put() must be called on the - * returned value. - * - * @param event Event instance. - * @param name Event field name, see notes. - * - * Returns a field instance on success, NULL on error. - * - * Note: Passing a name will cause the function to perform a look-up by - * name assuming the event's payload is a structure. This will return - * the raw payload instance if name is NULL. - */ -extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event, - const char *name); - -/* - * TODO: Doxygenize. - * - * bt_ctf_event_get_payload_by_index: Get event's field by index. - * - * Returns the field associated with the provided index. bt_put() - * must be called on the returned value. The indexes to be provided are - * the same as can be retrieved from the event class. - * - * @param event Event. - * @param index Index of field. - * - * Returns the event's field, NULL on error. - * - * Note: Will return an error if the payload's type is not a structure. - */ -extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index( - struct bt_ctf_event *event, int index); - -/* - * TODO: Doxygenize. - * - * bt_ctf_event_set_payload: set an event's field. - * - * Set a manually allocated field as an event's payload. The event will share - * the field's ownership by using its reference count. - * bt_put() must be called on the returned value. - * - * @param event Event instance. - * @param name Event field name, see notes. - * @param value Instance of a field whose type corresponds to the event's field. - * - * Returns 0 on success, a negative value on error. - * - * Note: The function will return an error if a name is provided and the payload - * type is not a structure. If name is NULL, the payload field will be set - * directly and must match the event class' payload's type. - */ -extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, - const char *name, - struct bt_ctf_field *value); - -/** -@endcond +@sa bt_event_get_payload(): Returns the payload field of a given event. */ +extern int bt_event_set_payload(struct bt_event *event, + struct bt_field *payload); /** @} */ @@ -514,6 +489,10 @@ extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, @{ */ +extern struct bt_clock_value *bt_event_borrow_clock_value( + struct bt_event *event, + struct bt_clock_class *clock_class); + /** @brief Returns the value, as of the CTF IR event \p event, of the clock described by the @@ -531,37 +510,38 @@ extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, @postrefcountsame{clock_class} @postsuccessrefcountretinc -@sa bt_ctf_event_set_clock_value(): Sets the clock value of a given event. +@sa bt_event_set_clock_value(): Sets the clock value of a given event. */ -extern struct bt_ctf_clock_value *bt_ctf_event_get_clock_value( - struct bt_ctf_event *event, struct bt_ctf_clock *clock_class); +static inline +struct bt_clock_value *bt_event_get_clock_value( + struct bt_event *event, + struct bt_clock_class *clock_class) +{ + return bt_get(bt_event_borrow_clock_value(event, clock_class)); +} /** @brief Sets the value, as of the CTF IR event \p event, of the - clock described by the - \link ctfirclockclass CTF IR clock class\endlink \p clock_class. + clock described by its \link ctfirclockclass CTF IR + clock class\endlink. @param[in] event Event of which to set the value of the clock - described by \p clock_class. -@param[in] clock_class Class of the clock of which to set the value - for \p event. -@param[in] clock_value Value of the clock described by \p clock_class + described by the clock class of \p clock_value. +@param[in] clock_value Value of the clock described by its clock class as of \p event. @returns 0 on success, or a negative value on error. @prenotnull{event} -@prenotnull{clock_class} @prenotnull{clock_value} @prehot{event} @postrefcountsame{event} -@postrefcountsame{clock_class} -@sa bt_ctf_event_get_clock_value(): Returns the clock value of +@sa bt_event_get_clock_value(): Returns the clock value of a given event. */ -extern int bt_ctf_event_set_clock_value( - struct bt_ctf_event *event, struct bt_ctf_clock *clock_class, - struct bt_ctf_clock_value *clock_value); +extern int bt_event_set_clock_value( + struct bt_event *event, + struct bt_clock_value *clock_value); /** @} */