Reorder the headers to ensure that ours are actually self-contained

[simgrid.git] / doc / doxygen / uhood_switch.doc

diff --git a/doc/doxygen/uhood_switch.doc b/doc/doxygen/uhood_switch.doc
index 43fac9b403ff168e5164845206e8aa8c1be375b0..ae652130c535cd0fa05275e71fd84035f8ccd75d 100644 (file)
--- a/doc/doxygen/uhood_switch.doc
+++ b/doc/doxygen/uhood_switch.doc
@@ -27,7 +27,7 @@ Mimicking the OS behavior may seem over-engineered here, but this is
 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
 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:
 commonly used by our users.
 
 So, the key ideas here are:


@@ -200,7 +200,7 @@ The crux of `future.then()` is:
 @code{cpp}
 template<class T>
 template<class F>
 @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;
 -> Future<decltype(continuation(std::move(*this)))>
 {
   typedef decltype(continuation(std::move(*this))) R;


@@ -304,14 +304,14 @@ as input. It looks like this:
 # This looks like C++ but it is a basic IDL-like language
 # (one definition per line) parsed by a python script:
 
 # 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_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();
 int  process_sleep(double duration) [[block]];
 
 smx_mutex_t mutex_init();


@@ -328,9 +328,9 @@ number and its arguments (among some other things):
 @code{cpp}
 struct s_smx_simcall {
   // Simcall number:
 @code{cpp}
 struct s_smx_simcall {
   // Simcall number:

-  e_smx_simcall_t call;
+  Simcall call;

   // Issuing actor:
   // Issuing actor:

-  smx_process_t issuer;
+  smx_actor_t issuer;

   // Arguments of the simcall:
   union u_smx_scalar args[11];
   // Result of the simcall:
   // Arguments of the simcall:
   union u_smx_scalar args[11];
   // Result of the simcall:


@@ -371,7 +371,7 @@ this generates a bunch of C++ files:
   responsible for wrapping the parameters in the `struct s_smx_simcall`;
   and wrapping out the result;
 
   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)
    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)


@@ -468,20 +468,20 @@ kernel which will wake up the actor (with
 `simgrid::simix::unblock(actor)`) when the operation is completed.
 
 This is wrapped in a higher-level primitive as well. The
 `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>
 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");
 
 {
   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]{
   simgrid::xbt::Result<T> result;
 
   simcall_run_blocking([&result, self, &code]{


@@ -510,7 +510,7 @@ auto kernelSync(F code) -> decltype(code().get())
 A contrived example of this would be:
 
 @code{cpp}
 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;
   return kernel_wait_until(30).then(
     [](simgrid::kernel::Future<void> future) {
       return 42;


@@ -521,7 +521,7 @@ int res = simgrid::simix::kernelSync([&] {
 
 ### Asynchronous operations {#uhood_switch_v2_async}
 
 
 ### 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::Future`)
 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::Future`)


@@ -551,7 +551,7 @@ T simgrid::simix::Future<T>::get()
 {
   if (!valid())
     throw std::future_error(std::future_errc::no_state);
 {
   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 {
   simgrid::xbt::Result<T> result;
   simcall_run_blocking([this, &result, self]{
     try {


@@ -572,12 +572,12 @@ T simgrid::simix::Future<T>::get()
 }
 @endcode
 
 }
 @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>
 `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;
   -> Future<decltype(code().get())>
 {
   typedef decltype(code().get()) T;


@@ -594,7 +594,7 @@ auto kernelAsync(F code)
 A contrived example of this would be:
 
 @code{cpp}
 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;
   return kernel_wait_until(30).then(
     [](simgrid::kernel::Future<void> future) {
       return 42;


@@ -605,18 +605,18 @@ do_some_stuff();
 int res = future.get();
 @endcode
 
 int res = future.get();
 @endcode
 

-`kernelSync()` could be rewritten as:
+`kernel_sync()` could be rewritten as:

 
 @code{cpp}
 template<class F>
 
 @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
 }
 @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()`).
 
 ## Mutexes and condition variables
 `.get()`).
 
 ## Mutexes and condition variables


@@ -629,7 +629,7 @@ which can be exposed using the same API as `std::condition_variable`:
 @code{cpp}
 class ConditionVariable {
 private:
 @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:
   smx_cond_t cond_;
   ConditionVariable(smx_cond_t cond) : cond_(cond) {}
 public:


@@ -708,20 +708,15 @@ std::cv_status ConditionVariable::wait_for(
     simcall_cond_wait_timeout(cond_, lock.mutex()->mutex_, timeout);
     return std::cv_status::no_timeout;
   }
     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 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();
   }
   catch (...) {
     std::terminate();


@@ -769,7 +764,7 @@ We wrote two future implementations based on the `std::future` API:
 * the second one is a wait-based (`future.get()`) future used in the actors
   which waits using a simcall.
 
 * 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
 expose asynchronous operations in the simulation kernel to the actors.
 
 In addition, we wrote variations of some other C++ standard library


@@ -794,7 +789,7 @@ Reusing the same API as the C++ standard library is very useful because:
 
 This type of approach might be useful for other libraries which define
 their own contexts. An example of this is
 
 This type of approach might be useful for other libraries which define
 their own contexts. An example of this is

-[Mordor](https://github.com/mozy/mordor), a I/O library using fibers
+[Mordor](https://github.com/mozy/mordor), an I/O library using fibers

 (cooperative scheduling): it implements cooperative/fiber
 [mutex](https://github.com/mozy/mordor/blob/4803b6343aee531bfc3588ffc26a0d0fdf14b274/mordor/fibersynchronization.h#L70),
 [recursive
 (cooperative scheduling): it implements cooperative/fiber
 [mutex](https://github.com/mozy/mordor/blob/4803b6343aee531bfc3588ffc26a0d0fdf14b274/mordor/fibersynchronization.h#L70),
 [recursive


@@ -815,30 +810,14 @@ single-object without shared-state and synchronisation:
 @code{cpp}
 template<class T>
 class Result {
 @code{cpp}
 template<class T>
 class Result {

-  enum class ResultStatus {
-    invalid,
-    value,
-    exception,
-  };

 public:
 public:

-  Result();
-  ~Result();
-  Result(Result const& that);
-  Result& operator=(Result const& that);
-  Result(Result&& that);
-  Result& operator=(Result&& that);

   bool is_valid() const;
   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:
   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~
 
 };
 @endcode~
 


@@ -974,4 +953,4 @@ auto makeTask(F code, Args... args)
     in the simulation which we would like to avoid.
     `std::try_lock()` should be safe to use though.
 
     in the simulation which we would like to avoid.
     `std::try_lock()` should be safe to use though.
 

-*/
\ No newline at end of file
+*/