/*! @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
mandatory to the model-checker. The simcalls, representing actors'
actions, are the transitions of the formal system. Verifying the
system requires to manipulate these transitions explicitly. This also
-allows to run safely the actors in parallel, even if this is less
+allows one to run the actors safely in parallel, even if this is less
commonly used by our users.
So, the key ideas here are:
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:
@code{cpp}
template<class T>
template<class F>
-auto simgrid::kernel::Future<T>::thenNoUnwrap(F continuation)
+auto simgrid::kernel::Future<T>::then_no_unwrap(F continuation)
-> Future<decltype(continuation(std::move(*this)))>
{
typedef decltype(continuation(std::move(*this))) R;
}
@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
# (one definition per line) parsed by a python script:
-void process_kill(smx_process_t process);
+void process_kill(smx_actor_t process);
void process_killall(int reset_pid);
-void process_cleanup(smx_process_t process) [[nohandler]];
-void process_suspend(smx_process_t process) [[block]];
-void process_resume(smx_process_t process);
-void process_set_host(smx_process_t process, sg_host_t dest);
-int process_is_suspended(smx_process_t process) [[nohandler]];
-int process_join(smx_process_t process, double timeout) [[block]];
+void process_cleanup(smx_actor_t process) [[nohandler]];
+void process_suspend(smx_actor_t process) [[block]];
+void process_resume(smx_actor_t process);
+void process_set_host(smx_actor_t process, sg_host_t dest);
+int process_is_suspended(smx_actor_t process) [[nohandler]];
+int process_join(smx_actor_t process, double timeout) [[block]];
int process_sleep(double duration) [[block]];
smx_mutex_t mutex_init();
// Simcall number:
e_smx_simcall_t call;
// Issuing actor:
- smx_process_t issuer;
+ smx_actor_t issuer;
// Arguments of the simcall:
union u_smx_scalar args[11];
// Result of the simcall:
};
@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);
responsible for wrapping the parameters in the `struct s_smx_simcall`;
and wrapping out the result;
-* [accessors](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/popping_accessors.h)
+* [accessors](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/popping_accessors.hpp)
to get/set values of of `struct s_smx_simcall`;
* a simulation-kernel-side [big switch](https://github.com/simgrid/simgrid/blob/4ae2fd01d8cc55bf83654e29f294335e3cb1f022/src/simix/popping_generated.cpp#L106)
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
`simgrid::simix::unblock(actor)`) when the operation is completed.
This is wrapped in a higher-level primitive as well. The
-`kernelSync()` function expects a function-object which is executed
+`kernel_sync()` function expects a function-object which is executed
immediately in the simulation kernel and returns a `Future<T>`. The
simulator blocks the actor and resumes it when the `Future<T>` becomes
ready with its result:
@code{cpp}
template<class F>
-auto kernelSync(F code) -> decltype(code().get())
+auto kernel_sync(F code) -> decltype(code().get())
{
typedef decltype(code().get()) T;
if (SIMIX_is_maestro())
xbt_die("Can't execute blocking call in kernel mode");
- smx_process_t self = SIMIX_process_self();
+ smx_actor_t self = SIMIX_process_self();
simgrid::xbt::Result<T> result;
simcall_run_blocking([&result, self, &code]{
A contrived example of this would be:
@code{cpp}
-int res = simgrid::simix::kernelSync([&] {
+int res = simgrid::simix::kernel_sync([&] {
return kernel_wait_until(30).then(
[](simgrid::kernel::Future<void> future) {
return 42;
});
@endcode
-### Asynchronous operations
+### Asynchronous operations {#uhood_switch_v2_async}
-We can write the related `kernelAsync()` which wakes up the actor immediately
+We can write the related `kernel_async()` 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}
{
if (!valid())
throw std::future_error(std::future_errc::no_state);
- smx_process_t self = SIMIX_process_self();
+ smx_actor_t self = SIMIX_process_self();
simgrid::xbt::Result<T> result;
simcall_run_blocking([this, &result, self]{
try {
}
@endcode
-`kernelAsync()` simply :wink: calls `kernelImmediate()` and wraps the
+`kernel_async()` simply :wink: calls `kernelImmediate()` and wraps the
`simgrid::kernel::Future` into a `simgrid::simix::Future`:
@code{cpp}
template<class F>
-auto kernelAsync(F code)
+auto kernel_async(F code)
-> Future<decltype(code().get())>
{
typedef decltype(code().get()) T;
A contrived example of this would be:
@code{cpp}
-simgrid::simix::Future<int> future = simgrid::simix::kernelSync([&] {
+simgrid::simix::Future<int> future = simgrid::simix::kernel_sync([&] {
return kernel_wait_until(30).then(
[](simgrid::kernel::Future<void> future) {
return 42;
int res = future.get();
@endcode
-`kernelSync()` could be rewritten as:
+`kernel_sync()` could be rewritten as:
@code{cpp}
template<class F>
-auto kernelSync(F code) -> decltype(code().get())
+auto kernel_sync(F code) -> decltype(code().get())
{
- return kernelAsync(std::move(code)).get();
+ return kernel_async(std::move(code)).get();
}
@endcode
The semantic is equivalent but this form would require two simcalls
-instead of one to do the same job (one in `kernelAsync()` and one in
+instead of one to do the same job (one in `kernel_async()` 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
-
-SimGrid has had a C-based API for mutexes and condition variables for
-some time. These mutexes are different from the standard
-system-level mutex (`std::mutex`, `pthread_mutex_t`, etc.) because
-they work at simulation-level. Locking on a simulation mutex does
-not block the thread directly but makes a simcall
-(`simcall_mutex_lock()`) which asks the simulation kernel to wake the calling
-actor when it can get ownership of the mutex. Blocking directly at the
-OS level would deadlock the simulation.
-
-Reusing the C++ standard API for our simulation mutexes has many
-benefits:
-
- * it makes it easier for people familiar with the `std::mutex` to
- understand and use SimGrid mutexes;
-
- * we can benefit from a proven API;
-
- * we can reuse from generic library code in SimGrid.
-
-We defined a reference-counted `Mutex` class for this (which supports
-the [`Lockable`](http://en.cppreference.com/w/cpp/concept/Lockable)
-requirements, see
-[`[thread.req.lockable.req]`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4296.pdf#page=1175)
-in the C++14 standard):
-
-@code{cpp}
-class Mutex {
- friend ConditionVariable;
-private:
- friend simgrid::simix::Mutex;
- simgrid::simix::Mutex* mutex_;
- Mutex(simgrid::simix::Mutex* mutex) : mutex_(mutex) {}
-public:
-
- friend void intrusive_ptr_add_ref(Mutex* mutex);
- friend void intrusive_ptr_release(Mutex* mutex);
- using Ptr = boost::intrusive_ptr<Mutex>;
-
- // No copy:
- Mutex(Mutex const&) = delete;
- Mutex& operator=(Mutex const&) = delete;
-
- static Ptr createMutex();
-
-public:
- void lock();
- void unlock();
- bool try_lock();
-};
-@endcode
-
-The methods are simply wrappers around existing simcalls:
-
-@code{cpp}
-void Mutex::lock()
-{
- simcall_mutex_lock(mutex_);
-}
-@endcode
-
-Using the same API as `std::mutex` (`Lockable`) means we can use existing
-C++-standard code such as `std::unique_lock<Mutex>` or
-`std::lock_guard<Mutex>` for exception-safe mutex handling[^lock]:
-
-@code{cpp}
-{
- std::lock_guard<simgrid::s4u::Mutex> lock(*mutex);
- sum += 1;
-}
-@endcode
-
### Condition Variables
Similarly SimGrid already had simulation-level condition variables
@code{cpp}
class ConditionVariable {
private:
- friend s_smx_cond;
+ friend s_smx_cond_t;
smx_cond_t cond_;
ConditionVariable(smx_cond_t cond) : cond_(cond) {}
public:
simcall_cond_wait_timeout(cond_, lock.mutex()->mutex_, timeout);
return std::cv_status::no_timeout;
}
- catch (xbt_ex& e) {
-
+ catch (const simgrid::TimeoutException& e) {
// If the exception was a timeout, we have to take the lock again:
- if (e.category == timeout_error) {
- try {
- lock.mutex()->lock();
- return std::cv_status::timeout;
- }
- catch (...) {
- std::terminate();
- }
+ try {
+ lock.mutex()->lock();
+ return std::cv_status::timeout;
+ }
+ catch (...) {
+ std::terminate();
}
-
- std::terminate();
}
catch (...) {
std::terminate();
* the second one is a wait-based (`future.get()`) future used in the actors
which waits using a simcall.
-These futures are used to implement `kernelSync()` and `kernelAsync()` which
+These futures are used to implement `kernel_sync()` and `kernel_async()` which
expose asynchronous operations in the simulation kernel to the actors.
In addition, we wrote variations of some other C++ standard library
@code{cpp}
template<class T>
class Result {
- enum class ResultStatus {
- invalid,
- value,
- exception,
- };
public:
- Result();
- ~Result();
- Result(Result const& that);
- Result& operator=(Result const& that);
- Result(Result&& that);
- Result& operator=(Result&& that);
bool is_valid() const;
- void reset();
void set_exception(std::exception_ptr e);
void set_value(T&& value);
void set_value(T const& value);
T get();
private:
- ResultStatus status_ = ResultStatus::invalid;
- union {
- T value_;
- std::exception_ptr exception_;
- };
+ boost::variant<boost::blank, T, std::exception_ptr> value_;
};
@endcode~
in the simulation which we would like to avoid.
`std::try_lock()` should be safe to use though.
-*/
\ No newline at end of file
+*/
