From cdac506670725ae4fe40b3b1a31ceeb9488ce53a Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Tue, 8 Jan 2019 23:09:57 +0100 Subject: [PATCH] doc cosmetics, and cleanup the API more functions in the API, don't help users but mess them up - In python: - remove this_actor.kill(pid) - bind Actor.by_pid(pid) - remove this_actor.kill_all(), we have Actor.kill_all() - In C++: - deprecate s4u::Actor::kill(pid) - Various docstrings improvements --- docs/source/app_s4u.rst | 2 +- examples/python/CMakeLists.txt | 3 ++- examples/python/actor-kill/actor-kill.py | 4 ++-- examples/s4u/README.rst | 15 ++++++++---- examples/s4u/actor-kill/s4u-actor-kill.cpp | 2 +- .../s4u/actor-lifetime/s4u-actor-lifetime.cpp | 6 +++-- include/simgrid/s4u/Actor.hpp | 7 +++--- src/bindings/python/simgrid_python.cpp | 24 ++++++++++++------- src/s4u/s4u_Actor.cpp | 2 +- 9 files changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index ea65f530a2..3f3aaec09c 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -365,7 +365,7 @@ Here is a little example: } // The mutex gets automatically freed because the only existing reference gets out of scope -API C++ Reference +C++ API Reference ***************** .. _API_s4u_this_actor: diff --git a/examples/python/CMakeLists.txt b/examples/python/CMakeLists.txt index 709ee0fcb9..a997211d54 100644 --- a/examples/python/CMakeLists.txt +++ b/examples/python/CMakeLists.txt @@ -1,4 +1,4 @@ -foreach(example actor-create actor-daemon actor-join actor-kill actor-migrate actor-suspend actor-yield +foreach(example actor-create actor-daemon actor-join actor-kill actor-migrate actor-suspend actor-yield # actor-lifetime exec-basic) set(tesh_files ${tesh_files} ${CMAKE_CURRENT_SOURCE_DIR}/${example}/${example}.tesh) set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/${example}/${example}.py) @@ -14,5 +14,6 @@ foreach(example actor-create actor-daemon actor-join actor-kill actor-migrate ac endforeach() set(tesh_files examples/python/actor-create/actor-create_d.xml + examples/python/actor-lifetime/actor-lifetime_d.xml ${tesh_files} PARENT_SCOPE) set(examples_src ${examples_src} PARENT_SCOPE) diff --git a/examples/python/actor-kill/actor-kill.py b/examples/python/actor-kill/actor-kill.py index bfa31a3adb..a3118eca8f 100644 --- a/examples/python/actor-kill/actor-kill.py +++ b/examples/python/actor-kill/actor-kill.py @@ -35,7 +35,7 @@ def killer(): this_actor.sleep_for(2) this_actor.info("Kill the victim A") # - and then kill it - this_actor.kill(victimA.pid) # Kill by PID is legit + Actor.by_pid(victimA.pid).kill() # You can retrieve an actor from its PID (and then kill it) this_actor.sleep_for(1) @@ -52,7 +52,7 @@ def killer(): this_actor.sleep_for(1) this_actor.info("Killing everybody but myself") - this_actor.kill_all() + Actor.kill_all() this_actor.info("OK, goodbye now. I commit a suicide.") this_actor.exit() diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index 571632bff9..ca814d7c5c 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -38,15 +38,22 @@ 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. + `examples/python/actor-create/actor-create_d.xml `_ - |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 - :cpp:func:`void simgrid::s4u::Actor::kill(void)` or the - :cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` methods. - |br| `examples/s4u/actor-kill/s4u-actor-kill.cpp `_ + Actors can forcefully stop other actors. + + - |cpp| `examples/s4u/actor-kill/s4u-actor-kill.cpp `_ + :cpp:func:`void simgrid::s4u::Actor::kill(void)`, + :cpp:func:`void simgrid::s4u::Actor::kill_all()`, + :cpp:func:`simgrid::s4u::this_actor::exit`. + - |py| `examples/python/actor-kill/actor-kill.py `_ + :py:func:`simgrid.Actor.kill`, + :py:func:`simgrid.Actor.kill_all`, + :py:func:`simgrid.this_actor.exit`. - **Controling the actor life cycle from the XML:** You can specify a start time and a kill time in the deployment diff --git a/examples/s4u/actor-kill/s4u-actor-kill.cpp b/examples/s4u/actor-kill/s4u-actor-kill.cpp index 785ab6d868..9c0f356462 100644 --- a/examples/s4u/actor-kill/s4u-actor-kill.cpp +++ b/examples/s4u/actor-kill/s4u-actor-kill.cpp @@ -37,7 +37,7 @@ static void killer() simgrid::s4u::this_actor::sleep_for(2); XBT_INFO("Kill the victim A"); /* - and then kill it */ - simgrid::s4u::Actor::kill(victimA->get_pid()); // Kill by PID is legit + simgrid::s4u::Actor::by_pid(victimA->get_pid())->kill(); // You can retrieve an actor from its PID (and then kill it) simgrid::s4u::this_actor::sleep_for(1); diff --git a/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp b/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp index c11c4b9e58..9f12c5505f 100644 --- a/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp +++ b/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp @@ -22,11 +22,13 @@ public: XBT_INFO("Exiting now (done sleeping or got killed)."); }, nullptr); - + } + void operator()() + { XBT_INFO("Hello! I go to sleep."); simgrid::s4u::this_actor::sleep_for(10); + XBT_INFO("Done sleeping."); } - void operator()() { XBT_INFO("Done sleeping."); } }; int main(int argc, char* argv[]) diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 06ef8a2bb9..f0c41432db 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -258,9 +258,6 @@ public: */ void kill(); - /** Kill an actor from its ID */ - static void kill(aid_t pid); - /** Retrieves the actor that have the given PID (or nullptr if not existing) */ static ActorPtr by_pid(aid_t pid); @@ -279,7 +276,7 @@ public: void join(double timeout); Actor* restart(); - /** Ask kindly to all actors to die. Only the issuer will survive. */ + /** Kill all actors (but the issuer). Being killed is not something that actors can delay or avoid. */ static void kill_all(); /** Returns the internal implementation of this actor */ @@ -292,6 +289,8 @@ public: void set_property(std::string key, std::string value); #ifndef DOXYGEN + XBT_ATTRIB_DEPRECATED_v325("Please use Actor::by_pid(pid).kill() instead") static void kill(aid_t pid); + /** @deprecated See Actor::create() */ XBT_ATTRIB_DEPRECATED_v323("Please use Actor::create()") static ActorPtr createActor( const char* name, s4u::Host* host, std::function code) diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp index a3acac5858..211e65053e 100644 --- a/src/bindings/python/simgrid_python.cpp +++ b/src/bindings/python/simgrid_python.cpp @@ -3,6 +3,7 @@ /* 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. */ +#include #include // Must be first #include @@ -72,13 +73,20 @@ PYBIND11_MODULE(simgrid, m) m2.def("yield_", &simgrid::s4u::this_actor::yield, "Yield the actor, see :cpp:func:`void simgrid::s4u::this_actor::yield()`"); m2.def("exit", &simgrid::s4u::this_actor::exit, "kill the current actor"); - m2.def("kill", [](py::int_ pid) { Actor::kill(pid); }, "Kill an actor by pid"); - m2.def("kill_all", &Actor::kill_all, "Kill all actors but the caller."); - - m2.def( - "on_exit", - [](py::function fun) { simgrid::s4u::this_actor::on_exit([fun](int ignored, void* data) { fun(); }, nullptr); }, - ""); + m2.def("on_exit", + [](py::object fun) { + ActorPtr act = Actor::self(); + simgrid::s4u::this_actor::on_exit( + [act, fun](int ignored, void* data) { + try { + fun(); + } catch (py::error_already_set& e) { + xbt_die("Error while executing the on_exit lambda: %s", e.what()); + } + }, + nullptr); + }, + ""); /* Class Engine */ py::class_(m, "Engine", "Simulation Engine, see :ref:`class s4u::Engine `") @@ -180,12 +188,12 @@ PYBIND11_MODULE(simgrid, m) "Create an actor from a function or an object, see :cpp:func:`simgrid::s4u::Actor::create()`") .def_property("host", &Actor::get_host, &Actor::migrate, "The host on which this actor is located") .def_property_readonly("pid", &Actor::get_pid, "The PID (unique identifier) of this actor.") + .def("by_pid", &Actor::by_pid, "Retrieve an actor by its PID") .def("daemonize", &Actor::daemonize, "This actor will be automatically terminated when the last non-daemon actor finishes, see :cpp:func:`void " "simgrid::s4u::Actor::daemonize()`") .def("join", py::overload_cast(&Actor::join), "Wait for the actor to finish, see :cpp:func:`void simgrid::s4u::Actor::join(double)`", py::arg("timeout")) - .def("kill", [](py::int_ pid) { Actor::kill(pid); }, "Kill an actor by pid") .def("kill", [](ActorPtr act) { act->kill(); }, "Kill that actor") .def("kill_all", &Actor::kill_all, "Kill all actors but the caller.") .def("migrate", &Actor::migrate, diff --git a/src/s4u/s4u_Actor.cpp b/src/s4u/s4u_Actor.cpp index a8228f697e..b22b2b0531 100644 --- a/src/s4u/s4u_Actor.cpp +++ b/src/s4u/s4u_Actor.cpp @@ -175,7 +175,7 @@ double Actor::get_kill_time() return SIMIX_timer_get_date(pimpl_->kill_timer); } -void Actor::kill(aid_t pid) +void Actor::kill(aid_t pid) // deprecated { smx_actor_t killer = SIMIX_process_self(); smx_actor_t process = SIMIX_process_from_PID(pid); -- 2.20.1