From: Arnaud Giersch Date: Thu, 10 Dec 2020 20:13:32 +0000 (+0100) Subject: Move bits of documentation for recently converted tracing examples. X-Git-Tag: v3.26~19 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/ee6a764f17a132153060b0956781f59077b9d02f Move bits of documentation for recently converted tracing examples. --- diff --git a/examples/README.rst b/examples/README.rst index 0b74ab5ae0..fec86d863b 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -724,6 +724,71 @@ options to see the task executions: .. example-tab:: examples/s4u/trace-platform/s4u-trace-platform.cpp + - **Setting Categories** + This example declares several tracing categories to that are used to + classify its tasks. When the program is executed, the tracing mechanism + registers the resource utilization of hosts and links according to these + categories. Recommended options: + ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes`` + + .. tabs:: + + .. example-tab:: examples/s4u/trace-categories/trace-categories.cpp + + - **Master Workers tracing** + This is an augmented version of our basic master/worker example using + several tracing features. It traces resource usage, sorted out in several + categories; Trace marks and user variables are also used. Recommended + options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes`` + + .. tabs:: + + .. example-tab:: examples/s4u/trace-masterworkers/trace-masterworkers.cpp + + - **Process migration tracing** + This version is enhanced so that the process migrations can be displayed + as arrows in a Gantt-chart visualization. Recommended options to that + extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes`` + + .. tabs:: + + .. example-tab:: examples/s4u/trace-process-migration/trace-process-migration.cpp + +.. + TODO: These tracing examples should be integrated in the examples to not + duplicate the C++ files. A full command line to see the result in the right + tool (vite/FrameSoc) should be given along with some screenshots. + +Tracing user variables +---------------------- + +You can also attach your own variables to any resource described in the platform +file. The following examples illustrate this feature. They have to be run with +the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes`` + + - **Attaching variables to Hosts** + + .. tabs:: + + .. example-tab:: examples/s4u/trace-host-user-variables/trace-host-user-variables.cpp + + - **Attaching variables to Links** + The tricky part is that you have to know the name of the link you want to + enhance with a variable. + + .. tabs:: + + .. example-tab:: examples/s4u/trace-link-user-variables/trace-link-user-variables.cpp + + - **Attaching variables to network Routes** + It is often easier to update a given variable for all links of a given + network path (identified by its source and destination hosts) instead of + knowing the name of each specific link. + + .. tabs:: + + .. example-tab:: examples/s4u/trace-route-user-variables/trace-route-user-variables.cpp + ======================== Larger SimGrid Examplars ======================== diff --git a/examples/deprecated/msg/README.doc b/examples/deprecated/msg/README.doc index 9f60fb9902..e3c89ad81d 100644 --- a/examples/deprecated/msg/README.doc +++ b/examples/deprecated/msg/README.doc @@ -4,93 +4,9 @@ /** @defgroup msg_examples MSG examples @ingroup MSG_API - @brief Find the MSG example fitting your needs from the extensive set provided in the archive. - - @ref msg_ex_tracing - - @ref msg_ex_tracing_user_variables - -@warning MSG was deprecated in SimGrid v3.18. These examples should be - converted to S4U in the next releases. You really should - consider using S4U in your next project. - -@section msg_ex_tracing Tracing and visualization features - -Tracing can be activated by various configuration options which -are illustrated in these example. See also the -@ref tracing_tracing_options "full list of options related to tracing". - -It is interesting to run the process-create example with the following -options to see the task executions: - - - Setting Categories. - @ref examples/deprecated/msg/trace-categories/trace-categories.c \n - This example declares several tracing categories - to that are used to classify its tasks. When the program is executed, - the tracing mechanism registers the resource utilization of hosts - and links according to these categories. Recommended options: - @verbatim --cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes - @endverbatim - - - Master Workers tracing. - @ref examples/deprecated/msg/trace-masterworker/trace-masterworker.c \n - This is an augmented version of our basic master/worker example - using several tracing features. It traces resource usage, sorted - out in several categories; Trace marks and user variables are also - used. Recommended options: - @verbatim --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes - @endverbatim - - - Process migration tracing. - @ref examples/deprecated/msg/trace-process-migration/trace-process-migration.c \n - This version is enhanced so that the process migrations can be - displayed as arrows in a Gantt-chart visualization. Recommended - options to that extend: - @verbatim -cfg=tracing:yes --cfg=tracing/msg/process:yes - @endverbatim - -TODO: These tracing examples should be integrated in the examples to -not duplicate the C files. A full command line to see the result in -the right tool (vite/FrameSoc) should be given along with some -screenshots. - -@subsection msg_ex_tracing_user_variables Tracing user variables - -You can also attach your own variables to any resource described in -the platform file. The following examples illustrate this feature. -They have to be run with the following options: -@verbatim --cfg=tracing:yes --cfg=tracing/platform:yes -@endverbatim - - - Attaching variables to Hosts. - @ref examples/deprecated/msg/trace-host-user-variables/trace-host-user-variables.c - - - Attaching variables to Links. - @ref examples/deprecated/msg/trace-link-user-variables/trace-link-user-variables.c \n - The tricky part is that you have to know the name of the link you - want to enhance with a variable. - - - Attaching variables to network Routes - @ref examples/deprecated/msg/trace-route-user-variables/trace-route-user-variables.c \n - It is often easier to update a given variable for all links of a - given network path (identified by its source and destination - hosts) instead of knowing the name of each specific link. - -// As a human, you can stop reading at this point. The rest is garbage: -// -// Every example must be listed in the following, but it's not possible -// to move this content upper as each @example directive seems to eat -// everything until the next */ marker (and the content is placed at the -// top of the example file). - - -/** - -@example examples/deprecated/msg/trace-categories/trace-categories.c -@example examples/deprecated/msg/trace-masterworker/trace-masterworker.c -@example examples/deprecated/msg/trace-process-migration/trace-process-migration.c -@example examples/deprecated/msg/trace-host-user-variables/trace-host-user-variables.c -@example examples/deprecated/msg/trace-link-user-variables/trace-link-user-variables.c -@example examples/deprecated/msg/trace-route-user-variables/trace-route-user-variables.c +@warning MSG was deprecated in SimGrid v3.18. + You really should consider using S4U in your next project. */