Logo AND Algorithmique Numérique Distribuée

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