From 4724bddcd04a5531a88dd84f798b4c8cc7f1bd00 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Tue, 8 Jan 2019 06:32:35 +0100 Subject: [PATCH] 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. --- examples/s4u/README.rst | 56 +++++++++++++++----------- include/simgrid/s4u/Actor.hpp | 34 +++++++--------- src/bindings/python/simgrid_python.cpp | 8 ++-- src/s4u/s4u_Actor.cpp | 10 ----- src/simix/libsmx.cpp | 7 +--- teshsuite/s4u/actor/actor.cpp | 3 +- 6 files changed, 53 insertions(+), 65 deletions(-) diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index 53f349bfa2..571632bff9 100644 --- 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. - |br| |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp `_ - |br| |py| `examples/python/actor-create/actor-create.py `_ + + - |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp `_ + - |py| `examples/python/actor-create/actor-create.py `_ - **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. - |br| |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp `_ - |br| |py| `examples/python/actor-daemon/actor-daemon.py `_ + + - |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp `_ + - |py| `examples/python/actor-daemon/actor-daemon.py `_ 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 `_ + Actors can be suspended and resumed during their executions. + + - |cpp| `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 `_ + :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. - |br| |cpp| `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 `_ - :py:func:`simgrid.this_actor.migrate()` |py| + + - |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp `_ + :cpp:func:`simgrid::s4u::this_actor::migrate()` + - |py| `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. - |br| |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp `_ - :cpp:func:`simgrid::s4u::Actor::join()` |cpp| - |br| |py| `examples/python/actor-join/actor-join.py `_ - :py:func:`simgrid.Actor.join()` |py| + + - |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp `_ + :cpp:func:`simgrid::s4u::Actor::join()` + - |py| `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 - at this timestamp. - |br| |cpp| `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 `_ - :py:func:`simgrid.this_actor.yield_()` |py| + at this timestamp. + + - |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp `_ + :cpp:func:`simgrid::s4u::this_actor::yield()` + - |py| `examples/python/actor-yield/actor-yield.py `_ + :py:func:`simgrid.this_actor.yield_()` 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. - |br| |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp `_ - |br| |py| `examples/python/exec-basic/exec-basic.py `_ + + - |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp `_ + - |py| `examples/python/exec-basic/exec-basic.py `_ - **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 87b0082596..d0a0086b6d 100644 --- 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; - /** 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(); - /** 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 yield(); - /** Returns true if the actor is suspended. */ bool is_suspended(); @@ -394,9 +392,9 @@ namespace this_actor { 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); -/** 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 inline void sleep_for(std::chrono::duration duration) @@ -422,7 +420,7 @@ XBT_PUBLIC void execute(double flop, double priority); * @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: @@ -476,8 +474,8 @@ XBT_PUBLIC void parallel_execute(std::vector hosts, std::vector bytes_amounts); /** \rst - * Block the actor until the built :ref:`parallel execution ` completes, or until the timeout. - * \endrst + * Block the current actor until the built :ref:`parallel execution ` completes, or until the + * timeout. \endrst */ XBT_PUBLIC void parallel_execute(std::vector hosts, std::vector flops_amounts, std::vector 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 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(); -/** @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(); -/** @brief Yield the actor. */ +/** @brief Yield the current actor. */ 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 bool is_suspended(); - -/** @brief kill the actor. */ +/** @brief kill the current actor. */ 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 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); /** @} */ @@ -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(); -/** @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() */ diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp index d5ed15963a..1a02f46d0a 100644 --- 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("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 f693e258b1..b97e32e542 100644 --- 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()); } -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(); @@ -442,10 +436,6 @@ Host* getHost() /* deprecated */ { 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); diff --git a/src/simix/libsmx.cpp b/src/simix/libsmx.cpp index 7bf0ed312a..38249b8fff 100644 --- 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 - * @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) { diff --git a/teshsuite/s4u/actor/actor.cpp b/teshsuite/s4u/actor/actor.cpp index 900310340e..ba2d6a266b 100644 --- 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("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!"); -- 2.20.1