examples/msg/README

   1 This file follows the Doxygen syntax to be included in the documentation.
   2
   3 /**
   4 MSG comes with an extensive set of examples. It is sometimes difficult
   5 to find the one you need. This list aims at helping you finding the
   6 example from which you can learn what you want to.
   7
   8 Basic examples and features
   9 ===========================
  10  * sendrecv/sendrecv.c: Ping-pong example. It's hard to think of a
  11    simpler example. The tesh files laying in the directory are
  12    instructive concerning the way to pass options to the simulators
  13    (as described in "Simgrid options and configurations").
  14
  15  * masterslave/masterslave_forwarder.c: Master/slaves example. This
  16    good old example is also very simple. Its basic version is fully
  17    commented in the web documentation, but several variants can be
  18    found in the same directory.
  19
  20  * masterslave/masterslave_console.c: demonstrate how to use lua files
  21    instead of XML for the platform and deployment declaration using
  22    MSG_load_platform_script(). The most interesting part is probably
  23    not the C code, but rather the masterslave/masterslave_script.lua,
  24    which demonstrates how to express the platform and deployment in
  25    lua.
  26
  27  * migration/migration.c Demonstrates how to use the
  28    MSG_process_migrate() function to let processes change the host
  29    they run on after their start.
  30
  31  * suspend/suspend.c: Demonstrates how to suspend and resume processes
  32    using MSG_process_suspend() and MSG_process_resume().
  33
  34  * properties/msg_prop.c Attaching arbitrary information to host,
  35    processes and such, and retrieving them with
  36    MSG_host_get_properties(), MSG_host_get_property_value(),
  37    MSG_process_get_properties() and MSG_process_get_property_value().
  38    Also make sure to read the platform and deployment XML files to see
  39    how to declare these data.
  40
  41  * parallel_task/parallel_task.c: Demonstrates the use of
  42    MSG_parallel_task_create(), to create special tasks that run on
  43    several hosts at the same time. The resulting simulations are very
  44    close to what can be achieved in SimDag, but still allows to use
  45    the other features of MSG (it'd be cool to be able to mix
  46    interfaces, but it's not possible ATM).
  47
  48  * priority/priority.c: Demonstrates the use of
  49    MSG_task_set_priority() to change the computation priority of a
  50    given task.
  51
  52 Asynchronous communications
  53 ===========================
  54 There is several examples of asynchronous communications coming in the
  55 archive. In addition to the fully documented example [50]Asynchronous
  56 communications, there is several other examples in the archive:
  57
  58  * msg/icomms/peer.c: basic example of async functions
  59    (MSG_task_isend, MSG_task_irecv, MSG_comm_wait)
  60  * msg/icomms/peer2.c: demonstrates the MSG_comm_waitall() function
  61  * msg/icomms/peer3.c: demonstrates the MSG_comm_waitany() function
  62
  63 Tracing and visualization features
  64 ==================================
  65  * tracing/simple.c very simple program that creates, executes and
  66    destroy a task
  67  * tracing/ms.c TODO
  68  * tracing/categories.c example with the declaration of multiple
  69    categories
  70  * tracing/procmig.c example to trace process migration using the mask
  71    TRACE_PROCESS
  72  * tracing/trace_platform.c: Demonstrates how to trace the platform
  73  * tracing/user_variables.c: Demonstrates how to trace user-provided
  74    variables
  75
  76 Models-related examples
  77 =======================
  78
  79 Packet level simulators
  80 -----------------------
  81 These examples demonstrate how to use the bindings to classical
  82 Packet-Level Simulators (PLS), as explained in the relevant part of
  83 the web documentation. The most interesting is probably not the C
  84 files since they are unchanged from the other simulations, but the
  85 associated files, such as the platform files to see how to declare a
  86 platform to be used with the PLS bindings of SimGrid and the tesh
  87 files to see how to actually start a simulation in these settings.
  88
  89  * ns3: Simple ping-pong using ns3 instead of the SimGrid models
  90  * gtnets Simple ping-pong using GTNeTs instead of the SimGrid models
  91
  92 Other resource kinds
  93 --------------------
  94 This section contains some sparse examples of how to use the other
  95 kind of resources, such as disk. These resources are quite
  96 experimental for now, but here we go anyway.
  97
  98  * io/file.c Example with the disk resource
  99
 100 Trace driven simulations
 101 ========================
 102
 103 The actions/actions.c example demonstrates how to run trace-driven
 104 simulations. It is very handy when you want to test an algorithm or
 105 protocol that does nothing unless it receives some events from
 106 outside. For example, a P2P protocol reacts to requests from the user,
 107 but does nothing if there is no such event.
 108
 109 In such situations, SimGrid allows to write your protocol in your C
 110 file, and the events to react to in a separate text file. Declare a
 111 function handling each of the events that you want to accept in your
 112 trace files, register them using MSG_action_register in your main, and
 113 then use MSG_action_trace_run to launch the simulation. You can either
 114 have one trace file containing all your events, or a file per
 115 simulated process. Check the tesh files in the example directory for
 116 details on how to do it.
 117
 118 This example uses this approach to replay MPI-like traces. It comes
 119 with a set of event handlers reproducing MPI events. This is somehow
 120 similar to SMPI, yet differently implemented. This code should
 121 probably be changed to use SMPI internals instead, but wasn't, so far.
 122
 123 Examples of full applications
 124 =============================
 125
 126  * token_ring/ring_call.c: Classical token ring communication, where a
 127    token is exchanged along a ring to reach every participant.
 128
 129  * pmm/msg_pmm.c: Parallel Matrix Multiplication is a little
 130    application. This is something that most MPI developper have
 131    written during their class, here implemented using MSG instead of
 132    MPI.
 133
 134  * chord/chord.c: Classical Chord P2P protocol This example implements
 135    the well known Chord P2P protocol. Its main advantage is that it
 136    constitute a fully working non-trivial example. In addition, its
 137    implementation is rather efficient, as demonstrated in
 138    [57]http://hal.inria.fr/inria-00602216/
 139
 140
 141 */