There is even a specific 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_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
+XBT_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_host_load Where is the get_host_load function hidden in MSG?
-/* xbt/synchro_core.h -- Synchronization tools */
-/* Usable in simulator, (or in real life when mixing with GRAS) */
+/* xbt/synchro_core.h -- Simulated synchronization */
-/* Copyright (c) 2009-2014. The SimGrid Team.
- * All rights reserved. */
+/* Copyright (c) 2009-2016. The SimGrid Team. */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
/** @addtogroup XBT_synchro
* @brief XBT synchronization tools
- *
- * This section describes the XBT synchronization tools.
- * This is a portability layer (for windows and UNIX) of a pthread-like API. Nice, isn't it?
- *
+ *
+ * This section describes the simulated synchronization mechanisms,
+ * that you can use in your simulation without deadlocks. See @ref
+ * faq_MIA_thread_synchronization for details.
+ *
* @{
*/
