$ make
\endverbatim
-\subsection tracing_tracing_functions Tracing Functions
-
-\li <b>\c TRACE_category (const char *category)</b>: This function should be used
-to define a user category. The category can be used to differentiate the tasks
-that are created during the simulation (for example, tasks from server1,
-server2, or request tasks, computation tasks, communication tasks).
-All resource utilization (host power and link bandwidth) will be
-classified according to the task category. Tasks that do not belong to a
-category are not traced. The color for the category that is being declared
-is random (use next function to specify a color).
-
-\li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
-as TRACE_category, but let user specify a color encoded as a RGB-like string with
-three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
-color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
-
-\li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
-This function should be called after the creation of a MSG task, to define the
-category of that task. The first parameter \c task must contain a task that was
-created with the function \c MSG_task_create. The second parameter
-\c category must contain a category that was previously defined by the function
-\c TRACE_category.
+\subsection instr_category_functions Tracing categories functions
+\li \c TRACE_category(const char *category)
+\li \c TRACE_category_with_color(const char *category, const char *color)
+\li \c MSG_task_set_category(m_task_t task, const char *category)
+\li \c MSG_task_get_category(m_task_t task)
\li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
This function should be called after the creation of a SimDAG task, to define the
\c category must contain a category that was previously defined by the function
\c TRACE_category.
-\li <b>\c TRACE_declare_mark(const char *mark_type)</b>: This function
-declares a new Paje event type in the trace file that can be used by
-simulators to declare application-level marks. This function is
-independent of which API is used in SimGrid.
-
-\li <b>\c TRACE_mark(const char *mark_type, const char *mark_value)</b>:
-This function creates a mark in the trace file. The first parameter
-had to be previously declared using \c TRACE_declare_mark, the second
-is the identifier for this mark instance. We recommend that the \c
-mark_value (the second parameter) is a unique value for the whole
-trace file (the whole simulation). Nevertheless, this is not a strong
-requirement: the trace will be valid if there are multiple mark
-identifiers for the same trace.
+\subsection instr_mark_functions Tracing marks functions
+\li \c TRACE_declare_mark(const char *mark_type)
+\li \c TRACE_mark(const char *mark_type, const char *mark_value)
+
+\subsection instr_uservariables_functions Tracing user variables functions
\li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
Declare a user variable that will be associated to host/link. A variable can
#include "simgrid_config.h"
#ifdef HAVE_TRACING
-
#include "instr/instr_private.h"
#include "surf/network_private.h"
XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
+/** \ingroup TRACE_category
+ * \brief Declare a new category with a random color.
+ *
+ * This function should be used to define a user category. The
+ * category can be used to differentiate the tasks that are created
+ * during the simulation (for example, tasks from server1, server2,
+ * or request tasks, computation tasks, communication tasks). All
+ * resource utilization (host power and link bandwidth) will be
+ * classified according to the task category. Tasks that do not
+ * belong to a category are not traced. The color for the category
+ * that is being declared is random. This function has no effect
+ * if a category with the same name has been already declared.
+ *
+ * See \ref tracing_tracing for details on how to trace
+ * the (categorized) resource utilization.
+ *
+ * \param category The name of the new tracing category to be created.
+ *
+ * \see TRACE_category_with_color, MSG_task_set_category
+ */
void TRACE_category(const char *category)
{
TRACE_category_with_color (category, NULL);
}
+/** \ingroup TRACE_category
+ * \brief Declare a new category with a color.
+ *
+ * Same as #TRACE_category, but let user specify a color encoded as a
+ * RGB-like string with three floats from 0 to 1. So, to specify a
+ * red color, pass "1 0 0" as color parameter. A light-gray color
+ * can be specified using "0.7 0.7 0.7" as color. This function has
+ * no effect if a category with the same name has been already declared.
+ *
+ * See \ref tracing_tracing for details on how to trace
+ * the (categorized) resource utilization.
+ *
+ * \param category The name of the new tracing category to be created.
+ * \param color The color of the category (see \ref tracing_tracing to
+ * know how to correctly specify the color)
+ *
+ * \see MSG_task_set_category
+ */
void TRACE_category_with_color (const char *category, const char *color)
{
/* safe switch */
instr_new_variable_type (category, final_color);
}
+/** \ingroup TRACE_mark
+ * \brief Declare a new type for tracing mark.
+ *
+ * This function declares a new Paje event
+ * type in the trace file that can be used by
+ * simulators to declare application-level
+ * marks. This function is independent of
+ * which API is used in SimGrid.
+ *
+ * \param mark_type The name of the new type.
+ *
+ * \see TRACE_mark
+ */
void TRACE_declare_mark(const char *mark_type)
{
/* safe switch */
PJ_type_event_new(mark_type, NULL, PJ_type_get_root());
}
+/**
+ * \ingroup TRACE_mark
+ * \brief Create a new instance of a tracing mark type.
+ *
+ * This function creates a mark in the trace file. The
+ * first parameter had to be previously declared using
+ * #TRACE_declare_mark, the second is the identifier
+ * for this mark instance. We recommend that the
+ * mark_value is a unique value for the whole simulation.
+ * Nevertheless, this is not a strong requirement: the
+ * trace will be valid even if there are multiple mark
+ * identifiers for the same trace.
+ *
+ * \param mark_type The name of the type for which the new instance will belong.
+ * \param mark_value The name of the new instance mark.
+ *
+ * \see TRACE_declare_mark
+ */
void TRACE_mark(const char *mark_type, const char *mark_value)
{
/* safe switch */
}
/** \ingroup msg_gos_functions
+ * \brief Sets the tracing category of a task.
+ *
+ * This function should be called after the creation of
+ * a MSG task, to define the category of that task. The
+ * first parameter #task must contain a task that was
+ * created with the function #MSG_task_create. The second
+ * parameter #category must contain a category that was
+ * previously declared with the function #TRACE_category
+ * (or with #TRACE_category_with_color).
*
* See \ref tracing_tracing for details on how to trace
* the (categorized) resource utilization.
*
- * \brief Sets the tracing category of a task.
- *
* \param task the task that is going to be categorized
* \param category the name of the category to be associated to the task
*
#endif
}
-
/** \ingroup msg_gos_functions
*
* \brief Gets the current tracing category of a task.
