doxygen/inside_release.doc \
doxygen/community.doc \
doxygen/community_contact.doc \
- doxygen/community_contributing.doc \
doxygen/community_extend.doc \
doxygen/community_giveback.doc \
doxygen/FAQ.doc \
doxygen/module-smpi.doc \
doxygen/module-trace.doc \
@CMAKE_HOME_DIRECTORY@/doc/doxygen/logcategories.doc \
- @CMAKE_HOME_DIRECTORY@/src/instr/ \
@CMAKE_HOME_DIRECTORY@/include/ \
@CMAKE_HOME_DIRECTORY@/include/xbt \
@CMAKE_HOME_DIRECTORY@/include/simgrid \
@CMAKE_HOME_DIRECTORY@/include/simgrid/s4u \
@CMAKE_HOME_DIRECTORY@/src/include/surf \
- @CMAKE_HOME_DIRECTORY@/src/xbt/ \
+ @CMAKE_HOME_DIRECTORY@/src/msg/ \
+ @CMAKE_HOME_DIRECTORY@/src/kernel/ \
+ @CMAKE_HOME_DIRECTORY@/src/kernel/activity/ \
+ @CMAKE_HOME_DIRECTORY@/src/kernel/context/ \
+ @CMAKE_HOME_DIRECTORY@/src/kernel/routing/ \
+ @CMAKE_HOME_DIRECTORY@/src/instr/ \
@CMAKE_HOME_DIRECTORY@/src/surf/ \
@CMAKE_HOME_DIRECTORY@/src/surf/plugins/ \
@CMAKE_HOME_DIRECTORY@/src/s4u/ \
- @CMAKE_HOME_DIRECTORY@/src/msg/ \
@CMAKE_HOME_DIRECTORY@/src/smpi/ \
@CMAKE_HOME_DIRECTORY@/src/simdag \
@CMAKE_HOME_DIRECTORY@/src/simix \
+ @CMAKE_HOME_DIRECTORY@/src/xbt/ \
@CMAKE_BINARY_DIR@/include \
@CMAKE_BINARY_DIR@/src \
- @CMAKE_HOME_DIRECTORY@/examples/msg/README.doc
+ @CMAKE_HOME_DIRECTORY@/examples/msg/README.doc \
+ @CMAKE_HOME_DIRECTORY@/examples/s4u/README.doc
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
# should be searched for input files as well. Possible values are YES and NO.
# If left blank NO is used.
-RECURSIVE = NO
+RECURSIVE = YES
# The EXCLUDE tag can be used to specify files and/or directories that should be
# excluded from the INPUT source files. This way you can easily exclude a
EXAMPLE_PATH = ./ \
@CMAKE_HOME_DIRECTORY@/src/surf/ \
+ @CMAKE_HOME_DIRECTORY@/src/surf/xml/ \
@CMAKE_HOME_DIRECTORY@/src/xbt/ \
@CMAKE_HOME_DIRECTORY@/examples \
@CMAKE_HOME_DIRECTORY@/doc/example_lists
<a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">"obsolete" slides</a>)
may give you some insights on what SimGrid can help you to do and what
are its limitations. Then you definitely should read the \ref
-MSG_examples.
+msg_examples.
If you are stuck at any point and if this FAQ cannot help you, please drop us a
mail to the user mailing list: <simgrid-user@lists.gforge.inria.fr>.
MSG_comm_test(), MSG_comm_wait(), MSG_comm_waitall() and MSG_comm_waitany();
MSG_comm_destroy().
-There is even a specific example section on \ref MSG_ex_asynchronous_communications.
+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
#### Examples ####
-Almost any @ref MSG_examples include a deployment file.
+Almost any @ref msg_examples include a deployment file.
### The argument tag ###
\tableofcontents
SimGrid comes with many examples provided in the examples/ directory.
-Those examples are described in section \ref MSG_examples. Those
+Those examples are described in section \ref msg_examples. Those
examples are commented and should be easy to understand. for a first
step into SimGrid we also provide some more detailed examples in the
sections below.
- \ref msg_VMs
- \ref msg_synchro
- \ref msg_trace_driven
- - \ref MSG_examples
+ - \ref msg_examples
*/
@ingroup MSG_API
@brief How to setup and control your simulation.
-The basic workflow is the following (check the \ref MSG_examples for
+The basic workflow is the following (check the \ref msg_examples for
details).
-# Initialize the library with #MSG_init
loopback_bw | no | int | Bandwidth for loopback (if any). See <b>link</b> section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref pf_sharing_policy_fatpipe "\b FATPIPE".
loopback_lat | no | int | Latency for loopback (if any). See <b>link</b> section for syntax/details. See loopback_bw for more info.
topology | no | FLAT\|TORUS\|FAT_TREE\|DRAGONFLY (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), <a href="http://en.wikipedia.org/wiki/Torus_interconnect">TORUS </a>, FAT_TREE, and DRAGONFLY attributes for this tag.
-topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref simgrid::surf::AsClusterFatTree "AsClusterFatTree documentation". For dragonfly, refer to \ref simgrid::surf::AsClusterDragonfly "AsClusterDragonfly documentation".
+topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref simgrid::kernel::routing::AsClusterFatTree "AsClusterFatTree documentation". For dragonfly, refer to \ref simgrid::kernel::routing::AsClusterDragonfly "AsClusterDragonfly documentation".
the router name is defined as the resulting String in the following
/*! @page uhood_switch Process Synchronizations and Context Switching
+@tableofcontents
+
@section uhood_switch_DES SimGrid as an Operating System
SimGrid is a discrete event simulator of distributed systems: it does
in order to <em>set the result</em> which will be made available to
the consumer by `future.get()`.
-### Which future do we need?
+@subsection uhood_switch_futures_needs Which future do we need?
The blocking API provided by the standard C++11 futures does not suit
our needs since the simulation kernel <em>cannot</em> block, and since
- Some features of the standard (such as shared futures) are not
needed in our context, and thus not considered here.
-### Implementing `Future` and `Promise`
+@subsection uhood_switch_futures_implem Implementing `Future` and `Promise`
The `simgrid::kernel::Future` and `simgrid::kernel::Promise` use a
shared state defined as follows:
}
@endcode
-## Generic simcalls
+@section uhood_switch_simcalls Implementing the simcalls
+
+So a simcall is a way for the actor to push a request to the
+simulation kernel and yield the control until the request is
+fulfilled. The performance requirements are very high because
+the actors usually do an inordinate amount of simcalls during the
+simulation.
+
+As for real syscalls, the basic idea is to write the wanted call and
+its arguments in a memory area that is specific to the actor, and
+yield the control to the simulation kernel. Once in kernel mode, the
+simcalls of each demanding actor are evaluated sequentially in a
+strictly reproducible order. This makes the whole simulation
+reproducible.
-### Motivation
-Simcalls are not so easy to understand and adding a new one is not so easy
-either. In order to add one simcall, one has to first
-add it to the [list of simcalls](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/simcalls.in)
-which looks like this:
+@subsection uhood_switch_simcalls_v2 The historical way
+
+In the very first implementation, everything was written by hand and
+highly optimized, making our software very hard to maintain and
+evolve. We decided to sacrifice some performance for
+maintainability. In a second try (that is still in use in SimGrid
+v3.13), we had a lot of boiler code generated from a python script,
+taking the [list of simcalls](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/simcalls.in)
+as input. It looks like this:
@code{cpp}
# This looks like C++ but it is a basic IDL-like language
};
@endcode
-Then one has to call (manually:cry:) a
-[Python script](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/simcalls.py)
-which generates a bunch of C++ files:
+When manually calling the relevant [Python
+script](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/simcalls.py),
+this generates a bunch of C++ files:
* an enum of all the [simcall numbers](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/popping_enum.h#L19);
Then one has to write the code of the kernel side handler for the simcall
and the code of the simcall itself (which calls the code-generated
-marshaling/unmarshaling stuff):sob:.
+marshaling/unmarshaling stuff).
In order to simplify this process, we added two generic simcalls which can be
used to execute a function in the simulation kernel:
}
@endcode
-### Blocking simcall
+### Blocking simcall {#uhood_switch_v2_blocking}
The second generic simcall (`simcall_run_blocking()`) executes a function in
the SimGrid simulation kernel immediately but does not wake up the calling actor
});
@endcode
-### Asynchronous operations
+### Asynchronous operations {#uhood_switch_v2_async}
We can write the related `kernelAsync()` which wakes up the actor immediately
and returns a future to the actor. As this future is used in the actor context,
it is a different future
-(`simgrid::simix::Future` instead of `simgrid::kernel::Furuere`)
+(`simgrid::simix::Future` instead of `simgrid::kernel::Future`)
which implements a C++11 `std::future` wait-based API:
@code{cpp}
instead of one to do the same job (one in `kernelAsync()` and one in
`.get()`).
-## Representing the simulated time
-
-SimGrid uses `double` for representing the simulated time:
-
-* durations are expressed in seconds;
-
-* timepoints are expressed as seconds from the beginning of the simulation.
-
-In contrast, all the C++ APIs use `std::chrono::duration` and
-`std::chrono::time_point`. They are used in:
-
-* `std::this_thread::wait_for()` and `std::this_thread::wait_until()`;
-
-* `future.wait_for()` and `future.wait_until()`;
-
-* `condvar.wait_for()` and `condvar.wait_until()`.
-
-We can define `future.wait_for(duration)` and `future.wait_until(timepoint)`
-for our futures but for better compatibility with standard C++ code, we might
-want to define versions expecting `std::chrono::duration` and
-`std::chrono::time_point`.
-
-For time points, we need to define a clock (which meets the
-[TrivialClock](http://en.cppreference.com/w/cpp/concept/TrivialClock)
-requirements, see
-[`[time.clock.req]`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf#page=642)
-working in the simulated time in the C++14 standard):
-
-@code{cpp}
-struct SimulationClock {
- using rep = double;
- using period = std::ratio<1>;
- using duration = std::chrono::duration<rep, period>;
- using time_point = std::chrono::time_point<SimulationClock, duration>;
- static constexpr bool is_steady = true;
- static time_point now()
- {
- return time_point(duration(SIMIX_get_clock()));
- }
-};
-@endcode
-
-A time point in the simulation is a time point using this clock:
-
-@code{cpp}
-template<class Duration>
-using SimulationTimePoint =
- std::chrono::time_point<SimulationClock, Duration>;
-@endcode
-
-This is used for example in `simgrid::s4u::this_actor::sleep_for()` and
-`simgrid::s4u::this_actor::sleep_until()`:
-
-@code{cpp}
-void sleep_for(double duration)
-{
- if (duration > 0)
- simcall_process_sleep(duration);
-}
-
-void sleep_until(double timeout)
-{
- double now = SIMIX_get_clock();
- if (timeout > now)
- simcall_process_sleep(timeout - now);
-}
-
-template<class Rep, class Period>
-void sleep_for(std::chrono::duration<Rep, Period> duration)
-{
- auto seconds =
- std::chrono::duration_cast<SimulationClockDuration>(duration);
- this_actor::sleep_for(seconds.count());
-}
-
-template<class Duration>
-void sleep_until(const SimulationTimePoint<Duration>& timeout_time)
-{
- auto timeout_native =
- std::chrono::time_point_cast<SimulationClockDuration>(timeout_time);
- this_actor::sleep_until(timeout_native.time_since_epoch().count());
-}
-@endcode
-
-Which means it is possible to use (since C++14):
-
-@code{cpp}
-using namespace std::chrono_literals;
-simgrid::s4u::actor::sleep_for(42s);
-@endcode
-
## Mutexes and condition variables
## Mutexes
documentation, but it should remain readable directly.
/**
- @defgroup MSG_examples MSG examples
+ @defgroup msg_examples MSG examples
@ingroup MSG_API
@brief Find the MSG example fitting your needs from the extensive set provided in the archive.
@ref examples/msg/app-masterworker/app-masterworker.c\n
Another good old example, where one Master process has a bunch of
task to dispatch to a set of several Worker processes. It is fully
- commented in @ref MSG_ex_master_worker.
+ commented in @ref msg_ex_master_worker.
@section msg_ex_async Asynchronous communications
In addition to the fully documented example of @ref
-MSG_ex_asynchronous_communications, there are several other examples
+msg_ex_asynchronous_communications, there are several other examples
shipped in the archive:
- <b>Basic asynchronous communications</b>.
--- /dev/null
+S4U (Simgrid for you) is the next interface of SimGrid, expected to be released with SimGrid 4.0.
+
+Even if it's in a very preliminary state so far, you are welcome to
+try it and report any interface glitches that you see. Be however
+warned that the interface will be modified until its final release.
+You will have to adapt your code on the way.
+
+This file follows the Doxygen syntax to be included in the
+documentation, but it should remain readable directly.
+
+/**
+ @defgroup s4u_examples S4U examples
+ @ingroup s4u_api
+ @brief Find the S4U example fitting your needs in the archive.
+
+ - @ref s4u_ex_basics
+
+@section s4u_ex_basics Basic examples and features
+
+@section s4u_ex_synchro Inter-Actor Synchronization
+
+ - <b>Mutex</b>.
+ @ref examples/s4u/mutex/s4u_mutex.cpp\n
+ Shows how to use simgrid::s4u::Mutex synchronization objects
+
+*/
+
+/**
+@example examples/s4u/mutex/s4u_mutex.cpp
+
+*/
\ No newline at end of file
return std::move(result);
}
-/** Producer side of a @simgrid::kernel::Future
+/** Producer side of a @ref simgrid::kernel::Future
*
* A @ref Promise is connected to some `Future` and can be used to
* set its result.
class ConditionVariable;
+/** @brief A classical mutex, but blocking in the simulation world
+ *
+ * It is strictly impossible to use a real mutex (such as
+ * [std::mutex](http://en.cppreference.com/w/cpp/thread/mutex)
+ * or [pthread_mutex_t](http://pubs.opengroup.org/onlinepubs/007908775/xsh/pthread_mutex_lock.html)),
+ * because it would block the whole simulation.
+ * Instead, you should use the present class, that is a drop-in replacement of
+ * [std::mutex](http://en.cppreference.com/w/cpp/thread/mutex).
+ *
+ */
XBT_PUBLIC_CLASS Mutex {
friend ConditionVariable;
private:
friend simgrid::simix::Mutex;
simgrid::simix::Mutex* mutex_;
Mutex(simgrid::simix::Mutex* mutex) : mutex_(mutex) {}
-public:
+ /* refcounting of the intrusive_ptr is delegated to the implementation object */
friend void intrusive_ptr_add_ref(Mutex* mutex)
{
xbt_assert(mutex);
xbt_assert(mutex);
SIMIX_mutex_unref(mutex->mutex_);
}
+public:
using Ptr = boost::intrusive_ptr<Mutex>;
// No copy:
+ /** You cannot create a new mutex by copying an existing one. Use MutexPtr instead */
Mutex(Mutex const&) = delete;
+ /** You cannot create a new mutex by value assignment either. Use MutexPtr instead */
Mutex& operator=(Mutex const&) = delete;
+ /** Constructs a new mutex */
static Ptr createMutex();
public:
*
* Used to simulate the time it takes to access to a file, but does not really store any information.
*
- * They are located on @link{simgrid::s4u::Storage}, that are accessed from a given @link{simgrid::s4u::Host} through mountpoints.
+ * They are located on @link{simgrid::s4u::Storage} that are accessed from a given @link{simgrid::s4u::Host} through mountpoints.
* For now, you cannot change the mountpoints programatically, and must declare them from your platform file.
*/
XBT_PUBLIC_CLASS File {
/** @ingroup s4u_api
*
- * @tableofcontents
+ * @tableofcontents
*
* An host represents some physical resource with computing and networking capabilities.
*
*
* auto args = std::make_tuple(1, false);
* int res = apply(foo, args);
- * @encode
+ * @endcode
**/
template <class F, class Tuple>
constexpr auto apply(F&& f, Tuple&& t)
-/* Copyright (c) 2008-2016. The SimGrid Team.
- * All rights reserved. */
+/* Copyright (c) 2008-2016. The SimGrid Team. All rights reserved. */
/* 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. */
-/** \file mc_compare.cpp Memory snapshooting and comparison */
+/** \file compare.cpp Memory snapshooting and comparison */
#include <cinttypes>
XBT_LOG_CONNECT(smpi_dvfs);
XBT_LOG_CONNECT(smpi_group);
XBT_LOG_CONNECT(smpi_kernel);
+ XBT_LOG_CONNECT(smpi_memory);
XBT_LOG_CONNECT(smpi_mpi);
XBT_LOG_CONNECT(smpi_mpi_dt);
XBT_LOG_CONNECT(smpi_pmpi);
XBT_LOG_CONNECT(xbt_lib);
XBT_LOG_CONNECT(xbt_mallocator);
XBT_LOG_CONNECT(xbt_matrix);
+ XBT_LOG_CONNECT(xbt_memory_map);
XBT_LOG_CONNECT(xbt_parmap);
XBT_LOG_CONNECT(xbt_sync);
XBT_LOG_CONNECT(xbt_sync_os);
XBT_LOG_CONNECT(mc_comm_pattern);
XBT_LOG_CONNECT(mc_process);
XBT_LOG_CONNECT(mc_protocol);
- XBT_LOG_CONNECT(mc_RegionSnaphot);
+ XBT_LOG_CONNECT(mc_Channel);
XBT_LOG_CONNECT(mc_ModelChecker);
+ XBT_LOG_CONNECT(mc_RegionSnaphot);
+ XBT_LOG_CONNECT(mc_Session);
XBT_LOG_CONNECT(mc_state);
#endif
XBT_LOG_CONNECT(mc_global);
XBT_LOG_CONNECT(msg_task);
XBT_LOG_CONNECT(msg_vm);
+ /* s4u */
+ XBT_LOG_CONNECT(s4u);
+ XBT_LOG_CONNECT(s4u_activity);
+ XBT_LOG_CONNECT(s4u_actor);
+ XBT_LOG_CONNECT(s4u_as);
+ XBT_LOG_CONNECT(s4u_channel);
+ XBT_LOG_CONNECT(s4u_comm);
+ XBT_LOG_CONNECT(s4u_file);
+
/* sg */
XBT_LOG_CONNECT(sg_host);
XBT_LOG_CONNECT(surf_vm);
XBT_LOG_CONNECT(surf_host);
+ /* routing */
+ XBT_LOG_CONNECT(AsImpl);
+
#endif /* simgrid_EXPORTS */
}
chomp $file;
parse_file($file);
}
+parse_file("../include/xbt/sysdep.h");
close FILES;
# Display the tree, looking for disconnected elems
