X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fevent-class.h;h=12d78015c90be8297fecee8f3f46c4a5f58b492e;hb=312c056ae3d374b253fa0cfe5ed576c0b0e5e569;hp=5052f70fa551452ef09e745cf222b7f6e583e963;hpb=9ac68eb139149d2768848dae5e263cc5a755d439;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/event-class.h b/include/babeltrace/ctf-ir/event-class.h index 5052f70f..12d78015 100644 --- a/include/babeltrace/ctf-ir/event-class.h +++ b/include/babeltrace/ctf-ir/event-class.h @@ -30,14 +30,18 @@ * http://www.efficios.com/ctf */ +/* For bt_get() */ +#include + #include #include -#include #ifdef __cplusplus extern "C" { #endif +struct bt_value; + /** @defgroup ctfireventclass CTF IR event class @ingroup ctfir @@ -50,12 +54,14 @@ extern "C" { A CTF IR event class is a template that you can use to create concrete \link ctfirevent CTF IR events\endlink. -An event class has the following properties, both of which \em must -be unique amongst all the event classes contained in the same -\link ctfirstreamclass CTF IR stream class\endlink: +An event class has the following properties: - A \b name. -- A numeric \b ID. +- A numeric \b ID (\em must be unique amongst all the event classes + contained in the same + \link ctfirstreamclass CTF IR stream class\endlink). +- A optional log level. +- An optional Eclipse Modeling Framework URI. A CTF IR event class owns two \link ctfirfieldtypes field types\endlink: @@ -78,8 +84,8 @@ class\endlink contains zero or more \link ctfirstreamclass stream classes\endlink, and a stream class contains zero or more event classes. Before you can create an event from an event class with -bt_ctf_event_create(), you \em must add the prepared event class to a -stream class by calling bt_ctf_stream_class_add_event_class(). This +bt_event_create(), you \em must add the prepared event class to a +stream class by calling bt_stream_class_add_event_class(). This function, when successful, \em freezes the event class, disallowing any future modification of its properties and field types by the user. @@ -88,7 +94,7 @@ As with any Babeltrace object, CTF IR event class objects have counts. See \ref refs to learn more about the reference counting management of Babeltrace objects. -bt_ctf_stream_class_add_event_class() \em freezes its event class +bt_stream_class_add_event_class() \em freezes its event class parameter on success. You cannot modify a frozen event class: it is considered immutable, except for \link refs reference counting\endlink. @@ -104,14 +110,70 @@ considered immutable, except for \link refs reference counting\endlink. */ /** -@struct bt_ctf_event_class +@struct bt_event_class @brief A CTF IR event class. @sa ctfireventclass */ -struct bt_ctf_event_class; -struct bt_ctf_field; -struct bt_ctf_field_type; -struct bt_ctf_stream_class; +struct bt_event_class; +struct bt_field; +struct bt_field_type; +struct bt_stream_class; + +/** +@brief Log level of an event class. +*/ +enum bt_event_class_log_level { + /// Unknown, used for errors. + BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN = -1, + + /// Unspecified log level. + BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED = 255, + + /// System is unusable. + BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY = 0, + + /// Action must be taken immediately. + BT_EVENT_CLASS_LOG_LEVEL_ALERT = 1, + + /// Critical conditions. + BT_EVENT_CLASS_LOG_LEVEL_CRITICAL = 2, + + /// Error conditions. + BT_EVENT_CLASS_LOG_LEVEL_ERROR = 3, + + /// Warning conditions. + BT_EVENT_CLASS_LOG_LEVEL_WARNING = 4, + + /// Normal, but significant, condition. + BT_EVENT_CLASS_LOG_LEVEL_NOTICE = 5, + + /// Informational message. + BT_EVENT_CLASS_LOG_LEVEL_INFO = 6, + + /// Debug information with system-level scope (set of programs). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM = 7, + + /// Debug information with program-level scope (set of processes). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM = 8, + + /// Debug information with process-level scope (set of modules). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS = 9, + + /// Debug information with module (executable/library) scope (set of units). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE = 10, + + /// Debug information with compilation unit scope (set of functions). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT = 11, + + /// Debug information with function-level scope. + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION = 12, + + /// Debug information with line-level scope (default log level). + BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE = 13, + + /// Debug-level message. + BT_EVENT_CLASS_LOG_LEVEL_DEBUG = 14, +}; /** @name Creation and parent access functions @@ -121,23 +183,32 @@ struct bt_ctf_stream_class; /** @brief Creates a default CTF IR event class named \p name­. -The event class is created \em without an event context -\link ctfirfieldtypes field type\endlink and with an empty event -payload field type. +On success, the context and payload field types are empty structure +field types. You can modify those default field types after the +event class is created with +bt_event_class_set_context_field_type() and +bt_event_class_set_payload_field_type(). Upon creation, the event class's ID is not set. You -can set it to a specific value with bt_ctf_event_class_set_id(). If it -is still unset when you call bt_ctf_stream_class_add_event_class(), then +can set it to a specific value with bt_event_class_set_id(). If it +is still unset when you call bt_stream_class_add_event_class(), then the stream class assigns a unique ID to this event class before freezing it. +The created event class's log level is initially set to +#BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED and it has no Eclipse Modeling +Framework URI. + @param[in] name Name of the event class to create (copied on success). @returns Created event class, or \c NULL on error. @prenotnull{name} @postsuccessrefcountret1 */ -extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name); +extern struct bt_event_class *bt_event_class_create(const char *name); + +extern struct bt_stream_class *bt_event_class_borrow_stream_class( + struct bt_event_class *event_class); /** @brief Returns the parent CTF IR stream class of the CTF IR event @@ -146,7 +217,7 @@ extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name); It is possible that the event class was not added to a stream class yet, in which case this function returns \c NULL. You can add an event class to a stream class with -bt_ctf_stream_class_add_event_class(). +bt_stream_class_add_event_class(). @param[in] event_class Event class of which to get the parent stream class. @@ -158,11 +229,15 @@ bt_ctf_stream_class_add_event_class(). @postrefcountsame{event_class} @postsuccessrefcountretinc -@sa bt_ctf_stream_class_add_event_class(): Add an event class to +@sa bt_stream_class_add_event_class(): Add an event class to a stream class. */ -extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class( - struct bt_ctf_event_class *event_class); +static inline +struct bt_stream_class *bt_event_class_get_stream_class( + struct bt_event_class *event_class) +{ + return bt_get(bt_event_class_borrow_stream_class(event_class)); +} /** @} */ @@ -184,8 +259,8 @@ string. @prenotnull{event_class} @postrefcountsame{event_class} */ -extern const char *bt_ctf_event_class_get_name( - struct bt_ctf_event_class *event_class); +extern const char *bt_event_class_get_name( + struct bt_event_class *event_class); /** @brief Returns the numeric ID of the CTF IR event class \p event_class. @@ -197,11 +272,11 @@ extern const char *bt_ctf_event_class_get_name( @prenotnull{event_class} @postrefcountsame{event_class} -@sa bt_ctf_event_class_set_id(): Sets the numeric ID of a given +@sa bt_event_class_set_id(): Sets the numeric ID of a given event class. */ -extern int64_t bt_ctf_event_class_get_id( - struct bt_ctf_event_class *event_class); +extern int64_t bt_event_class_get_id( + struct bt_event_class *event_class); /** @brief Sets the numeric ID of the CTF IR event class @@ -219,140 +294,106 @@ of the stream class to which you eventually add \p event_class. @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX). @postrefcountsame{event_class} -@sa bt_ctf_event_class_get_id(): Returns the numeric ID of a given +@sa bt_event_class_get_id(): Returns the numeric ID of a given event class. */ -extern int bt_ctf_event_class_set_id( - struct bt_ctf_event_class *event_class, uint64_t id); +extern int bt_event_class_set_id( + struct bt_event_class *event_class, uint64_t id); /** -@brief Returns the number of attributes contained in the CTF IR event - class \p event_class. +@brief Returns the log level of the CTF IR event class \p event_class. -@param[in] event_class Event class of which to get the number - of contained attributes. -@returns Number of contained attributes in - \p event_class, or a negative value on error. +@param[in] event_class Event class of which to get the log level. +@returns Log level of event class \p event_class, + #BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED if + not specified, or + #BT_EVENT_CLASS_LOG_LEVEL_UNKNOWN on error. @prenotnull{event_class} @postrefcountsame{event_class} -@sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name - of the attribute of a given event class at a given index. -@sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value - of the attribute of a given event class at a given index. +@sa bt_event_class_set_log_level(): Sets the log level of a given + event class. */ -extern int64_t bt_ctf_event_class_get_attribute_count( - struct bt_ctf_event_class *event_class); +extern enum bt_event_class_log_level bt_event_class_get_log_level( + struct bt_event_class *event_class); /** -@brief Returns the name of the attribute at the index \p index of the - CTF IR event class \p event_class. - -On success, \p event_class remains the sole owner of the returned -string. +@brief Sets the log level of the CTF IR event class + \p event_class to \p log_level. -@param[in] event_class Event class of which to get the name - of an attribute. -@param[in] index Index of the attribute of which to get the name. -@returns Attribute name, or \c NULL on error. +@param[in] event_class Event class of which to set the log level. +@param[in] log_level Log level of the event class. +@returns 0 on success, or a negative value on error. @prenotnull{event_class} -@pre \p index is lesser than the number of attributes contained by - \p event_class. +@prehot{event_class} +@pre \p log_level is #BT_EVENT_CLASS_LOG_LEVEL_UNSPECIFIED, + #BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY, + #BT_EVENT_CLASS_LOG_LEVEL_ALERT, + #BT_EVENT_CLASS_LOG_LEVEL_CRITICAL, + #BT_EVENT_CLASS_LOG_LEVEL_ERROR, + #BT_EVENT_CLASS_LOG_LEVEL_WARNING, + #BT_EVENT_CLASS_LOG_LEVEL_NOTICE, + #BT_EVENT_CLASS_LOG_LEVEL_INFO, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION, + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE, or + #BT_EVENT_CLASS_LOG_LEVEL_DEBUG. @postrefcountsame{event_class} -@sa bt_ctf_event_class_get_attribute_value_by_index(): Returns the value - of the attribute of a given event class at a given index. +@sa bt_event_class_get_log_level(): Returns the log level of a given + event class. */ -extern const char * -bt_ctf_event_class_get_attribute_name_by_index( - struct bt_ctf_event_class *event_class, uint64_t index); +extern int bt_event_class_set_log_level( + struct bt_event_class *event_class, + enum bt_event_class_log_level log_level); /** -@brief Returns the value of the attribute at the index \p index of the - CTF IR event class \p event_class. +@brief Returns the Eclipse Modeling Framework URI of the CTF IR event + class \p event_class. -@param[in] event_class Event class of which to get the value - of an attribute. -@param[in] index Index of the attribute of which to get the value. -@returns Attribute value, or \c NULL on error. +@param[in] event_class Event class of which to get the + Eclipse Modeling Framework URI. +@returns Eclipse Modeling Framework URI of event + class \p event_class, or \c NULL on error. @prenotnull{event_class} -@pre \p index is lesser than the number of attributes contained by - \p event_class. -@postsuccessrefcountretinc @postrefcountsame{event_class} -@sa bt_ctf_event_class_get_attribute_name_by_index(): Returns the name - of the attribute of a given event class at a given index. -*/ -extern struct bt_value * -bt_ctf_event_class_get_attribute_value_by_index( - struct bt_ctf_event_class *event_class, uint64_t index); - -/** -@brief Returns the value of the attribute named \p name of the CTF IR - event class \p event_class. - -On success, the reference count of the returned value object is -incremented. - -@param[in] event_class Event class of which to get the value - of an attribute. -@param[in] name Name of the attribute to get. -@returns Attribute value, or \c NULL on error. - -@prenotnull{event_class} -@prenotnull{name} -@postsuccessrefcountretinc -@postrefcountsame{event_class} +@sa bt_event_class_set_emf_uri(): Sets the Eclipse Modeling + Framework URI of a given event class. */ -extern struct bt_value * -bt_ctf_event_class_get_attribute_value_by_name( - struct bt_ctf_event_class *event_class, const char *name); +extern const char *bt_event_class_get_emf_uri( + struct bt_event_class *event_class); /** -@brief Sets the attribute named \p name of the CTF IR event class - \p event_class to the value \p value. +@brief Sets the Eclipse Modeling Framework URI of the CTF IR event class + \p event_class to \p emf_uri, or unsets the event class's EMF URI. -Valid attributes, as of Babeltrace \btversion, are: - -- id: \em must be an integer value object with a raw value - that is greater than or equal to 0. This represents the event class's - numeric ID and you can also set it with bt_ctf_event_class_set_id(). - -- name: must be a string value object. This represents - the name of the event class. - -- loglevel: must be an integer value object with a raw - value greater than or equal to 0. This represents the numeric log level - associated with this event class. Log level values - are application-specific. - -- model.emf.uri: must be a string value object. This - represents the application-specific Eclipse Modeling Framework URI - of the event class. - -@param[in] event_class Event class of which to set an - attribute. -@param[in] name Attribute name (copied on success). -@param[in] value Attribute value. -@returns 0 on success, or a negative value on error. +@param[in] event_class Event class of which to set the + Eclipse Modeling Framework URI. +@param[in] emf_uri Eclipse Modeling Framework URI of the + event class (copied on success), or \c NULL + to unset the current EMF URI. +@returns 0 on success, or a negative value if there's + no EMF URI or on error. @prenotnull{event_class} -@prenotnull{name} -@prenotnull{value} +@prenotnull{emf_uri} @prehot{event_class} @postrefcountsame{event_class} -@postsuccessrefcountinc{value} -@sa bt_ctf_event_class_get_attribute_value_by_name(): Returns the - attribute of a given event class having a given name. +@sa bt_event_class_get_emf_uri(): Returns the Eclipse Modeling + Framework URI of a given event class. */ -extern int bt_ctf_event_class_set_attribute( - struct bt_ctf_event_class *event_class, const char *name, - struct bt_value *value); +extern int bt_event_class_set_emf_uri( + struct bt_event_class *event_class, + const char *emf_uri); /** @} */ @@ -361,6 +402,9 @@ extern int bt_ctf_event_class_set_attribute( @{ */ +extern struct bt_field_type *bt_event_class_borrow_context_field_type( + struct bt_event_class *event_class); + /** @brief Returns the context field type of the CTF IR event class \p event_class. @@ -374,11 +418,15 @@ extern int bt_ctf_event_class_set_attribute( @post On success, if the return value is a field type, its reference count is incremented. -@sa bt_ctf_event_class_set_context_type(): Sets the context field type of a +@sa bt_event_class_set_context_field_type(): Sets the context field type of a given event class. */ -extern struct bt_ctf_field_type *bt_ctf_event_class_get_context_type( - struct bt_ctf_event_class *event_class); +static inline +struct bt_field_type *bt_event_class_get_context_field_type( + struct bt_event_class *event_class) +{ + return bt_get(bt_event_class_borrow_context_field_type(event_class)); +} /** @brief Sets the context field type of the CTF IR event class \p event_class to @@ -406,12 +454,15 @@ As of Babeltrace \btversion, if \p context_type is not \c NULL, @post On success, if \p context_type is not \c NULL, the reference count of \p context_type is incremented. -@sa bt_ctf_event_class_get_context_type(): Returns the context field type of a +@sa bt_event_class_get_context_field_type(): Returns the context field type of a given event class. */ -extern int bt_ctf_event_class_set_context_type( - struct bt_ctf_event_class *event_class, - struct bt_ctf_field_type *context_type); +extern int bt_event_class_set_context_field_type( + struct bt_event_class *event_class, + struct bt_field_type *context_type); + +extern struct bt_field_type *bt_event_class_borrow_payload_field_type( + struct bt_event_class *event_class); /** @brief Returns the payload field type of the CTF IR event class @@ -426,11 +477,15 @@ extern int bt_ctf_event_class_set_context_type( @post On success, if the return value is a field type, its reference count is incremented. -@sa bt_ctf_event_class_set_payload_type(): Sets the payload field type of a +@sa bt_event_class_set_payload_field_type(): Sets the payload field type of a given event class. */ -extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type( - struct bt_ctf_event_class *event_class); +static inline +struct bt_field_type *bt_event_class_get_payload_field_type( + struct bt_event_class *event_class) +{ + return bt_get(bt_event_class_borrow_payload_field_type(event_class)); +} /** @brief Sets the payload field type of the CTF IR event class \p event_class to @@ -458,133 +513,12 @@ As of Babeltrace \btversion, if \p payload_type is not \c NULL, @post On success, if \p payload_type is not \c NULL, the reference count of \p payload_type is incremented. -@sa bt_ctf_event_class_get_payload_type(): Returns the payload field type of a +@sa bt_event_class_get_payload_field_type(): Returns the payload field type of a given event class. */ -extern int bt_ctf_event_class_set_payload_type( - struct bt_ctf_event_class *event_class, - struct bt_ctf_field_type *payload_type); - -/** -@brief Returns the number of fields contained in the - payload field type of the CTF IR event class \p event_class. - -@remarks -Calling this function is the equivalent of getting the payload field -type of \p event_class with bt_ctf_event_class_get_payload_type() and -getting its field count with -bt_ctf_field_type_structure_get_field_count(). - -@param[in] event_class Event class of which to get the number - of fields contained in its payload field type. -@returns Number of fields in the payload field type - of \p event_class, or a negative value on error. - -@prenotnull{event_class} -@postrefcountsame{event_class} -*/ -extern int64_t bt_ctf_event_class_get_payload_type_field_count( - struct bt_ctf_event_class *event_class); - -/** -@brief Returns the type and the name of the field at index \p index - in the payload field type of the CTF IR event class - \p event_class. - -On success, the field's type is placed in \p *field_type if -\p field_type is not \c NULL. The field's name is placed in -\p *name if \p name is not \c NULL. \p event_class remains the sole -owner of \p *name. - -Both \p name and \p field_type can be \c NULL if the caller is not -interested in one of them. - -@remarks -Calling this function is the equivalent of getting the payload field -type of \p event_class with bt_ctf_event_class_get_payload_type() and -getting the type and name of one of its field with -bt_ctf_field_type_structure_get_field(). - -@param[in] event_class Event class of which to get the type and name - of a field in its payload field type. -@param[out] field_name Name of the field at the index - \p index in the payload field type of - \p event_class (can be \c NULL). -@param[out] field_type Type of the field at the index \p index in the - payload field type of \p event_class - (can be \c NULL). -@param[in] index Index of the payload field type's field to find. -@returns 0 on success, or a negative value on error. - -@prenotnull{event_class} -@pre \p index is lesser than the number of fields contained in the - payload field type of \p event_class (see - bt_ctf_event_class_get_payload_type_field_count()). -@postrefcountsame{event_class} -@post On success, if \p field_type is not \c NULL, the - reference count of \p *field_type is incremented. -*/ -extern int bt_ctf_event_class_get_payload_type_field_by_index( - struct bt_ctf_event_class *event_class, - const char **field_name, struct bt_ctf_field_type **field_type, - uint64_t index); - -/** -@brief Returns the type of the field named \p name in the payload - field type of the CTF IR event class \p event_class. - -@remarks -Calling this function is the equivalent of getting the payload field -type of \p event_class with bt_ctf_event_class_get_payload_type() and -getting the type of one of its field with -bt_ctf_field_type_structure_get_field_type_by_name(). - -@param[in] event_class Event class of which to get the type of a - payload field type's field. -@param[in] name Name of the payload field type's field to get. -@returns Type of the field named \p name in the payload - field type of \p event_class, or \c NULL if - the function cannot find the field or - on error. - -@prenotnull{event_class} -@prenotnull{name} -@postrefcountsame{event_class} -@postsuccessrefcountretinc -*/ -extern struct bt_ctf_field_type * -bt_ctf_event_class_get_payload_type_field_type_by_name( - struct bt_ctf_event_class *event_class, const char *name); - -/* Pre-2.0 CTF writer compatibility */ -#define bt_ctf_event_class_get_field_by_name bt_ctf_event_class_get_payload_type_field_type_by_name - -/** -@brief Adds a field named \p name with the type \p field_type to the - payload field type of the CTF IR event class \p event_class. - -@remarks -Calling this function is the equivalent of getting the payload field -type of \p event_class with bt_ctf_event_class_get_payload_type() and -adding a field to it with bt_ctf_field_type_structure_add_field(). - -@param[in] event_class Event class containing the payload field - type in which to add a field. -@param[in] field_type Type of the field to add. -@param[in] name Name of the field to add (copied on - success). -@returns 0 on success, or a negative value on error. - -@prenotnull{event_class} -@prenotnull{type} -@prenotnull{name} -@prehot{event_class} -@postrefcountsame{event_class} -@postsuccessrefcountinc{field_type} -*/ -extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class, - struct bt_ctf_field_type *field_type, - const char *name); +extern int bt_event_class_set_payload_field_type( + struct bt_event_class *event_class, + struct bt_field_type *payload_type); /** @} */