1 /*! @page community_giveback Giving back to SimGrid
5 We are sometimes asked by users how to give back to the project. Here
6 are some ideas, but if you have new ones, feel free.
8 @section contributing_spread Spread the word
10 There is many ways to help the SimGrid project. The first and most
11 natural one is to <b>use it for your research, and say so</b>. Cite
12 the SimGrid framework in your paper and discuss of its advantages with
13 your colleagues to spread the word. When we ask for new fundings to
14 sustain the project, the amount of publications enabled by SimGrid is
15 always the first question that we get. The more you use the framework,
18 We use several systems to detect the scientific publications citing
19 our work, so actually citing correctly the framework (see
20 <a href="http://simgrid.gforge.inria.fr/Publications.html">here</a>)
21 should be enough to get us adding your paper to our list. But if you
22 remark that your paper is missing on
23 <a href="http://simgrid.gforge.inria.fr/Usages.html">our
24 page listing all papers using SimGrid</a>, please say so. Likewise, if
25 your paper is badly cited, please drop us an email so that we can fix
28 Also, <b>help us constituting an active and welcoming user
29 community</b>. Get subscribed to the mailing lists, and answer the
30 questions that newcommers have if you can. Point them (gentely ;) to
31 the relevant part of the documentation on need, and help them becoming
32 part of our community too.
34 Another easy way to help the project is to add a link to the
35 <a href="http://simgrid.gforge.inria.fr">SimGrid homepage</a>
36 on your homepage to <b>improve SimGrid's ranking in the search
37 engines</b>. Internet visibility is a battle where you can make the
38 difference. This can be done by adding the following html snipet to
39 your page, that simply renders as <a href="http://simgrid.gforge.inria.fr/">Simgrid</a>.
42 <a href="http://simgrid.gforge.inria.fr/"
43 title="Versatile simulation of distributed systems: Grid Simulator, P2P simulator, MPI simulator, Cloud Simulator or HPC Simulator">
47 Or you can prefer this version with a little logo (if you want to
48 contribute another logo for that, please don't hesitate ;)
49 <img src="http://simgrid.gforge.inria.fr/logos/simgrid_logo.png"/>
52 <a href="http://simgrid.gforge.inria.fr/"
53 title="Versatile simulation of distributed systems: Grid Simulator, P2P simulator, MPI simulator, Cloud Simulator or HPC Simulator">
54 <img src="http://simgrid.gforge.inria.fr/logos/simgrid_logo.png"
55 alt="Versatile simulation of distributed systems: Grid Simulator, P2P simulator, MPI simulator, Cloud Simulator or HPC Simulator" align="center">
59 Finally, if you organize a scientific event where you expect many
60 potential users, <b>invite us to give a tutorial on SimGrid</b>. We
61 found that 45 minutes to one hour is sufficient. It allows to explain
62 the main motivations and outcomes of the project in order to motivate
63 the attendees get more information on SimGrid, and eventually improve
64 their scientific habits by using a sound simulation framework.
65 <a href="http://webloria.loria.fr/~quinson/blog/2012/1120/Simgrid_at_Louvain/">Here</a>
66 is an example of such a presentation.
68 @section contributing_bugs Reporting (and fixing) any issue you find
70 Because of its size and complexity, SimGrid is not perfect and
71 contains a large amount of glitches and issues. When you find one,
72 don't assume that it's here because we don't care. It survived only
73 because nobody told us. We unfortunately cannot endlessly review our
74 large code and documentation base. So please, <b>report any issue you
75 find</b>, be it a typo in the documentation, a paragraph that
76 needs to be reworded, a bug in the code or any other problem. The best
77 way to do so is to open a bug on our
78 <a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">Bug
79 Tracking System</a> so that we don't forget about it (we have other
80 obligations too and are sometimes unable to fix bugs right away, no
81 matter how easy the fix it). The worst way to report such issue is to
82 go through private emails. These are unreliable, and we are trying to
83 develop SimGrid openly, so private discussions are to be avoided if
86 If you can provide a patch fixing the issue you report, that's even
87 better, and often ensures that it will get fixed very soon.
89 Of course, a very good way to give back to the SimGrid community is to
90 <b>triage and fix the bugs in the BTS</b>. If you
91 can come up with a patch fixing them, we will be more than happy to
92 apply your changes so that the entier community enjoys them.
94 @section contributing_contrib Contributing features and associated tools
96 If you deeply miss a feature in the framework, you should consider
97 implementing it yourself. That's free software, meaning that you are
98 free to help yourself. Of course, we'll do our best to assist you in
99 this task, so don't hesitate to contact us with your idea.
101 If you develop an independent tool that is somehow associated to
102 SimGrid, we'd love helping you gaining visibility by listing it on our
103 <a href="http://simgrid.gforge.inria.fr/contrib.html">Contrib
106 @section contributing_todo Enchancements
108 If you want to want to start working on the SimGrid codebase, here are a few
109 ideas of things that could be done to improved the current code (not all of them
112 @subsection contributing_todo_cxxification Migration to C++
114 The code is being migrated to C++ but a large part is still C (or C++ with
115 C idioms). It would be valuable to replace C idioms with C++ ones:
117 - replace XBT structures and C dynamic arrays with C++ containers;
119 - replace `char*` strings with `std::string`;
121 - use exception-safe RAII (`std::unique_ptr`, etc.) instead of explicit
122 `malloc/free` or `new/delete`;
124 - use `std::function` (or template functionoid arguments) instead of function
127 @subsubsection contributing_todo_exceptions Exceptions
129 SimGrid used to implement exceptions in C. This has been replaced with C++
130 exceptions but some bits of the C exceptions are still remaining:
132 - `xbt_ex` was the type of C exceptions. It is now a standard C++ exception.
133 We might want to remove this exception and use a more idiomatic C++
134 solution with dedicated exception classes for different errors.
135 `std::system_error` might be used as well by replacing some `xbt_errcat_t`
136 with custom subclasses of `std::error_category`.
138 - The C API currently throws exceptions. Throwing exceptions out of a C API is
139 not very friendly. C code does not expect them, cannot catch them and cannot
140 handle resource management properly in face of exceptions. We should clearly
141 separate the C++ API and the C API and catch all exceptions before they get
144 @subsubsection contributing_todo_time Time and duration
146 Some support for C++11-style time/duration is implemented (see `chrono.hpp`)
147 but only available in some (S4U) APIs. It would be nice to add support for
148 them in the rest of the C++ code.
150 A related change would be to avoid using "-1" to mean "forever" at least in S4U
151 and in the internal code. For compatibility, MSG should probably keep this
152 semantic. We should probably always use separate functions
153 (`wait` vs `wait_for`).
155 @subsubsection contributing_todo_futures Futures
157 - Some features are missing in the Maestro future implementation
158 (`simgrid::kernel::Future`, `simgrid::kernel::Promise`)
159 could be extended to support additional features:
160 `when_any`, `shared_future`, etc.
162 - The corresponding feature might then be implemented in the user process
163 futures (`simgrid::simix::Future`).
165 - Currently `.then()` is not available for user futures. We would need to add
166 a basic user event loop in order to queue the pending continuations.
168 - We might need to provide the option to cancel a pending operation. This
169 might be achieved by defining some `Action` or `Operation` class with an
170 API compatible with `Future` (and convertiable to it) but with an
171 additional `.cancel()` method.
173 @subsection contributing_todo_smpi SMPI
175 @subsubsection contributing_smpi_split_process Process-based privatization
177 Currently, all the simulated processes live in the same process as the SimGrid
178 simulator. The benefit is that we don't have to do context switches and IPC
179 between the simulator and the processes.
181 The fact that they share the same address space means that one memory corruption
182 in one simulated process can propagate to the other ones and the SimGrid
185 Moreover, the current design for SMPI applications is to compile the MPI code
186 normally and execute it once per simulated process in the same system process:
187 This means that all the existing simulated MPI processes share the same virtual
188 address space and share by default sthe same global variables. This is not
189 correct as each MPI process is expected to use its own address space and have
190 its own global variables. In order to fix, this problem we have an optional
191 SMPI privatization feature which creates a instanciation of the executable
192 data segment per MPI process and map the correct one (using `mmap`) at each
195 This approach has many problems:
197 1. It is not completely safe. We only handle SMPI privatization for the global
198 variables in the execute data segment. Shared objects are ignored but some
199 may contain global variables which may need to be privatized:
201 - libsimgrid for example must not be privatized because it contains
202 shared state for the simulator;
204 - libc must not be privatized for the same reason (but some global variables
205 in the libc may not be privatized);
207 - if we use global variables of some shared object in the executable, this
208 global variable will be instanciated in the executable (because of copy
209 relocation) and will be privatized even if it shoud not.
211 2. We cannot execute the MPI processes in parallel. Only one can execute at
212 the same time because only one privatization segment can be mapped at a
215 In order to fix this, the standard solution is to move each MPI process in its
216 system process and use IPC to communicate with the simulator. One concern would
217 be the impact on performance and memory consumption:
219 - It would introduce a lot of context switches and IPC communications between
220 the MPI processes and the SimGrid simulator. However, currently every context
221 switch needs a `mmap` for SMPI privatization which is costly as well
224 - Instanciating a lot of processes might consume more memory which might be a
225 problem if we want to simulate a lot of MPI processes. Compiling MPI programs
226 as static executables with a lightweight libc might help and we might want to
227 support that. The SMPI processes should probably not embed all the SimGrid
228 simulator and its dependencies, the C++ runtime, etc.
230 We would need to modify the model-checker as well which currently can only
231 manage on model-checked process. For the model-checker we can expect some
232 benefits from this approach: if a process did not execute, we know its state
233 did not change and we don't need to take its snapshot and compare its state.
235 Other solutions for this might include:
237 - Mapping each MPI process in the process of the simulator but in a different
238 symbol namespace (see `dlmopen`). Each process would have its own separate
239 instanciation and would not share libraries.
241 - Instanciate each MPI process in a separate lightweight VM (for example based
242 on WebAssembly) in the simualtor process.
244 @subsection contributing_todo_mc Model-checker
246 @subsubsection contributing_todo_mc_state_compare Overhaul the state comparison code
248 The state comparison code is quite complicated. It has very long functions and
249 is programmed mostly using C idioms and is difficult to understanda and debug.
250 It is in need or an overhaul:
252 - cleanup, refactorisation, usage of C++ features.
254 - The state comparison code works by infering types of blocks allocated on the
255 heap by following pointers from known roots (global variables, local
256 variables). Usually the first type found for a given block is used even if
257 a better one could be found later. By using a first pass of type inference,
258 on each snapshot before comparing the states, we might use a better type
259 information on the different blocks.
261 - We might benefit from adding logic for handling some known types. For
262 example, both `std::string` and `std::vector` have a capacity which might
263 be larger than the current size of the container. We should might ignore
264 the corresponding elements when comparing the states and infering the types.
266 - Another difficulty in the state comparison code is the detection of
267 dangling pointers. We cannot easily know if a pointer is dangling and
268 dangling pointers might lead us to choose the wrong type when infering
269 heap blocks. We might mitigate this problem by delaying the reallocation of
270 a freed block until there is no blocks pointing to it anymore using some
271 sort of basic garbage-collector.
273 @subsubsection contributing_todo_state_hashing Hashing the states
275 In order to speed up the state comparison an idea was to create a hash of the
276 state. Only states with the same hash would need to be compared using the
277 state comparison algorithm. Some information should not be inclueded in the
278 hash in order to avoid considering different states which would otherwise
279 would have been considered equal.
281 The stated could be indexed by their hash. Currently they are indexed
282 by the number of processes and the amount of heap currently allocated
283 (see `DerefAndCompareByNbProcessesAndUsedHeap`).
285 Good candidate informations for the state hashing:
287 - number of processes;
289 - their backtraces (instruction addresses);
291 - their current simcall numbers;
293 - some simcall arguments (eg. number of elements in a waitany);
295 - number of pending communications;
299 Some basic infrastructure for this is already in the code (see `mc_hash.cpp`)
300 but it is currently disabled.
302 @subsubsection contributing_todo_mc_separation Separate the model-checker code from libsimgrid
304 @subsubsection contributing_todo_mc_mced_interface Interface with the model-checked processes
306 The model-checker reads many informations about the model-checked process
307 by `process_vm_readv()`-ing brutally the data structure of the model-checked
308 process leading to some horrible code such as walking a swag from another
309 process. It prevents us as well from replacing some XBT data structures with
310 standard C++ ones. We need a sane way to expose the relevant informations to
313 @subsubsection contributing_todo_mc_generic_simcalls Generic simcalls
315 We have introduced some generic simcalls which can be used to execute a
316 callback in SimGrid Maestro context. It makes it a lot easier to interface
317 the simulated process with the maestro. However, the callbacks for the
318 model-checker which cannot decide how it should handle them. We would need a
319 solution for this if we want to be able to replace the simcalls the
320 model-checker cares about by generic simcalls.
322 @subsubsection contributing_todo_mc_api Definig an API for writing Model-Checking algorithms
324 Currently, writing a new model-checking algorithms in SimGridMC is quite
325 difficult: the logic of the model-checking algorithm is mixed with a lot of
326 low-level concerns about the way the model-checker is implemented. This makes it
327 difficult to write new algorithms and difficult to understand, debug and modify
328 the existing ones. We need a clean API to express the model-checking algorithms
329 in a form which is closer to the text-book/paper description. This API muste
330 be exposed in a a language which is more adequate to this task.
334 1. Design and implement a clean API for expression model-checking algorithms.
335 A `Session` class currently exists for this but is not feature complete
336 and should probably be rewritten. It should be easy to create bindings
337 for different languages on top of this API.
339 2. Create a binding to some better suited, dynamic, scripting language
342 3. Rewrite the existing model-checking algorithms in this language using the