-\subsection faq_MIA_MSG MSG features
-
-\subsubsection faq_MIA_examples I want some more complex MSG examples!
-
-Many people have come to ask me a more complex example and each time,
-they have realized afterward that the basics were in the previous three
-examples.
-
-Of course they have often been needing more complex functions like
-MSG_process_suspend(), MSG_process_resume() and
-MSG_process_isSuspended() (to perform synchronization), or
-MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
-receptions), or even MSG_process_create() (to design asynchronous
-communications or computations). But the examples are sufficient to
-start.
-
-We know. We should add some more examples, but not really some more
-complex ones... We should add some examples that illustrate some other
-functionalists (like how to simply encode asynchronous
-communications, RPC, process migrations, thread synchronization, ...)
-and we will do it when we will have a little bit more time. We have
-tried to document the examples so that they are understandable. Tell
-us if something is not clear and once again feel free to participate!
-:)
-
-\subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication
-
-There is no task duplication in MSG. When you create a task, you can
-process it or send it somewhere else. As soon as a process has sent
-this task, he doesn't have this task anymore. It's gone. The receiver
-process has got the task. However, you could decide upon receiving to
-create a "copy" of a task but you have to handle by yourself the
-semantic associated to this "duplication".
-
-As we already told, we prefer keeping the API as simple as
-possible. This kind of feature is rather easy to implement by users
-and the semantic you associate really depends on people. Having a
-*generic* task duplication mechanism is not that trivial (in
-particular because of the data field). That is why I would recommend
-that you write it by yourself even if I can give you advice on how to
-do it.
-
-You have the following functions to get information about a task:
-MSG_task_get_name(), MSG_task_get_compute_duration(),
-MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
-and MSG_task_get_data().
-
-You could use a dictionary (#xbt_dict_t) of dynars (#xbt_dynar_t). If
-you still don't see how to do it, please come back to us...
-
-\subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
-
-In the past (version <= 3.4), there was no function to perform asynchronous communications.
-It could easily be implemented by creating new process when needed though. Since version 3.5,
-we have introduced the following functions:
- - MSG_task_isend()
- - MSG_task_irecv()
- - MSG_comm_test()
- - MSG_comm_wait()
- - MSG_comm_waitall()
- - MSG_comm_waitany()
- - MSG_comm_destroy()
-
-We refer you to the description of these functions for more details on their usage as well
-as to the example section on \ref MSG_ex_asynchronous_communications.
-
-\subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
-
-You obviously cannot use pthread_mutexes of pthread_conds since we handle every
-scheduling related decision within SimGrid.
-
-In the past (version <=3.3.4) you could do it by playing with
-MSG_process_suspend() and MSG_process_resume() or with fake communications (using MSG_task_get(),
-MSG_task_put() and MSG_task_Iprobe()).
-
-Since version 3.4, you can use classical synchronization structures. See page \ref XBT_synchro or simply check in
-include/xbt/synchro_core.h.
-
-\subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
-
-There is no such thing because its semantic wouldn't be really
-clear. Of course, it is something about the amount of host throughput,
-but there is as many definition of "host load" as people asking for
-this function. First, you have to remember that resource availability
-may vary over time, which make any load notion harder to define.
-
-It may be instantaneous value or an average one. Moreover it may be only the
-power of the computer, or may take the background load into account, or may
-even take the currently running tasks into account. In some SURF models,
-communications have an influence on computational power. Should it be taken
-into account too?
-
-First of all, it's near to impossible to predict the load beforehand in the
-simulator since it depends on too much parameters (background load
-variation, bandwidth sharing algorithmic complexity) some of them even being
-not known beforehand (other task starting at the same time). So, getting
-this information is really hard (just like in real life). It's not just that
-we want MSG to be as painful as real life. But as it is in some way
-realistic, we face some of the same problems as we would face in real life.
-
-How would you do it for real? The most common option is to use something
-like NWS that performs active probes. The best solution is probably to do
-the same within MSG, as in next code snippet. It is very close from what you
-would have to do out of the simulator, and thus gives you information that
-you could also get in real settings to not hinder the realism of your
-simulation.
-
-\code
-double get_host_load() {
- m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
- double date = MSG_get_clock();
-
- MSG_task_execute(task);
- date = MSG_get_clock() - date;
- MSG_task_destroy(task);
- return (0.001/date);
-}
-\endcode
-
-Of course, it may not match your personal definition of "host load". In this
-case, please detail what you mean on the mailing list, and we will extend
-this FAQ section to fit your taste if possible.
-
-\subsubsection faq_MIA_communication_time How can I get the *real* communication time?
+@subsection faq_MIA_MSG MSG features
+
+@subsubsection faq_MIA_thread_synchronization How to synchronize my user processes?
+
+It depends on why you want to synchronize them. If you just want to
+have a shared state between your processes, then you probably don't
+need to do anything. User processes never get forcefully interrupted
+in SimGrid (unless you explicitly request the parallel execution of
+user processes -- see @ref options_virt_parallel).
+
+Even if several processes are executed at the exact same time within
+the simulation, they are linearized in reality by default: one process
+always run in an exclusive manner, atomic, uninterrupted until it does
+a simcall (until it ask a service from the simulation kernel). This is
+surprising at first, but things are much easier this way, both for the
+user (who don't have to protect her shared data) and for the kernel
+(that avoid many synchronization issues too). Processes are executed
+concurrently in the simulated realm, but you don't need to bother with
+this in the real realm.
+
+If you really need to synchronize your processes (because it's what
+you are studying or to create an atomic section that spans over
+several simcalls), you obviously cannot use regular synchronization
+mechanisms (pthread_mutexes in C or the synchronized keyword in Java).
+This is because the SimGrid kernel locks all processes and unlock them
+one after the other when they are supposed to run, until they give the
+control back in their simcall. If one of them gets locked by the OS
+before returning the control to the kernel, that's definitively a
+deadlock.
+
+Instead, you should use the synchronization mechanism provided by the
+simulation kernel. This could with a SimGrid mutex, a SimGrid
+condition variables or a SimGrid semaphore, as described in @ref
+msg_synchro (in Java, only semaphores are available). But actually,
+many synchronization patterns can be encoded with communication on
+mailboxes. Typically, if you need one process to notify another one,
+you could use a condition variable or a semphore, but sending a
+message to a specific mailbox does the trick in most cases.
+
+@subsubsection faq_MIA_communication_time How can I get the *real* communication time?