Various doc improvements

Also kill meaningless functions:
- Actor::yield() was not even implemented, only declared
- this_actor::is_suspended() can only return false, because suspended
  actors don't get executed.

diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst
index 53f349b..571632b 100644 (file)
--- a/examples/s4u/README.rst
+++ b/examples/s4u/README.rst
@@ -38,8 +38,9 @@ Starting and Stoping Actors
   - **Creating actors:**
     Most actors are started from the deployment XML file, but there is other methods.
     This example show them all.
   - **Creating actors:**
     Most actors are started from the deployment XML file, but there is other methods.
     This example show them all.

-    |br| |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-create/s4u-actor-create.cpp>`_
-    |br|  |py| `examples/python/actor-create/actor-create.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-create/actor-create.py>`_
+    
+    - |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-create/s4u-actor-create.cpp>`_
+    - |py|  `examples/python/actor-create/actor-create.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-create/actor-create.py>`_

     
   - **Kill actors:**
     Actors can forcefully stop other actors with the 
     
   - **Kill actors:**
     Actors can forcefully stop other actors with the 


@@ -56,40 +57,48 @@ Starting and Stoping Actors
   - **Daemonize actors:**
     Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
     actor into a daemon that will be automatically killed once the simulation is over.
   - **Daemonize actors:**
     Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
     actor into a daemon that will be automatically killed once the simulation is over.

-    |br| |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
-    |br|  |py| `examples/python/actor-daemon/actor-daemon.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-daemon/actor-daemon.py>`_
+    
+    - |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
+    - |py|  `examples/python/actor-daemon/actor-daemon.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-daemon/actor-daemon.py>`_

     
 Inter-Actors Interactions
 -------------------------
 
   - **Suspend and Resume actors:**    
     
 Inter-Actors Interactions
 -------------------------
 
   - **Suspend and Resume actors:**    

-    Actors can be suspended and resumed during their executions thanks
-    to :cpp:func:`simgrid::s4u::Actor::suspend()` and
-    :cpp:func:`simgrid::s4u::Actor::resume()`.
-    |br| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-suspend/s4u-actor-suspend.cpp>`_
+    Actors can be suspended and resumed during their executions.
+    
+    - |cpp| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-suspend/s4u-actor-suspend.cpp>`_
+      :cpp:func:`simgrid::s4u::this_actor::suspend()`,
+      :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
+    - |py|  `examples/python/actor-suspend/actor-suspend.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-suspend/actor-suspend.py>`_
+      :py:func:`simgrid.this_actor.suspend()`,
+      :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, :py:func:`simgrid.Actor.is_suspended()`.

 
   - **Migrating Actors:**
     Actors can move or be moved from a host to another very easily.
 
   - **Migrating Actors:**
     Actors can move or be moved from a host to another very easily.

-    |br| |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migrate/s4u-actor-migrate.cpp>`_
-    :cpp:func:`simgrid::s4u::this_actor::migrate()` |cpp|
-    |br|  |py| `examples/python/actor-migrate/actor-migrate.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-migrate/actor-migrate.py>`_
-    :py:func:`simgrid.this_actor.migrate()` |py|
+    
+    - |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migrate/s4u-actor-migrate.cpp>`_
+      :cpp:func:`simgrid::s4u::this_actor::migrate()`
+    - |py|  `examples/python/actor-migrate/actor-migrate.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-migrate/actor-migrate.py>`_
+      :py:func:`simgrid.this_actor.migrate()`

 
   - **Waiting for the termination of an actor:** (joining on it)
     You can block the current actor until the end of another actor.
 
   - **Waiting for the termination of an actor:** (joining on it)
     You can block the current actor until the end of another actor.

-    |br| |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
-    :cpp:func:`simgrid::s4u::Actor::join()` |cpp|
-    |br| |py| `examples/python/actor-join/actor-join.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-join/actor-join.py>`_
-    :py:func:`simgrid.Actor.join()` |py|
+    
+    - |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
+      :cpp:func:`simgrid::s4u::Actor::join()`
+    - |py|  `examples/python/actor-join/actor-join.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-join/actor-join.py>`_
+      :py:func:`simgrid.Actor.join()`

 
   - **Yielding to other actors**.
     The ```yield()``` function interrupts the execution of the current
     actor, leaving a chance to the other actors that are ready to run
 
   - **Yielding to other actors**.
     The ```yield()``` function interrupts the execution of the current
     actor, leaving a chance to the other actors that are ready to run

-    at this timestamp. 
-    |br| |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
-    :cpp:func:`simgrid::s4u::this_actor::yield()` |cpp|
-    |br|  |py| `examples/python/actor-yield/actor-yield.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-yield/actor-yield.py>`_
-    :py:func:`simgrid.this_actor.yield_()` |py|
+    at this timestamp.
+    
+    - |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
+      :cpp:func:`simgrid::s4u::this_actor::yield()`
+    - |py|  `examples/python/actor-yield/actor-yield.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-yield/actor-yield.py>`_
+      :py:func:`simgrid.this_actor.yield_()`

 
 Traces Replay as a Workload
 ---------------------------
 
 Traces Replay as a Workload
 ---------------------------


@@ -160,8 +169,9 @@ Executions on the CPU
     the actor until a given amount of flops gets computed on its simulated
     host. Some executions can be given an higher priority so that they
     get more resources.
     the actor until a given amount of flops gets computed on its simulated
     host. Some executions can be given an higher priority so that they
     get more resources.

-    |br| |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
-    |br|  |py| `examples/python/exec-basic/exec-basic.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-basic/exec-basic.py>`_
+    
+    - |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
+    - |py|  `examples/python/exec-basic/exec-basic.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-basic/exec-basic.py>`_

 
   - **Asynchronous execution:**
     You can start asynchronous executions, just like you would fire
 
   - **Asynchronous execution:**
     You can start asynchronous executions, just like you would fire

diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp
index 87b0082..d0a0086 100644 (file)
--- a/include/simgrid/s4u/Actor.hpp
+++ b/include/simgrid/s4u/Actor.hpp
@@ -211,14 +211,12 @@ public:
   /** Retrieves the actor ID of that actor's creator */
   aid_t get_ppid() const;
 
   /** Retrieves the actor ID of that actor's creator */
   aid_t get_ppid() const;
 

-  /** Suspend an actor by suspending the task on which it was waiting for the completion. */
+  /** Suspend an actor, that is blocked until resume()ed by another actor */

   void suspend();
 
   void suspend();
 

-  /** Resume a suspended actor by resuming the task on which it was waiting for the completion. */
+  /** Resume an actor that was previously suspend()ed */

   void resume();
 
   void resume();
 

-  void yield();
-

   /** Returns true if the actor is suspended. */
   bool is_suspended();
 
   /** Returns true if the actor is suspended. */
   bool is_suspended();
 


@@ -394,9 +392,9 @@ namespace this_actor {
 
 XBT_PUBLIC bool is_maestro();
 
 
 XBT_PUBLIC bool is_maestro();
 

-/** Block the actor sleeping for that amount of seconds (may throw hostFailure) */
+/** Block the current actor sleeping for that amount of seconds (may throw hostFailure) */

 XBT_PUBLIC void sleep_for(double duration);
 XBT_PUBLIC void sleep_for(double duration);

-/** Block the actor sleeping until the specified timestamp (may throw hostFailure) */
+/** Block the current actor sleeping until the specified timestamp (may throw hostFailure) */

 XBT_PUBLIC void sleep_until(double timeout);
 
 template <class Rep, class Period> inline void sleep_for(std::chrono::duration<Rep, Period> duration)
 XBT_PUBLIC void sleep_until(double timeout);
 
 template <class Rep, class Period> inline void sleep_for(std::chrono::duration<Rep, Period> duration)


@@ -422,7 +420,7 @@ XBT_PUBLIC void execute(double flop, double priority);
  * @example examples/s4u/exec-ptask/s4u-exec-ptask.cpp
  */
 
  * @example examples/s4u/exec-ptask/s4u-exec-ptask.cpp
  */
 

-/** Block the actor until the built parallel execution terminates
+/** Block the current actor until the built parallel execution terminates

  *
  * \rst
  * .. _API_s4u_parallel_execute:
  *
  * \rst
  * .. _API_s4u_parallel_execute:


@@ -476,8 +474,8 @@ XBT_PUBLIC void parallel_execute(std::vector<s4u::Host*> hosts, std::vector<doub
                                  std::vector<double> bytes_amounts);
 
 /** \rst
                                  std::vector<double> bytes_amounts);
 
 /** \rst

- * Block the actor until the built :ref:`parallel execution <API_s4u_parallel_execute>` completes, or until the timeout.
- * \endrst
+ * Block the current actor until the built :ref:`parallel execution <API_s4u_parallel_execute>` completes, or until the
+ * timeout. \endrst

  */
 XBT_PUBLIC void parallel_execute(std::vector<s4u::Host*> hosts, std::vector<double> flops_amounts,
                                  std::vector<double> bytes_amounts, double timeout);
  */
 XBT_PUBLIC void parallel_execute(std::vector<s4u::Host*> hosts, std::vector<double> flops_amounts,
                                  std::vector<double> bytes_amounts, double timeout);


@@ -504,27 +502,25 @@ XBT_PUBLIC std::string get_name();
 /** @brief Returns the name of the current actor as a C string. */
 XBT_PUBLIC const char* get_cname();
 
 /** @brief Returns the name of the current actor as a C string. */
 XBT_PUBLIC const char* get_cname();
 

-/** @brief Returns the name of the host on which the actor is running. */
+/** @brief Returns the name of the host on which the curret actor is running. */

 XBT_PUBLIC Host* get_host();
 
 XBT_PUBLIC Host* get_host();
 

-/** @brief Suspend the actor, that is blocked until resume()ed by another actor. */
+/** @brief Suspend the current actor, that is blocked until resume()ed by another actor. */

 XBT_PUBLIC void suspend();
 
 XBT_PUBLIC void suspend();
 

-/** @brief Yield the actor. */
+/** @brief Yield the current actor. */

 XBT_PUBLIC void yield();
 
 XBT_PUBLIC void yield();
 

-/** @brief Resume the actor, that was suspend()ed previously. */
+/** @brief Resume the current actor, that was suspend()ed previously. */

 XBT_PUBLIC void resume();
 
 XBT_PUBLIC void resume();
 

-XBT_PUBLIC bool is_suspended();
-
-/** @brief kill the actor. */
+/** @brief kill the current actor. */

 XBT_PUBLIC void exit();
 
 XBT_PUBLIC void exit();
 

-/** @brief Add a function to the list of "on_exit" functions. */
+/** @brief Add a function to the list of "on_exit" functions of the current actor. */

 XBT_PUBLIC void on_exit(std::function<void(int, void*)> fun, void* data);
 
 XBT_PUBLIC void on_exit(std::function<void(int, void*)> fun, void* data);
 

-/** @brief Migrate the actor to a new host. */
+/** @brief Migrate the current actor to a new host. */

 XBT_PUBLIC void migrate(Host* new_host);
 
 /** @} */
 XBT_PUBLIC void migrate(Host* new_host);
 
 /** @} */


@@ -545,8 +541,6 @@ XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::get_pid()") XBT_PUBLIC aid_t
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::get_ppid()") XBT_PUBLIC aid_t getPpid();
 /** @deprecated See this_actor::get_host() */
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::get_host()") XBT_PUBLIC Host* getHost();
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::get_ppid()") XBT_PUBLIC aid_t getPpid();
 /** @deprecated See this_actor::get_host() */
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::get_host()") XBT_PUBLIC Host* getHost();

-/** @deprecated See this_actor::is_suspended() */
-XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::is_suspended()") XBT_PUBLIC bool isSuspended();

 /** @deprecated See this_actor::on_exit() */
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::on_exit()") XBT_PUBLIC void onExit(int_f_pvoid_pvoid_t fun, void* data);
 /** @deprecated See this_actor::exit() */
 /** @deprecated See this_actor::on_exit() */
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::on_exit()") XBT_PUBLIC void onExit(int_f_pvoid_pvoid_t fun, void* data);
 /** @deprecated See this_actor::exit() */

diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp
index d5ed159..1a02f46 100644 (file)
--- a/src/bindings/python/simgrid_python.cpp
+++ b/src/bindings/python/simgrid_python.cpp
@@ -179,9 +179,7 @@ PYBIND11_MODULE(simgrid, m)
       .def("migrate", &Actor::migrate,
            "Moves that actor to another host, see :cpp:func:`void simgrid::s4u::Actor::migrate()`", py::arg("dest"))
       .def("self", &Actor::self, "Retrieves the current actor, see :cpp:func:`void simgrid::s4u::Actor::self()`")
       .def("migrate", &Actor::migrate,
            "Moves that actor to another host, see :cpp:func:`void simgrid::s4u::Actor::migrate()`", py::arg("dest"))
       .def("self", &Actor::self, "Retrieves the current actor, see :cpp:func:`void simgrid::s4u::Actor::self()`")

-      .def("suspend", &Actor::suspend,
-           "Suspend that actor, that is blocked until resume()ed by another actor. See :cpp:func:`void "
-           "simgrid::s4u::Actor::suspend()`")
-      .def("resume", &Actor::resume,
-           "Resume that actor, that was previously suspend()ed. See :cpp:func:`void simgrid::s4u::Actor::suspend()`");
+      .def("is_suspended", &Actor::is_suspended, "Returns True if that actor is currently suspended.")
+      .def("suspend", &Actor::suspend, "Suspend that actor, that is blocked until resume()ed by another actor.")
+      .def("resume", &Actor::resume, "Resume that actor, that was previously suspend()ed.");

 }
 }

diff --git a/src/s4u/s4u_Actor.cpp b/src/s4u/s4u_Actor.cpp
index f693e25..b97e32e 100644 (file)
--- a/src/s4u/s4u_Actor.cpp
+++ b/src/s4u/s4u_Actor.cpp
@@ -392,12 +392,6 @@ void resume()
   simgrid::s4u::Actor::on_resume(process->iface());
 }
 
   simgrid::s4u::Actor::on_resume(process->iface());
 }
 

-bool is_suspended()
-{
-  smx_actor_t process = SIMIX_process_self();
-  return simgrid::simix::simcall([process] { return process->suspended_; });
-}
-

 void exit()
 {
   smx_actor_t process = SIMIX_process_self();
 void exit()
 {
   smx_actor_t process = SIMIX_process_self();


@@ -442,10 +436,6 @@ Host* getHost() /* deprecated */
 {
   return get_host();
 }
 {
   return get_host();
 }

-bool isSuspended() /* deprecated */
-{
-  return is_suspended();
-}

 void on_exit(int_f_pvoid_pvoid_t fun, void* data) /* deprecated */
 {
   SIMIX_process_self()->iface()->on_exit([fun](int a, void* b) { fun((void*)(intptr_t)a, b); }, data);
 void on_exit(int_f_pvoid_pvoid_t fun, void* data) /* deprecated */
 {
   SIMIX_process_self()->iface()->on_exit([fun](int a, void* b) { fun((void*)(intptr_t)a, b); }, data);

diff --git a/src/simix/libsmx.cpp b/src/simix/libsmx.cpp
index 7bf0ed3..38249b8 100644 (file)
--- a/src/simix/libsmx.cpp
+++ b/src/simix/libsmx.cpp
@@ -166,12 +166,7 @@ void simcall_process_join(smx_actor_t process, double timeout)
 
 /**
  * @ingroup simix_process_management
 
 /**
  * @ingroup simix_process_management

- * @brief Suspends a process.
- *
- * This function suspends the process by suspending the synchro
- * it was waiting for completion.
- *
- * @param process a SIMIX process
+ * @brief Suspends an actor

  */
 void simcall_process_suspend(smx_actor_t process)
 {
  */
 void simcall_process_suspend(smx_actor_t process)
 {

diff --git a/teshsuite/s4u/actor/actor.cpp b/teshsuite/s4u/actor/actor.cpp
index 9003103..ba2d6a2 100644 (file)
--- a/teshsuite/s4u/actor/actor.cpp
+++ b/teshsuite/s4u/actor/actor.cpp
@@ -13,7 +13,8 @@ static void worker()
   XBT_INFO("Worker started (PID:%ld, PPID:%ld)", simgrid::s4u::this_actor::get_pid(),
            simgrid::s4u::this_actor::get_ppid());
   while (1) {
   XBT_INFO("Worker started (PID:%ld, PPID:%ld)", simgrid::s4u::this_actor::get_pid(),
            simgrid::s4u::this_actor::get_ppid());
   while (1) {

-    XBT_INFO("Plop i am %ssuspended", simgrid::s4u::this_actor::is_suspended() ? "" : "not ");
+    simgrid::s4u::this_actor::yield();
+    XBT_INFO("Plop i am not suspended");

     simgrid::s4u::this_actor::sleep_for(1);
   }
   XBT_INFO("I'm done. See you!");
     simgrid::s4u::this_actor::sleep_for(1);
   }
   XBT_INFO("I'm done. See you!");