From 51e6b67c8e8e69f068544f8026a3ffdc9da70e72 Mon Sep 17 00:00:00 2001 From: schnorr Date: Sat, 24 Mar 2012 19:21:35 +0100 Subject: [PATCH] [trace] improve documentation of tracing API, make tracing.doc points to them --- doc/tracing.doc | 45 ++++++------------------ src/instr/instr_interface.c | 70 ++++++++++++++++++++++++++++++++++++- src/msg/msg_gos.c | 12 +++++-- 3 files changed, 88 insertions(+), 39 deletions(-) diff --git a/doc/tracing.doc b/doc/tracing.doc index 2c590eeb83..257852f3c5 100644 --- a/doc/tracing.doc +++ b/doc/tracing.doc @@ -46,28 +46,11 @@ $ cmake -Denable_tracing=ON . $ make \endverbatim -\subsection tracing_tracing_functions Tracing Functions - -\li \c TRACE_category (const char *category): 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 \c TRACE_category_with_color (const char *category, const char *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, 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 \c TRACE_msg_set_task_category (m_task_t task, const char *category): -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 \c TRACE_sd_set_task_category (SD_task_t task, const char *category): This function should be called after the creation of a SimDAG task, to define the @@ -76,19 +59,11 @@ 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. -\li \c TRACE_declare_mark(const char *mark_type): 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 \c TRACE_mark(const char *mark_type, const char *mark_value): -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 \c TRACE_[host|link]_variable_declare (const char *variable): Declare a user variable that will be associated to host/link. A variable can diff --git a/src/instr/instr_interface.c b/src/instr/instr_interface.c index fc03a78247..e241c8fad2 100644 --- a/src/instr/instr_interface.c +++ b/src/instr/instr_interface.c @@ -7,7 +7,6 @@ #include "simgrid_config.h" #ifdef HAVE_TRACING - #include "instr/instr_private.h" #include "surf/network_private.h" @@ -20,11 +19,49 @@ typedef enum { 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 */ @@ -58,6 +95,19 @@ void TRACE_category_with_color (const char *category, const char *color) 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 */ @@ -69,6 +119,24 @@ void TRACE_declare_mark(const char *mark_type) 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 */ diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c index 7043c047d4..2205fcdc5d 100644 --- a/src/msg/msg_gos.c +++ b/src/msg/msg_gos.c @@ -875,12 +875,19 @@ int MSG_task_listen_from(const char *alias) } /** \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 * @@ -893,7 +900,6 @@ void MSG_task_set_category (m_task_t task, const char *category) #endif } - /** \ingroup msg_gos_functions * * \brief Gets the current tracing category of a task. -- 2.20.1