Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
fix some errors and warnings in the doc generation
[simgrid.git] / docs / source / community.rst
1 .. _community:
2
3 The SimGrid Community
4 =====================
5
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.
12
13 Contacting the community
14 ------------------------
15
16 There are several locations where you can connect and discuss about
17 SimGrid. If you have a question, please have a look at the
18 documentation and examples first, but if some remain don't hesitate to
19 ask the community for help. If you do not have a question, just come
20 to us and say hello! We love earing about how people use SimGrid.
21
22  - For questions or remarks, drop us an email on the `user mailing
23    list <mailto:simgrid-user@lists.gforge.inria.fr>`_ (to subscribe,
24    visit the `web interface
25    <http://lists.gforge.inria.fr/mailman/listinfo/simgrid-user>`_);
26    you can also check out `our archives
27    <http://lists.gforge.inria.fr/pipermail/simgrid-user/>`_.  We
28    prefer you to **not use private emails**. SimGrid is an open
29    framework, and you never know who have the time and knowledge to
30    answer your question, so please keep messages on the public mailing
31    list.
32  - Join us on IRC and ask your question directly on the channel \#simgrid at
33    ``irc.debian.org``
34    (or use the ugly `web interface <https://webchat.oftc.net/?channels=%23simgrid>`_
35    if you don't have a
36    `real client <https://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients>`_
37    installed). When no non-french speaker are connected, we usually
38    chat in french on this channel, but we do switch back to english
39    when we have a guest.
40    
41    Be warned that even if many people are connected to
42    the chanel, they may not be staring at their IRC windows.
43    So don't be surprised if you don't get an answer in the 
44    second, and turn to the mailing lists if nobody seems to be there.
45    The logs of this channel are publicly
46    `available online <http://colabti.org/irclogger/irclogger_logs/simgrid>`_,
47    so may also want to check in a few hours if someone answered after
48    you left. 
49    
50  - Asking your question on
51    `StackOverflow <http://stackoverflow.com/questions/tagged/simgrid>`_
52    is also a good idea, as this
53    site is very well indexed. We answer questions there too (don't
54    forget to use the SimGrid tag in your question so that we can see
55    it), and they remain usable for the next users. 
56
57 Giving back to SimGrid
58 ----------------------
59
60 We are sometimes asked by users how to give back to the project. Here
61 are some ideas, but if you have new ones, feel free to share them with us.
62
63 Spread the word
64 ^^^^^^^^^^^^^^^
65
66 There are many ways to help the SimGrid project. The first and most
67 natural one is to **use SimGrid for your research, and say so**. Cite
68 the SimGrid framework in your papers and discuss of its advantages with
69 your colleagues to spread the word. When we ask for new fundings to
70 sustain the project, the amount of publications enabled by SimGrid is
71 always the first question we get. The more you use the framework,
72 the better for us. 
73
74 Make sure that your scientific publications using SimGrid actually
75 cite the `right paper <https://simgrid.org/Publications.html>`_.
76 Also make sure that these citations are correctly listed on 
77 `our list <https://simgrid.org/Usages.html>`_.
78
79 You can also **help us constituting an active and welcoming user
80 community**. Subscribe to the mailing lists, and answer the
81 questions that newscomers have if you can. Point them (gently ;) to
82 the relevant part of the documentation on need, and help them becoming
83 part of our community too. 
84
85 Another easy way to help the project is to add a link to the `SimGrid
86 homepage <simgrid.org>`_ on your site to improve SimGrid's ranking in
87 search engines.
88
89 Finally, if you organize a scientific event where you expect many
90 potential users, you can invite us to give a tutorial on SimGrid. We
91 found that 45 minutes to one hour is very sharp, but
92 `doable <http://people.irisa.fr/Martin.Quinson/blog/2012/1120/Simgrid_at_Louvain/>`_.
93 It is enough to explain the main motivations and outcomes of the
94 project in order to motivate the attendees get more information on
95 SimGrid, and eventually improve their scientific habits by using a
96 sound simulation framework. 
97
98 Report (and fix) issues
99 ^^^^^^^^^^^^^^^^^^^^^^^
100
101 Because of its size and complexity, SimGrid far from perfect and
102 contains a large amount of glitches and issues. When you find one,
103 don't assume that it's here because we don't care. It survived only
104 because nobody told us. We unfortunately cannot endlessly review our
105 large code and documentation base. So please, **report any issue you
106 find**, be it a typo in the documentation, a paragraph that needs to
107 be reworded, a bug in the code, or any other problem. The best way to
108 do so is to open an issue on our
109 `Bug Tracker <https://github.com/simgrid/simgrid/issues>`_ so
110 that we don't forget about it. 
111
112 The worst way to report such issues is to go through private emails.
113 These are unreliable, and we are trying to develop SimGrid openly, so
114 private discussions are to be avoided if possible. 
115
116 If you can provide a patch fixing the issue you report, that's even
117 better. If you cannot, then you need to give us a minimal working
118 example (MWE), that is a ready to use solution that reproduces the
119 problem you face. Your bug will take much more time
120 for us to reproduce and fix if you don't give us the MWE, so you want
121 to help us helping you to get things efficient.
122
123 Of course, a very good way to give back to the SimGrid community is to
124 triage and fix the bugs in the Bug Tracking Systems. If the bug report
125 has no MWE, we'd love you to contribute one. If you can come up with a
126 patch, we will be more than happy to apply your changes so that the
127 whole community enjoys them.
128
129 Extending SimGrid and its Ecosystem
130 -----------------------------------
131
132 Contributing Code
133 ^^^^^^^^^^^^^^^^^
134
135 If you deeply miss a feature in the framework, you should consider
136 implementing it yourself. SimGrid is free software, meaning that you are
137 free to help yourself. Of course, we'll do our best to assist you in
138 this task, so don't hesitate to contact us with your idea.
139
140 You could write a new plugin extending SimGrid in some way, or a
141 routing model for another kind of network. But even if you write your own
142 platform file, this is probably interesting to other users too, and
143 could be included to SimGrid. Modeling accurately a given platform is
144 a difficult work, which outcome is very precious to us.
145
146 Or maybe you developed an independent tool on top of SimGrid. We'd
147 love helping you gaining visibility by listing it in our 
148 `Contrib <https://simgrid.org/contrib.html>`_. 
149
150 Possible Enhancements
151 ^^^^^^^^^^^^^^^^^^^^^
152
153 If you want to start working on the SimGrid codebase, here are a few
154 ideas of things that could be done to improve the current code (not all of them
155 are difficult, do trust yourself ;)
156
157 Time and duration
158 """""""""""""""""
159
160 We should avoir using "-1" to mean "forever" at least in S4U and in
161 the internal code.  We should probably always use separate functions
162 (`wait` vs `wait_for`).
163
164 Futures and Promises
165 """"""""""""""""""""
166
167  - Some features are missing in the Maestro future implementation
168    (`simgrid::kernel::Future`, `simgrid::kernel::Promise`)
169    could be extended to support additional features:
170    `when_any`, `shared_future`, etc.
171
172  - The corresponding feature might then be implemented in the user process
173    futures (`simgrid::simix::Future`).
174
175  - Currently `.then()` is not available for user futures. We would need to add
176    a basic user event loop in order to queue the pending continuations.
177
178  - We might need to provide an option to cancel a pending operation. This
179    might be achieved by defining some `Action` or `Operation` class with an
180    API compatible with `Future` (and convertible to it) but with an
181    additional `.cancel()` method.
182
183 MC: Overhaul the state comparison code
184 """"""""""""""""""""""""""""""""""""""
185
186 The state comparison code is quite complicated. It has very long functions and
187 is programmed mostly using C idioms and is difficult to understand and debug.
188 It is in need of an overhaul:
189
190   - cleanup, refactoring, usage of C++ features.
191
192   - The state comparison code works by infering types of blocks allocated on the
193     heap by following pointers from known roots (global variables, local
194     variables). Usually the first type found for a given block is used even if
195     a better one could be found later. By using a first pass of type inference,
196     on each snapshot before comparing the states, we might use a better type
197     information on the different blocks.
198
199   - We might benefit from adding logic for handling some known types. For
200     example, both `std::string` and `std::vector` have a capacity which might
201     be larger than the current size of the container. We should ignore
202     the corresponding elements when comparing the states and infering the types.
203
204   - Another difficulty in the state comparison code is the detection of
205     dangling pointers. We cannot easily know if a pointer is dangling and
206     dangling pointers might lead us to choose the wrong type when infering
207     heap blocks. We might mitigate this problem by delaying the reallocation of
208     a freed block until there is no blocks pointing to it anymore using some
209     sort of basic garbage-collector.
210
211 MC: Hashing the states
212 """"""""""""""""""""""
213
214 In order to speed up the state comparison an idea was to create a hash of the
215 state. Only states with the same hash would need to be compared using the
216 state comparison algorithm. Some information should not be inclueded in the
217 hash in order to avoid considering different states which would otherwise
218 would have been considered equal.
219
220 The states could be indexed by their hash. Currently they are indexed
221 by the number of processes and the amount of heap currently allocated
222 (see `DerefAndCompareByNbProcessesAndUsedHeap`).
223
224 Good candidate informations for the state hashing:
225
226  - number of processes;
227
228  - their backtraces (instruction addresses);
229
230  - their current simcall numbers;
231
232  - some simcall arguments (eg. number of elements in a waitany);
233
234  - number of pending communications;
235
236  - etc.
237
238 Some basic infrastructure for this is already in the code (see `mc_hash.cpp`)
239 but it is currently disabled.
240
241 Interface with the model-checked processes
242 """"""""""""""""""""""""""""""""""""""""""
243
244 The model-checker reads many information about the model-checked process by
245 `process_vm_readv()`-ing brutally the data structure of the model-checked
246 process leading to some inefficient code such as maintaining copies of complex
247 C++ structures in XBT dynars. We need a sane way to expose the relevant
248 information to the model-checker.
249
250 Generic simcalls
251 """"""""""""""""
252
253 We have introduced some generic simcalls which can be used to execute a
254 callback in SimGrid Maestro context. It makes it a lot easier to interface
255 the simulated process with the maestro. However, the callbacks for the
256 model-checker which cannot decide how it should handle them. We would need a
257 solution for this if we want to be able to replace the simcalls the
258 model-checker cares about by generic simcalls.
259
260 Defining an API for writing Model-Checking algorithms
261 """""""""""""""""""""""""""""""""""""""""""""""""""""
262
263 Currently, writing a new model-checking algorithms in SimGridMC is quite
264 difficult: the logic of the model-checking algorithm is mixed with a lot of
265 low-level concerns about the way the model-checker is implemented. This makes it
266 difficult to write new algorithms and difficult to understand, debug, and modify
267 the existing ones. We need a clean API to express the model-checking algorithms
268 in a form which is closer to the text-book/paper description. This API must
269 be exposed in a a language which is more adequate to this task.
270
271 Tasks:
272
273   1. Design and implement a clean API to express model-checking algorithms.
274      A `Session` class currently exists for this but is not feature complete
275      and should probably be rewritten. It should be easy to create bindings
276      for different languages on top of this API.
277
278   2. Create a binding to some better suited, dynamic, scripting language
279      (e.g., Lua).
280
281   3. Rewrite the existing model-checking algorithms in this language using the
282      new API.