2 @page community The SimGrid Community
6 SimGrid is a free software, written by a community of people. It
7 started as a little software to help ourselves in our own research,
8 and as more people put their input into the pot, it turned into
9 something that we hope to be valuable to many people. So yes. We hope
10 that SimGrid is helping you doing what you want, and that you will
11 join our community of happy simgriders.
13 @section community_contact Contacting the community
15 There are several locations where you can connect and discuss about
16 SimGrid. If you have a question, please have a look at the
17 documentation and examples first, but if some remain don't hesitate to
18 ask the community for help. If you do not have a question, just come to us
19 and say hello! We love earing about how people use SimGrid.
21 - For questions or remarks, drop us an email on the
22 <a href="mailto:simgrid-user@lists.gforge.inria.fr">User Mailing list</a>
23 (to subscribe, visit the [web interface](http://lists.gforge.inria.fr/mailman/listinfo/simgrid-user));
24 you can also check out [our archives](http://lists.gforge.inria.fr/pipermail/simgrid-user/).
25 We prefer you to <b>not use private emails</b>. SimGrid is an open
26 framework, and you never know who have the time and knowledge to
27 answer your question, so please keep messages on the public mailing list.
28 - Join us on IRC and ask your question directly on the channel \#simgrid at
29 \b irc.debian.org (or use the ugly [web interface](https://webchat.oftc.net/?channels=%23simgrid)
30 if you don't have a [real client](https://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients)
32 Be warned that even if many people are connected to
33 the chanel, they may not be staring at their IRC windows.
34 So don't be surprised if you don't get an answer in the
35 second, and turn to the mailing lists if nobody seems to be there.
36 - Asking your question on [StackOverflow](http://stackoverflow.com/questions/tagged/simgrid) is also a good idea, as this
37 site is very well indexed. We answer questions there too (don't
38 forget to use the SimGrid tag in your question so that we can see
39 it), and they remain usable for the next users.
41 @section community_giveback Giving back to SimGrid
43 We are sometimes asked by users how to give back to the project. Here
44 are some ideas, but if you have new ones, feel free to share them with us.
46 @subsection contributing_spread Spread the word
48 There are many ways to help the SimGrid project. The first and most
49 natural one is to <b>use it for your research, and say so</b>. Cite
50 the SimGrid framework in your papers and discuss of its advantages with
51 your colleagues to spread the word. When we ask for new fundings to
52 sustain the project, the amount of publications enabled by SimGrid is
53 always the first question we get. The more you use the framework,
56 Make sure that your scientific publications using SimGrid actually
57 cite the [right paper](http://simgrid.gforge.inria.fr/Publications.html).
58 Also make sure that these citations are correctly listed on
59 <a href="http://simgrid.gforge.inria.fr/Usages.html">our list</a>.
61 You can also <b>help us constituting an active and welcoming user
62 community</b>. Subscribe to the mailing lists, and answer the
63 questions that newscomers have if you can. Point them (gently ;) to
64 the relevant part of the documentation on need, and help them becoming
65 part of our community too.
67 Another easy way to help the project is to add a link to the <a
68 href="http://simgrid.gforge.inria.fr">SimGrid homepage</a> on your
69 site to <b>improve SimGrid's ranking in search engines</b>.
71 Finally, if you organize a scientific event where you expect many
72 potential users, <b>you can invite us to give a tutorial on SimGrid</b>. We
73 found that 45 minutes to one hour is very sharp, but doable. It
74 allows us to explain the main motivations and outcomes of the project in
75 order to motivate the attendees get more information on SimGrid, and
76 eventually improve their scientific habits by using a sound simulation
78 <a href="http://people.irisa.fr/Martin.Quinson/blog/2012/1120/Simgrid_at_Louvain/">Here</a>
79 is an example of such a presentation.
81 @subsection contributing_bugs Reporting (and fixing) any issue you find
83 Because of its size and complexity, SimGrid is not perfect and
84 contains a large amount of glitches and issues. When you find one,
85 don't assume that it's here because we don't care. It survived only
86 because nobody told us. We unfortunately cannot endlessly review our
87 large code and documentation base. So please, <b>report any issue you
88 find</b>, be it a typo in the documentation, a paragraph that needs to
89 be reworded, a bug in the code, or any other problem. The best way to
90 do so is to open an issue on our GitHub's
91 <a href="https://github.com/simgrid/simgrid/issues">Bug Tracker</a> so
92 that we don't forget about it (if you want to put some attachment, you
94 [this other bugtracker](https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse)
97 The worst way to report such issues is to go through private emails.
98 These are unreliable, and we are trying to develop SimGrid openly, so
99 private discussions are to be avoided if possible.
101 If you can provide a patch fixing the issue you report, that's even
102 better. If you cannot, then you need to give us a minimal working
103 example (MWE), that is a ready to use solution that reproduces the
104 problem you face. Your bug will take much more time
105 for us to reproduce and fix if you don't give us the MWE, so you want
106 to help us helping you to get things efficient.
108 Of course, a very good way to give back to the SimGrid community is to
109 <b>triage and fix the bugs in the Bug Tracking Systems</b>. If you
110 can come up with a patch fixing them, we will be more than happy to
111 apply your changes so that the whole community enjoys them.
113 @section community_extend Extending SimGrid and its Ecosystem
115 @subsection contributing_contrib Contributing features and associated tools
117 If you deeply miss a feature in the framework, you should consider
118 implementing it yourself. SimGrid is free software, meaning that you are
119 free to help yourself. Of course, we'll do our best to assist you in
120 this task, so don't hesitate to contact us with your idea.
122 You could write a new plugin extending SimGrid in some way, or a
123 routing model for another kind of network. But even if you write your own
124 platform file, this is probably interesting to other users too, and
125 could be included to SimGrid. Modeling accurately a given platform is
126 a difficult work, which outcome is very precious to us.
128 Or maybe you developed an independent tool on top of SimGrid. We'd
129 love helping you gaining visibility by listing it in our
130 <a href="http://simgrid.gforge.inria.fr/contrib.html">Contrib
133 @subsection contributing_todo Possible Enhancements
135 If you want to start working on the SimGrid codebase, here are a few
136 ideas of things that could be done to improve the current code (not all of them
137 are difficult, do trust yourself ;)
139 @subsubsection contributing_todo_cxxification Migration to C++
141 The code is being migrated to C++ but a large part is still C (or C++ with
142 C idioms). It would be valuable to replace C idioms with C++ ones:
144 - replace XBT structures and C dynamic arrays with C++ containers;
146 - replace `char*` strings with `std::string`;
148 - use exception-safe RAII (`std::unique_ptr`, etc.) instead of explicit
149 `malloc/free` or `new/delete`;
151 - use `std::function` (or template functionoid arguments) instead of function
156 SimGrid used to implement exceptions in C. This has been replaced with C++
157 exceptions but some bits of the C exceptions are still remaining:
159 - `xbt_ex` was the type of C exceptions. It is now a standard C++ exception.
160 We might want to remove this exception and use a more idiomatic C++
161 solution with dedicated exception classes for different errors.
162 `std::system_error` might be used as well by replacing some `xbt_errcat_t`
163 with custom subclasses of `std::error_category`.
165 - The C API currently throws exceptions. Throwing exceptions out of a C API is
166 not very friendly. C code does not expect them, cannot catch them and cannot
167 handle resource management properly in face of exceptions. We should clearly
168 separate the C++ API and the C API and catch all exceptions before they get
171 #### Time and duration
173 Some support for C++11-style time/duration is implemented (see `chrono.hpp`)
174 but only available in some (S4U) APIs. It would be nice to add support for
175 them in the rest of the C++ code.
177 A related change would be to avoid using "-1" to mean "forever" at least in S4U
178 and in the internal code. For compatibility, MSG should probably keep this
179 semantic. We should probably always use separate functions
180 (`wait` vs `wait_for`).
182 #### Futures and Promises
184 - Some features are missing in the Maestro future implementation
185 (`simgrid::kernel::Future`, `simgrid::kernel::Promise`)
186 could be extended to support additional features:
187 `when_any`, `shared_future`, etc.
189 - The corresponding feature might then be implemented in the user process
190 futures (`simgrid::simix::Future`).
192 - Currently `.then()` is not available for user futures. We would need to add
193 a basic user event loop in order to queue the pending continuations.
195 - We might need to provide an option to cancel a pending operation. This
196 might be achieved by defining some `Action` or `Operation` class with an
197 API compatible with `Future` (and convertible to it) but with an
198 additional `.cancel()` method.
200 @subsubsection contributing_todo_smpi SMPI
202 #### Process-based privatization
204 Currently, all the simulated processes live in the same process as the SimGrid
205 simulator. The benefit is that we don't have to do context switches and IPC
206 between the simulator and the processes.
208 The fact that they share the same address space means that one memory corruption
209 in one simulated process can propagate to the other ones and to the SimGrid
212 Moreover, the current design for SMPI applications is to compile the MPI code
213 normally and execute it once per simulated process in the same system process:
214 This means that all the existing simulated MPI processes share the same virtual
215 address space and share by default the same global variables. This is not
216 correct as each MPI process is expected to use its own address space and have
217 its own global variables. In order to fix, this problem we have an optional
218 SMPI privatization feature which creates an instanciation of the executable
219 data segment per MPI process and map the correct one (using `mmap`) at each
222 This approach has many problems:
224 1. It is not completely safe. We only handle SMPI privatization for the global
225 variables in the execute data segment. Shared objects are ignored but some
226 may contain global variables which may need to be privatized:
228 - libsimgrid for example must not be privatized because it contains
229 shared state for the simulator;
231 - libc must not be privatized for the same reason (but some global variables
232 in the libc may not be privatized);
234 - if we use global variables of some shared object in the executable, this
235 global variable will be instanciated in the executable (because of copy
236 relocation) and will be privatized even if it shoud not.
238 2. We cannot execute the MPI processes in parallel. Only one can execute at
239 the same time because only one privatization segment can be mapped at a
242 In order to fix this, the standard solution is to move each MPI process in its
243 own system process and use IPC to communicate with the simulator. One concern would
244 be the impact on performance and memory consumption:
246 - It would introduce a lot of context switches and IPC communications between
247 the MPI processes and the SimGrid simulator. However, currently every context
248 switch needs a `mmap` for SMPI privatization which is costly as well
251 - Instanciating a lot of processes might consume more memory which might be a
252 problem if we want to simulate a lot of MPI processes. Compiling MPI programs
253 as static executables with a lightweight libc might help and we might want to
254 support that. The SMPI processes should probably not embed all the SimGrid
255 simulator and its dependencies, the C++ runtime, etc.
257 We would need to modify the model-checker as well which currently can only
258 manage on model-checked process. For the model-checker we can expect some
259 benefits from this approach: if a process did not execute, we know its state
260 did not change and we don't need to take its snapshot and compare its state.
262 Other solutions for this might include:
264 - Mapping each MPI process in the process of the simulator but in a different
265 symbol namespace (see `dlmopen`). Each process would have its own separate
266 instanciation and would not share libraries.
268 - Instanciate each MPI process in a separate lightweight VM (for example based
269 on WebAssembly) in the simualtor process.
271 @subsubsection contributing_todo_mc Model-checker
273 #### Overhaul the state comparison code
275 The state comparison code is quite complicated. It has very long functions and
276 is programmed mostly using C idioms and is difficult to understand and debug.
277 It is in need of an overhaul:
279 - cleanup, refactoring, usage of C++ features.
281 - The state comparison code works by infering types of blocks allocated on the
282 heap by following pointers from known roots (global variables, local
283 variables). Usually the first type found for a given block is used even if
284 a better one could be found later. By using a first pass of type inference,
285 on each snapshot before comparing the states, we might use a better type
286 information on the different blocks.
288 - We might benefit from adding logic for handling some known types. For
289 example, both `std::string` and `std::vector` have a capacity which might
290 be larger than the current size of the container. We should ignore
291 the corresponding elements when comparing the states and infering the types.
293 - Another difficulty in the state comparison code is the detection of
294 dangling pointers. We cannot easily know if a pointer is dangling and
295 dangling pointers might lead us to choose the wrong type when infering
296 heap blocks. We might mitigate this problem by delaying the reallocation of
297 a freed block until there is no blocks pointing to it anymore using some
298 sort of basic garbage-collector.
300 #### Hashing the states
302 In order to speed up the state comparison an idea was to create a hash of the
303 state. Only states with the same hash would need to be compared using the
304 state comparison algorithm. Some information should not be inclueded in the
305 hash in order to avoid considering different states which would otherwise
306 would have been considered equal.
308 The states could be indexed by their hash. Currently they are indexed
309 by the number of processes and the amount of heap currently allocated
310 (see `DerefAndCompareByNbProcessesAndUsedHeap`).
312 Good candidate informations for the state hashing:
314 - number of processes;
316 - their backtraces (instruction addresses);
318 - their current simcall numbers;
320 - some simcall arguments (eg. number of elements in a waitany);
322 - number of pending communications;
326 Some basic infrastructure for this is already in the code (see `mc_hash.cpp`)
327 but it is currently disabled.
329 #### Separate the model-checker code from libsimgrid
331 #### Interface with the model-checked processes
333 The model-checker reads many information about the model-checked process
334 by `process_vm_readv()`-ing brutally the data structure of the model-checked
335 process leading to some horrible code such as walking a swag from another
336 process. It prevents us as well from replacing some XBT data structures with
337 standard C++ ones. We need a sane way to expose the relevant information to
340 #### Generic simcalls
342 We have introduced some generic simcalls which can be used to execute a
343 callback in SimGrid Maestro context. It makes it a lot easier to interface
344 the simulated process with the maestro. However, the callbacks for the
345 model-checker which cannot decide how it should handle them. We would need a
346 solution for this if we want to be able to replace the simcalls the
347 model-checker cares about by generic simcalls.
349 #### Defining an API for writing Model-Checking algorithms
351 Currently, writing a new model-checking algorithms in SimGridMC is quite
352 difficult: the logic of the model-checking algorithm is mixed with a lot of
353 low-level concerns about the way the model-checker is implemented. This makes it
354 difficult to write new algorithms and difficult to understand, debug, and modify
355 the existing ones. We need a clean API to express the model-checking algorithms
356 in a form which is closer to the text-book/paper description. This API must
357 be exposed in a a language which is more adequate to this task.
361 1. Design and implement a clean API to express model-checking algorithms.
362 A `Session` class currently exists for this but is not feature complete
363 and should probably be rewritten. It should be easy to create bindings
364 for different languages on top of this API.
366 2. Create a binding to some better suited, dynamic, scripting language
369 3. Rewrite the existing model-checking algorithms in this language using the