From 5f8f2fab9dcec8a5537ab01f82c12e2f7e0b8370 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Fri, 21 Jan 2022 17:02:55 +0100 Subject: [PATCH] Fix some more problems in the doc + cosmetics + extend python a bit --- docs/source/Tutorial_Algorithms.rst | 59 ++++++++++++++++---------- docs/source/app_s4u.rst | 9 ++++ src/bindings/python/simgrid_python.cpp | 20 ++++++--- tools/docker/Dockerfile.tuto-s4u | 4 +- 4 files changed, 61 insertions(+), 31 deletions(-) diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst index fd8a689e86..9ec483466f 100644 --- a/docs/source/Tutorial_Algorithms.rst +++ b/docs/source/Tutorial_Algorithms.rst @@ -683,23 +683,23 @@ Creating the workers from the master .. code-block:: cpp - void my_actor(int param1, double param2, std::string param3) { - ... - } - int main(int argc, char argv**) { - ... - simgrid::s4u::ActorPtr actor; - actor = simgrid::s4u::Actor::create("name", simgrid::s4u::Host::by_name("the_host"), - &my_actor, 42, 3.14, "thevalue"); - ... - } + void my_actor(int param1, double param2, std::string param3) { + ... + } + int main(int argc, char argv**) { + ... + simgrid::s4u::ActorPtr actor; + actor = simgrid::s4u::Actor::create("name", simgrid::s4u::Host::by_name("the_host"), + &my_actor, 42, 3.14, "thevalue"); + ... + } .. group-tab:: Python For that, the master needs to retrieve the list of hosts declared in - the platform with :py:func:`simgrid.Engine.get_all_hosts`. - Then, the master should start the worker actors with - :py:func:`simgrid.Actor.create`. + the platform with :py:func:`simgrid.Engine.get_all_hosts`. Since this method is not static, + you may want to call it on the Engine instance, as in ``Engine.instance().get_all_hosts()``. + Then, the master should start the worker actors with :py:func:`simgrid.Actor.create`. ``Actor.create(name, host, func, params...)`` is a very flexible function. Its third parameter is the function that the actor should @@ -727,11 +727,22 @@ Since we want later to study concurrent applications, it is advised to use a mailbox name that is unique over the simulation even if there is more than one master. -One possibility for that is to use the actor ID (aid) of each worker -as a mailbox name. The master can retrieve the aid of the newly -created actor with ``get_pid()`` while the actor itself can -retrieve its own aid with ``this_actor::get_pid()``. -The retrieved value is an ``aid_t``, which is an alias for ``long``. +.. tabs:: + + .. group-tab:: C++ + + One possibility for that is to use the actor ID (aid) of each worker + as a mailbox name. The master can retrieve the aid of the newly + created actor with :cpp:func:`simgrid::s4u::Actor::get_pid()` while the actor itself can + retrieve its own aid with :cpp:func:`simgrid::s4u::this_actor::get_pid()`. + The retrieved value is an :cpp:type:`aid_t`, which is an alias for ``long``. + + .. group-tab:: Python + + One possibility for that is to use the actor ID of each worker + as a mailbox name. The master can retrieve the aid of the newly + created actor with :py:func:`simgrid.Actor.pid` while the actor itself can + retrieve its own aid with :py:func:`simgrid.this_actor.get_pid()`. Wrap up ....... @@ -775,7 +786,7 @@ simulation. Instead, retrieve the time in the simulated world with You can still stop your workers with a specific task as previously, or you may kill them forcefully with :cpp:func:`simgrid::s4u::Actor::kill` (C++) -:py:func:`simgrid.Actor.kill` (C++). +:py:func:`simgrid.Actor.kill` (Python). Anyway, the new deployment `deployment3.xml` file should thus look like this: @@ -787,8 +798,8 @@ Controlling the message verbosity ................................. Not all messages are equally informative, so you probably want to -change some of the *info* messages (C: :c:macro:`XBT_INFO`; Python: :py:func:`this_actor.info`) -into *debug* messages`(C: c:macro:`XBT_DEBUG`; Python: :py:func:`this_actor.debug`) so that they are +change some of the *info* messages (C: :c:macro:`XBT_INFO`; Python: :py:func:`simgrid.this_actor.info`) +into *debug* messages`(C: :c:macro:`XBT_DEBUG`; Python: :py:func:`simgrid.this_actor.debug`) so that they are hidden by default. For example, you may want to use an *info* message once every 100 tasks and *debug* when sending all the other tasks. Or you could show only the total number of tasks processed by @@ -888,12 +899,14 @@ will categorize the tasks. Instead of starting the execution in one function call only with ``this_actor::execute(cost)``, you need to create the execution activity, set its tracing category, start it -and wait for its completion, as follows: +and wait for its completion, as follows. .. tabs:: .. group-tab:: C++ + Use :cpp:func:`simgrid::s4u::Exec::set_tracing_category` to change the category of an execution. + .. code-block:: cpp simgrid::s4u::ExecPtr exec = simgrid::s4u::this_actor::exec_init(compute_cost); @@ -909,6 +922,8 @@ and wait for its completion, as follows: .. group-tab:: Python + Use :py:func:`simgrid.Exec.set_tracing_category` to change the category of an execution. + .. code-block:: python exec = simgrid:.this_actor.exec_init(compute_cost) diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 36c6dd3245..c86574390a 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -670,6 +670,9 @@ Querying info .. autofunction:: simgrid.this_actor.get_host .. autofunction:: simgrid.this_actor.set_host + .. autofunction:: simgrid.this_actor.get_pid() + .. autofunction:: simgrid.this_actor.get_ppid() + .. group-tab:: C .. doxygenfunction:: sg_actor_self_get_data() @@ -704,8 +707,13 @@ Logging messages .. tabs:: + .. group-tab:: C++ + + Please refer to :ref:`the relevant documentation `. + .. group-tab:: Python + .. autofunction:: simgrid.this_actor.debug .. autofunction:: simgrid.this_actor.info .. autofunction:: simgrid.this_actor.error @@ -812,6 +820,7 @@ Engin initialization .. group-tab:: Python + .. automethod:: simgrid.Engine.__init__ .. automethod:: simgrid.Engine.instance .. group-tab:: C diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp index 2aa3e27fef..0bf85989ee 100644 --- a/src/bindings/python/simgrid_python.cpp +++ b/src/bindings/python/simgrid_python.cpp @@ -87,6 +87,8 @@ PYBIND11_MODULE(simgrid, m) /* this_actor namespace */ m.def_submodule("this_actor", "Bindings of the s4u::this_actor namespace. See the C++ documentation for details.") + .def( + "debug", [](const char* s) { XBT_DEBUG("%s", s); }, "Display a logging message of 'debug' priority.") .def( "info", [](const char* s) { XBT_INFO("%s", s); }, "Display a logging message of 'info' priority.") .def( @@ -123,17 +125,21 @@ PYBIND11_MODULE(simgrid, m) } }); }, - py::call_guard(), ""); + py::call_guard(), "") + .def("get_pid", &simgrid::s4u::this_actor::get_pid, "Retrieves PID of the current actor") + .def("get_ppid", &simgrid::s4u::this_actor::get_ppid, + "Retrieves PPID of the current actor (i.e., the PID of its parent)."); /* Class Engine */ py::class_(m, "Engine", "Simulation Engine") .def(py::init([](std::vector args) { - auto argc = static_cast(args.size()); - std::vector argv(args.size() + 1); // argv[argc] is nullptr - std::transform(begin(args), end(args), begin(argv), [](std::string& s) { return &s.front(); }); - // Currently this can be dangling, we should wrap this somehow. - return new simgrid::s4u::Engine(&argc, argv.data()); - })) + auto argc = static_cast(args.size()); + std::vector argv(args.size() + 1); // argv[argc] is nullptr + std::transform(begin(args), end(args), begin(argv), [](std::string& s) { return &s.front(); }); + // Currently this can be dangling, we should wrap this somehow. + return new simgrid::s4u::Engine(&argc, argv.data()); + }), + "The constructor should take the parameters from the command line, as is ") .def_static("get_clock", &Engine::get_clock, "The simulation time, ie the amount of simulated seconds since the simulation start.") .def_static( diff --git a/tools/docker/Dockerfile.tuto-s4u b/tools/docker/Dockerfile.tuto-s4u index 3e0f308021..f1f593946d 100644 --- a/tools/docker/Dockerfile.tuto-s4u +++ b/tools/docker/Dockerfile.tuto-s4u @@ -5,10 +5,10 @@ RUN apt update && apt -y upgrade # - Clone simgrid-template-s4u, as it is needed by the tutorial # - Add an empty makefile advising to run cmake before make, just in case -RUN apt install -y python-is-python3 pajeng r-base r-cran-tidyverse r-cran-devtools cmake g++ git libboost-dev flex bison libfmt-dev&& \ +RUN apt install -y python-is-python3 pajeng r-base r-cran-tidyverse r-cran-devtools cmake g++ git libboost-dev flex bison libfmt-dev && \ cd /source && \ git clone --depth=1 https://framagit.org/simgrid/simgrid-template-s4u.git simgrid-template-s4u.git && \ - printf "master-workers ping-pong:\n\t@echo \"Please run the following command before make:\";echo \" cmake .\"; exit 1" > Makefile &&\ + printf "master-workers ping-pong:\n\t@echo \"Please run the following command before make:\";echo \" cmake .\"; exit 1" > Makefile && \ apt autoremove -y && apt clean && apt autoclean RUN Rscript -e "library(devtools); install_github('schnorr/pajengr');" -- 2.20.1