Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
adding test example to trace process migration using the mask TRACE_PROCESS
[simgrid.git] / include / gras / emul.h
1 /* $Id$                     */
2
3 /* gras/emul.h - public interface to emulation support                      */
4 /*                (specific parts for SG or RL)                             */
5
6 /* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved.            */
7
8 /* This program is free software; you can redistribute it and/or modify it
9  * under the terms of the license (GNU LGPL) which comes with this package. */
10
11 #ifndef GRAS_COND_H
12 #define GRAS_COND_H
13
14 #include "xbt/misc.h"           /* SG_BEGIN_DECL */
15
16 SG_BEGIN_DECL()
17 /** @addtogroup GRAS_emul
18  *  @brief Code execution "emulation" and "virtualization".
19  * 
20  *  Emulation and virtualization words have a lot of different meanings in
21  *  computer science. Here is what we mean, and what this module allows you
22  *  to do (if it does not match your personal belives, I'm sorry):
23  * 
24  *  - Virtualization: Having some specific code for the simulation or for the reality
25  *  - Emulation: Report within the simulator the execution time of your code
26  * 
27  *  \section GRAS_emul_virtualization Virtualization 
28  * 
29  *  The whole idea of GRAS is to share the same code between the simulator
30  *  and the real implementation. But it is sometimes impossible, such as
31  *  when you want to deal with the OS. As an example, you may want to add
32  *  some extra delay before initiating a communication in RL to ensure that
33  *  the receiver is listening. This is usually useless in SG since you have
34  *  a much better control on process launch time.
35  * 
36  *  This would be done with the following snipet:
37  *  \verbatim if (gras_if_RL()) 
38    gras_os_sleep(1);\endverbatim
39  * 
40  *  Please note that those are real functions and not pre-processor
41  *  defines. This is to ensure that the same object code can be linked
42  *  against the SG library or the RL one without recompilation.
43  * 
44  *  @{
45  */
46 /** \brief Returns true only if the program runs on real life */
47 XBT_PUBLIC(int) gras_if_RL(void);
48
49 /** \brief Returns true only if the program runs within the simulator */
50 XBT_PUBLIC(int) gras_if_SG(void);
51
52 /** @} */
53
54 XBT_PUBLIC(int) gras_bench_always_begin(const char *location, int line);
55 XBT_PUBLIC(int) gras_bench_always_end(void);
56 XBT_PUBLIC(int) gras_bench_once_begin(const char *location, int line);
57 XBT_PUBLIC(int) gras_bench_once_end(void);
58
59 /** @addtogroup GRAS_emul
60  *  \section GRAS_emul_timing Emulation
61  *  
62  *  For simulation accuracy, it is mandatory to report the execution time
63  *  of your code into the simulator. For example, if your application is a
64  *  parallel matrix multiplication, you naturally have to slow down the
65  *  simulated hosts actually doing the computation.
66  *  
67  *  If you know beforehands how long each task will last, simply add a call
68  *  to the gras_bench_fixed function described below. If not, you can have
69  *  GRAS benchmarking your code automatically. Simply enclose the code to
70  *  time between a macro GRAS_BENCH_*_BEGIN and GRAS_BENCH_*_END, and
71  *  you're done. There is three pair of such macros, whose characteristics
72  *  are summarized in the following table. 
73  * 
74  *  <table>
75  *   <tr>
76  *    <td><b>Name</b></td> 
77  *    <td><b>Run on host machine?</b></td>
78  *    <td><b>Benchmarked?</b></td>
79  *    <td><b>Corresponding time reported to simulation?</b></td>
80  *   </tr> 
81  *   <tr>
82  *    <td>GRAS_BENCH_ALWAYS_BEGIN()<br> 
83  *        GRAS_BENCH_ALWAYS_END()</td> 
84  *    <td>Each time</td>
85  *    <td>Each time</td>
86  *    <td>Each time</td>
87  *   </tr>
88  *   <tr>
89  *    <td>GRAS_BENCH_ONCE_RUN_ONCE_BEGIN()<br> 
90  *        GRAS_BENCH_ONCE_RUN_ONCE_END()</td>
91  *    <td>Only first time</td>
92  *    <td>Only first time</td>
93  *    <td>Each time (with stored value)</td>
94  *   </tr>
95  *   <tr>
96  *    <td>GRAS_BENCH_ONCE_RUN_ALWAYS_BEGIN()<br> 
97  *        GRAS_BENCH_ONCE_RUN_ALWAYS_END()</td>
98  *    <td>Each time</td>
99  *    <td>Only first time</td>
100  *    <td>Each time (with stored value)</td>
101  *   </tr>
102  *  </table>
103  *  
104  *  As you can see, whatever macro pair you use, the corresponding value is
105  *  repported to the simulator. After all, that's what those macro are
106  *  about ;)
107  * 
108  *  The GRAS_BENCH_ALWAYS_* macros are the simplest ones. Each time the
109  *  corresponding block is encountered, the corresponding code is executed
110  *  and timed. Then, the simulated host is given the corresponding amount
111  *  of work.
112  * 
113  *  The GRAS_BENCH_ONCE_RUN_ONCE_* macros are good for cases where you know
114  *  that your execution time is constant and where you don't care about the
115  *  result in simulation mode. In our example, each sub-block
116  *  multiplication takes exactly the same amount of work (time depends only
117  *  on size, not on content), and the operation result can safely be
118  *  ignored for algorithm result. Doing so allows you to considerably
119  *  reduce the amount of computation needed when running on simulator.
120  * 
121  *  The GRAS_BENCH_ONCE_RUN_ALWAYS_* macros are good for cases where you
122  *  know that each block will induce the same amount of work (you thus
123  *  don't want to bench it each time), but you actually need the result (so
124  *  you have to run it each time). You may ask why you don't use
125  *  GRAS_BENCH_ONCE_RUN_ONCE_* macros in this case (why you save the
126  *  benchmarking time).  The timing operation is not very intrusive by
127  *  itself, but it has to be done in an exclusive way between the several
128  *  GRAS threads (protected by mutex). So, the day where there will be
129  *  threads in GRAS, this will do a big difference. Ok, I agree. For now,
130  *  it makes no difference.
131  * 
132  *  <b>Caveats</b>
133  * 
134  *   - Blocks are automatically differenciated using the filename and line
135  *     position at which the *_BEGIN part was called. Don't put two of them
136  *     on the same line.
137  * 
138  *   - You cannot nest blocks. It would make no sense, either.
139  * 
140  *   - By the way, GRAS is not exactly designed for parallel algorithm such
141  *     as parallel matrix multiplication but for distributed ones, you weirdo.
142  *     But it's just an example ;)
143  *  
144  * @{
145  */
146 /** \brief Start benchmarking this code block
147     \hideinitializer */
148 #define GRAS_BENCH_ALWAYS_BEGIN()           gras_bench_always_begin(__FILE__, __LINE__)
149 /** \brief Stop benchmarking this code block
150     \hideinitializer */
151 #define GRAS_BENCH_ALWAYS_END()             gras_bench_always_end()
152
153 /** \brief Start benchmarking this code block if it has never been benchmarked, run it in any case
154  *  \hideinitializer */
155 #define GRAS_BENCH_ONCE_RUN_ALWAYS_BEGIN()  gras_bench_once_begin(__FILE__, __LINE__)
156 /** \brief Stop benchmarking this part of the code
157     \hideinitializer */
158 #define GRAS_BENCH_ONCE_RUN_ALWAYS_END()    gras_bench_once_end()
159
160 /** \brief Start benchmarking this code block if it has never been benchmarked, ignore it if it was
161     \hideinitializer */
162 #define GRAS_BENCH_ONCE_RUN_ONCE_BEGIN()    if (gras_bench_once_begin(__FILE__, __LINE__)) {
163 /** \brief Stop benchmarking this part of the code
164     \hideinitializer */
165 #define GRAS_BENCH_ONCE_RUN_ONCE_END()      } gras_bench_once_end()
166
167 XBT_PUBLIC(void) gras_cpu_burn(double flops);
168 /** @} */
169
170 SG_END_DECL()
171 #endif /* GRAS_COND_H */