examples/msg/README.doc

   1 This file follows the Doxygen syntax to be included in the documentation.
   2
   3 /**
   4  @defgroup MSG_examples MSG examples
   5  @ingroup MSG_API
   6  @brief Find the MSG example fitting your needs from the extensive set provided in the archive.
   7
   8   - @ref msg_ex_basic
   9   - @ref msg_ex_async
  10   - @ref msg_ex_process
  11   - @ref msg_ex_tracing
  12   - @ref msg_ex_tracing_user_variables
  13   - @ref msg_ex_models
  14   - @ref msg_ex_io
  15   - @ref msg_ex_actions
  16   - @ref msg_ex_full_apps
  17   - @ref msg_ex_misc
  18
  19 @section msg_ex_basic Basic examples and features
  20
  21  - <b>Ping Pong</b>: @ref examples/msg/app-pingpong/app-pingpong.c\n
  22    It's hard to think of a simpler example: it is just sending one
  23    message back and forth.
  24    The tesh file laying in the directory show how to start the
  25    simulator binary, enlighting how to pass options to the simulators
  26    (as detailed in Section \ref options).
  27
  28  - <b>Token Ring</b>.
  29    @ref examples/msg/app-token-ring/app-token-ring.c\n
  30    Classical communication pattern, where a token is exchanged
  31    along a ring to reach every participant.
  32    The tesh file laying in the directory shows how to run the same
  33    example on different virtual platforms.
  34
  35  - <b>Master Workers</b>.
  36    @ref examples/msg/app-masterworker/app-masterworker.c\n
  37    Another good old example, where one Master process has a bunch of
  38    task to dispatch to a set of several Worker processes. It is fully
  39    commented in @ref MSG_ex_master_worker.
  40
  41 @section msg_ex_async Asynchronous communications
  42
  43 In addition to the fully documented example of @ref
  44 MSG_ex_asynchronous_communications, there are several other examples
  45 shipped in the archive:
  46
  47  - <b>Basic asynchronous communications</b>.
  48    @ref examples/msg/async-wait/async-wait.c \n
  49    Illustrates how to have non-blocking communications, that are
  50    communications running in the background leaving the process free
  51    to do something else during their completion. The main functions
  52    involved are @ref MSG_task_isend, @ref MSG_task_irecv, and @ref
  53    MSG_comm_wait.
  54
  55  - <b>Waiting for all communications in a set</b>.
  56    @ref examples/msg/async-waitall/async-waitall.c\n
  57    The @ref MSG_comm_waitall function is useful when you want to block
  58    until all activities in a given set have completed.
  59
  60  - <b>Waiting for the first completed communication in a set</b>.
  61    @ref examples/msg/async-waitall/async-waitany.c\n
  62    The @ref MSG_comm_waitany function is useful when you want to block
  63    until one activity of the set completes, no matter which terminates
  64    first.
  65
  66 */
  67
  68 As a human, you can stop reading at this point. The rest is garbage:
  69
  70 Every example must be listed in the following, but it's not possible
  71 to move this content upper as each example directive seems to eat the
  72 next doxygen commands.
  73
  74
  75 /**
  76 @defgroup MSG_ex_examples ignored
  77 @example examples/msg/app-pingpong/app-pingpong.c
  78 @example examples/msg/app-token-ring/app-token-ring.c
  79 @example examples/msg/app-masterworker/app-masterworker.c
  80
  81 @example examples/msg/async-wait/async-wait.c
  82 @example examples/msg/async-waitall/async-waitall.c
  83 @example examples/msg/async-waitall/async-waitany.c
  84 */
  85
  86 Basic examples and features
  87 ===========================
  88
  89  * migration/migration.c Demonstrates how to use the
  90    MSG_process_migrate() function to let processes change the host
  91    they run on after their start.
  92
  93  * suspend/suspend.c: Demonstrates how to suspend and resume processes
  94    using MSG_process_suspend() and MSG_process_resume().
  95
  96  * properties/msg_prop.c Attaching arbitrary information to host,
  97    processes and such, and retrieving them with
  98    MSG_host_get_properties(), MSG_host_get_property_value(),
  99    MSG_process_get_properties() and MSG_process_get_property_value().
 100    Also make sure to read the platform and deployment XML files to see
 101    how to declare these data.
 102
 103  * parallel_task/parallel_task.c: Demonstrates the use of
 104    MSG_parallel_task_create(), to create special tasks that run on
 105    several hosts at the same time. The resulting simulations are very
 106    close to what can be achieved in SimDag, but still allows to use
 107    the other features of MSG (it'd be cool to be able to mix
 108    interfaces, but it's not possible ATM).
 109
 110  * priority/priority.c: Demonstrates the use of
 111    MSG_task_set_priority() to change the computation priority of a
 112    given task.
 113
 114 Tracing and visualization features
 115 ==================================
 116  * tracing/simple.c very simple program that creates, executes and
 117    destroy a task
 118  * tracing/ms.c TODO
 119  * tracing/categories.c example with the declaration of multiple
 120    categories
 121  * tracing/procmig.c example to trace process migration using the mask
 122    TRACE_PROCESS
 123  * tracing/trace_platform.c: Demonstrates how to trace the platform
 124  * tracing/user_variables.c: Demonstrates how to trace user-provided
 125    variables
 126
 127 Models-related examples
 128 =======================
 129
 130 Packet level simulators
 131 -----------------------
 132 These examples demonstrate how to use the bindings to classical
 133 Packet-Level Simulators (PLS), as explained in the relevant part of
 134 the web documentation. The most interesting is probably not the C
 135 files since they are unchanged from the other simulations, but the
 136 associated files, such as the platform files to see how to declare a
 137 platform to be used with the PLS bindings of SimGrid and the tesh
 138 files to see how to actually start a simulation in these settings.
 139
 140  * ns3: Simple ping-pong using ns3 instead of the SimGrid models
 141  * gtnets Simple ping-pong using GTNeTs instead of the SimGrid models
 142
 143 Other resource kinds
 144 --------------------
 145 This section contains some sparse examples of how to use the other
 146 kind of resources, such as disk. These resources are quite
 147 experimental for now, but here we go anyway.
 148
 149  * io/file.c Example with the disk resource
 150
 151 Trace driven simulations
 152 ========================
 153
 154 The actions/actions.c example demonstrates how to run trace-driven
 155 simulations. It is very handy when you want to test an algorithm or
 156 protocol that does nothing unless it receives some events from
 157 outside. For example, a P2P protocol reacts to requests from the user,
 158 but does nothing if there is no such event.
 159
 160 In such situations, SimGrid allows to write your protocol in your C
 161 file, and the events to react to in a separate text file. Declare a
 162 function handling each of the events that you want to accept in your
 163 trace files, register them using MSG_action_register in your main, and
 164 then use MSG_action_trace_run to launch the simulation. You can either
 165 have one trace file containing all your events, or a file per
 166 simulated process. Check the tesh files in the example directory for
 167 details on how to do it.
 168
 169 This example uses this approach to replay MPI-like traces. It comes
 170 with a set of event handlers reproducing MPI events. This is somehow
 171 similar to SMPI, yet differently implemented. This code should
 172 probably be changed to use SMPI internals instead, but wasn't, so far.
 173
 174 Examples of full applications
 175 =============================
 176
 177  * chord/chord.c: Classical Chord P2P protocol This example implements
 178    the well known Chord P2P protocol. Its main advantage is that it
 179    constitute a fully working non-trivial example. In addition, its
 180    implementation is rather efficient, as demonstrated in
 181    [57]http://hal.inria.fr/inria-00602216/
 182
 183