From 68997e84e1199cbf17e3e3595022420af7cafb92 Mon Sep 17 00:00:00 2001 From: schnorr Date: Thu, 22 Mar 2012 13:15:22 +0100 Subject: [PATCH] document MSG tracing examples --- doc/Doxyfile.in | 2 ++ examples/msg/tracing/categories.c | 13 ++++++++++++- examples/msg/tracing/link_srcdst_user_variables.c | 15 +++++++++++++++ examples/msg/tracing/link_user_variables.c | 12 ++++++++++++ examples/msg/tracing/ms.c | 12 +++++++++++- examples/msg/tracing/procmig.c | 9 ++++++++- examples/msg/tracing/simple.c | 5 ++++- examples/msg/tracing/trace_platform.c | 8 +++++++- examples/msg/tracing/user_variables.c | 7 ++++++- 9 files changed, 77 insertions(+), 6 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index a23b712752..30e9c7e43a 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -693,6 +693,8 @@ INPUT += @top_srcdir@/examples/msg/sendrecv/sendrecv.c \ @top_srcdir@/examples/msg/tracing/procmig.c \ @top_srcdir@/examples/msg/tracing/trace_platform.c \ @top_srcdir@/examples/msg/tracing/user_variables.c \ + @top_srcdir@/examples/msg/tracing/link_user_variables.c \ + @top_srcdir@/examples/msg/tracing/link_srcdst_user_variables.c \ @top_srcdir@/examples/msg/ns3 \ @top_srcdir@/examples/msg/gtnets \ @top_srcdir@/examples/msg/io \ diff --git a/examples/msg/tracing/categories.c b/examples/msg/tracing/categories.c index 314addeab5..1c581c1f5c 100644 --- a/examples/msg/tracing/categories.c +++ b/examples/msg/tracing/categories.c @@ -6,7 +6,18 @@ /** @addtogroup MSG_examples * - * - tracing/categories.c example with the declaration of multiple categories + * - tracing/categories.c This is a master/slave program where the master creates + * tasks, send them to the slaves. For each task received, the slave executes + * it and then destroys it. This program declares several tracing categories that are + * used to classify tasks. When the program is executed, the tracing mechanism registers + * the resource utilization of hosts and links according to these categories. You might + * want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/categorized:1 + * --cfg=tracing/uncategorized:1 + * --cfg=triva/categorized:triva_cat.plist + * --cfg=triva/uncategorized:triva_uncat.plist + * (See \ref tracing_tracing_options for details) */ #include diff --git a/examples/msg/tracing/link_srcdst_user_variables.c b/examples/msg/tracing/link_srcdst_user_variables.c index 5dc745c43f..15d6eb3aaa 100644 --- a/examples/msg/tracing/link_srcdst_user_variables.c +++ b/examples/msg/tracing/link_srcdst_user_variables.c @@ -6,6 +6,21 @@ #include +/** @addtogroup MSG_examples + * + * - tracing/link_srcdst_user_variables.c: This program demonstrates how to + * trace user variables associated to the links of the platform file. Instead of + * providing the name of the link to update one of its variable, this example shows + * how to provide two hosts as parameter (source and destination, use their names as + * defined in the platform file). The tracing mechanism will get the route between + * these two hosts, if there is one defined in the platform file, and update the variable + * of all the links of that route to the value provided. + * You might want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/platform:1 + * (See \ref tracing_tracing_options for details) + */ + int master(int argc, char *argv[]); //dump function to create and execute a task diff --git a/examples/msg/tracing/link_user_variables.c b/examples/msg/tracing/link_user_variables.c index 9f7a5cfe95..7cdcbf4025 100644 --- a/examples/msg/tracing/link_user_variables.c +++ b/examples/msg/tracing/link_user_variables.c @@ -6,6 +6,18 @@ #include +/** @addtogroup MSG_examples + * + * - tracing/link_user_variables.c: This program demonstrates how to + * trace user variables associated to the links of the platform file. You need + * to provide the name of the link to update the value of the variable associated + * to that link. + * You might want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/platform:1 + * (See \ref tracing_tracing_options for details) + */ + int master(int argc, char *argv[]); //dump function to create and execute a task diff --git a/examples/msg/tracing/ms.c b/examples/msg/tracing/ms.c index df58acd05d..0e9c942d63 100644 --- a/examples/msg/tracing/ms.c +++ b/examples/msg/tracing/ms.c @@ -6,7 +6,17 @@ /** @addtogroup MSG_examples * - * - tracing/ms.c TODO + * - tracing/ms.c This is a master/slave program where the master creates + * tasks, send them to the slaves. For each task received, the slave executes + * it and then destroys it. This program uses several tracing functions that + * enable the tracing of categorized resource utilization, the use of trace marks, + * and user variables associated to the hosts of the platform file. + * You might want to run this program with the following parameters: + * --cfg=tracing/categorized:1 + * --cfg=tracing/uncategorized:1 + * --cfg=triva/categorized:triva_cat.plist + * --cfg=triva/uncategorized:triva_uncat.plist + * (See \ref tracing_tracing_options for details) */ #include diff --git a/examples/msg/tracing/procmig.c b/examples/msg/tracing/procmig.c index daa14662db..3c2121a41a 100644 --- a/examples/msg/tracing/procmig.c +++ b/examples/msg/tracing/procmig.c @@ -5,7 +5,14 @@ /** @addtogroup MSG_examples * - * - tracing/procmig.c example to trace process migration using the mask TRACE_PROCESS + * - tracing/procmig.c This program shows a process migration. Tracing + * this program with the options below enables a gantt-chart visualization + * of where the process has been during its execution. Migrations are represented by + * arrows from the origin to the destination host. + * You might want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/msg/process:1 + * (See \ref tracing_tracing_options for details) */ #include "msg/msg.h" /* core library */ diff --git a/examples/msg/tracing/simple.c b/examples/msg/tracing/simple.c index daaab12344..00f428aafa 100644 --- a/examples/msg/tracing/simple.c +++ b/examples/msg/tracing/simple.c @@ -12,7 +12,10 @@ * * @section MSG_ex_tracing Tracing and vizualization features * - * - tracing/simple.c very simple program that creates, executes and destroy a task + * - tracing/simple.c very simple program where each process creates, executes and + * destroy a task. You might want to run this program with the following parameters: + * --cfg=tracing/uncategorized:1 + * (See \ref tracing_tracing_options for details) */ /* Create a log channel to have nice outputs. */ diff --git a/examples/msg/tracing/trace_platform.c b/examples/msg/tracing/trace_platform.c index a3e9dd91db..ffcfaa1255 100644 --- a/examples/msg/tracing/trace_platform.c +++ b/examples/msg/tracing/trace_platform.c @@ -6,7 +6,13 @@ /** @addtogroup MSG_examples * - * - tracing/trace_platform.c: Demonstrates how to trace the platform + * - tracing/trace_platform.c: This program demonstrates how a + * platform file is traced to a Paje trace file format using the tracing + * mechanism of Simgrid. + * You might want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/categorized:1 + * (See \ref tracing_tracing_options for details) */ #include diff --git a/examples/msg/tracing/user_variables.c b/examples/msg/tracing/user_variables.c index 245e02681e..9cf0e43d49 100644 --- a/examples/msg/tracing/user_variables.c +++ b/examples/msg/tracing/user_variables.c @@ -6,7 +6,12 @@ /** @addtogroup MSG_examples * - * - tracing/user_variables.c: Demonstrates how to trace user-provided variables + * - tracing/user_variables.c: This program demonstrates how to + * trace user variables associated to the hosts of the platform file. + * You might want to run this program with the following parameters: + * --cfg=tracing:1 + * --cfg=tracing/platform:1 + * (See \ref tracing_tracing_options for details) */ #include -- 2.20.1