From: Martin Quinson Date: Sat, 22 Jan 2022 15:33:23 +0000 (+0100) Subject: Further fixups and cosmetics in the doc X-Git-Tag: v3.30~57 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/c225312830f146ce85fcd8b48e705fbee707bcb0 Further fixups and cosmetics in the doc --- diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst index 08c454eb1d..0594693ee8 100644 --- a/docs/source/Plugins.rst +++ b/docs/source/Plugins.rst @@ -69,48 +69,48 @@ kind of objects, please let us now. Partial list of existing signals in s4u: -- :cpp:member:`Actor::on_creation ` - :cpp:member:`Actor::on_suspend ` - :cpp:member:`Actor::on_resume ` - :cpp:member:`Actor::on_sleep ` - :cpp:member:`Actor::on_wake_up ` - :cpp:member:`Actor::on_host_change ` - :cpp:member:`Actor::on_termination ` - :cpp:member:`Actor::on_destruction ` -- :cpp:member:`Comm::on_send ` - :cpp:member:`Comm::on_recv ` - :cpp:member:`Comm::on_completion ` -- :cpp:member:`CommImpl::on_start ` - :cpp:member:`CommImpl::on_completion ` -- :cpp:member:`Disk::on_creation ` - :cpp:member:`Disk::on_destruction ` - :cpp:member:`Disk::on_state_change ` -- :cpp:member:`Engine::on_platform_creation ` - :cpp:member:`Engine::on_platform_created ` - :cpp:member:`Engine::on_time_advance ` - :cpp:member:`Engine::on_simulation_end ` - :cpp:member:`Engine::on_deadlock ` -- :cpp:member:`Exec::on_start ` - :cpp:member:`Exec::on_completion ` -- :cpp:member:`Host::on_creation ` - :cpp:member:`Host::on_destruction ` - :cpp:member:`Host::on_state_change ` - :cpp:member:`Host::on_speed_change ` -- :cpp:member:`Io::on_start ` - :cpp:member:`Io::on_completion ` -- :cpp:member:`Link::on_creation ` - :cpp:member:`Link::on_destruction ` - :cpp:member:`Link::on_state_change ` - :cpp:member:`Link::on_speed_change ` - :cpp:member:`Link::on_communication_state_change ` -- :cpp:member:`NetZone::on_creation ` - :cpp:member:`NetZone::on_seal ` -- :cpp:member:`VirtualMachine::on_start ` - :cpp:member:`VirtualMachine::on_started ` - :cpp:member:`VirtualMachine::on_suspend ` - :cpp:member:`VirtualMachine::on_resume ` - :cpp:member:`VirtualMachine::on_migration_start ` - :cpp:member:`VirtualMachine::on_migration_end ` +- :cpp:func:`Actor::on_creation ` + :cpp:func:`Actor::on_suspend ` + :cpp:func:`Actor::on_resume ` + :cpp:func:`Actor::on_sleep ` + :cpp:func:`Actor::on_wake_up ` + :cpp:func:`Actor::on_host_change ` + :cpp:func:`Actor::on_termination ` + :cpp:func:`Actor::on_destruction ` +- :cpp:func:`Comm::on_send ` + :cpp:func:`Comm::on_recv ` + :cpp:func:`Comm::on_completion ` +- :cpp:func:`CommImpl::on_start ` + :cpp:func:`CommImpl::on_completion ` +- :cpp:func:`Disk::on_creation ` + :cpp:func:`Disk::on_destruction ` + :cpp:func:`Disk::on_state_change ` +- :cpp:func:`Engine::on_platform_creation ` + :cpp:func:`Engine::on_platform_created ` + :cpp:func:`Engine::on_time_advance ` + :cpp:func:`Engine::on_simulation_end ` + :cpp:func:`Engine::on_deadlock ` +- :cpp:func:`Exec::on_start ` + :cpp:func:`Exec::on_completion ` +- :cpp:func:`Host::on_creation ` + :cpp:func:`Host::on_destruction ` + :cpp:func:`Host::on_state_change ` + :cpp:func:`Host::on_speed_change ` +- :cpp:func:`Io::on_start ` + :cpp:func:`Io::on_completion ` +- :cpp:func:`Link::on_creation ` + :cpp:func:`Link::on_destruction ` + :cpp:func:`Link::on_state_change ` + :cpp:func:`Link::on_speed_change ` + :cpp:func:`Link::on_communication_state_change ` +- :cpp:func:`NetZone::on_creation ` + :cpp:func:`NetZone::on_seal ` +- :cpp:func:`VirtualMachine::on_start ` + :cpp:func:`VirtualMachine::on_started ` + :cpp:func:`VirtualMachine::on_suspend ` + :cpp:func:`VirtualMachine::on_resume ` + :cpp:func:`VirtualMachine::on_migration_start ` + :cpp:func:`VirtualMachine::on_migration_end ` Existing Plugins **************** diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst index 9ec483466f..d5b6d8b3aa 100644 --- a/docs/source/Tutorial_Algorithms.rst +++ b/docs/source/Tutorial_Algorithms.rst @@ -563,7 +563,7 @@ It produces a ``Rplots.pdf`` with the following content: Lab 1: Simpler deployments -------------------------- -.. rst-class:: learning-goals +.. rst-class:: compact-list **Learning goals:** @@ -647,7 +647,7 @@ for more details. Lab 2: Using the Whole Platform ------------------------------- -.. rst-class:: learning-goals +.. rst-class:: compact-list **Learning goals:** @@ -765,7 +765,7 @@ separation of concerns between things of different nature. Lab 3: Fixed Experiment Duration -------------------------------- -.. rst-class:: learning-goals +.. rst-class:: compact-list **Learning goals:** @@ -812,7 +812,7 @@ default. You can still see the debug messages as follows: Lab 4: What-if analysis ----------------------- -.. rst-class:: learning-goals +.. rst-class:: compact-list **Learning goals:** @@ -878,7 +878,7 @@ Again, there is a nice example demoing this feature, :ref:`under platform-failur Lab 5: Competing Applications ----------------------------- -.. rst-class:: learning-goals +.. rst-class:: compact-list **Learning goals:** diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index d438d656f9..5be35b340d 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -5,18 +5,18 @@ object#TOC { div[itemprop="articleBody"] { word-wrap: break-word; } -ul.learning-goals { +ul.compact-list { line-height: 80%; margin-left: 2em; padding: 0.2em; margin-bottom: 1em; } -ul.learning-goals li { +ul.compact-list li { list-style: disc; } -ul.learning-goals li p { +ul.compact-list li p { margin-bottom: 0; } -p.learning-goals { +p.compact-list { margin-bottom: 0; } diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index b98b49a341..117b85d8e4 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -64,45 +64,34 @@ Virtual machines can also be migrated between hosts. The :ref:`simgrid::s4u::this_actor ` namespace provides many helper functions to simplify the code of actors. -- **Simulation Elements** - - - :ref:`class Actor `: - Active entities executing your application. - - :ref:`class Engine ` - Simulation engine (singleton). - - :ref:`class Mailbox ` - Communication rendezvous, with which actors meet each other. - -- **Resources** - - - :ref:`class Disk ` - Resource on which actors can write and read data. - - :ref:`class Host `: - Actor location, providing computational power. - - :ref:`class Link ` - Interconnecting hosts. - - :ref:`class NetZone `: - Sub-region of the platform, containing resources (Hosts, Links, etc). - - :ref:`class VirtualMachine `: - Execution containers that can be moved between Hosts. - -- **Activities** (:ref:`class Activity `): - The things that actors can do on resources - - - :ref:`class Comm ` - Communication activity, started on Mailboxes and consuming links. - - :ref:`class Exec ` - Computation activity, started on Host and consuming CPU resources. - - :ref:`class Io ` - I/O activity, started on and consuming disks. - -- **Synchronization Objects**: Classical IPC that actors can use - - - :ref:`class Barrier ` - - :ref:`class ConditionVariable ` - - :ref:`class Mutex ` - - :ref:`class Semaphore ` +.. rst-class:: compact-list + - **Simulation Elements** + + - :ref:`class Actor `: Active entities executing your application. + - :ref:`class Engine `: Simulation engine (singleton). + - :ref:`class Mailbox `: Communication rendezvous, with which actors meet each other. + + - **Resources** + + - :ref:`class Disk `: Resource on which actors can write and read data. + - :ref:`class Host `: Actor location, providing computational power. + - :ref:`class Link `: Interconnecting hosts. + - :ref:`class NetZone `: Sub-region of the platform, containing resources (Hosts, Links, etc). + - :ref:`class VirtualMachine `: Execution containers that can be moved between Hosts. + + - **Activities** (:ref:`class Activity `): The things that actors can do on resources. + + - :ref:`class Comm `: Communication activity, started on Mailboxes and consuming links. + - :ref:`class Exec `: Computation activity, started on Host and consuming CPU resources. + - :ref:`class Io `: I/O activity, started on and consuming disks. + + - **Synchronization Objects**: Classical IPC that actors can use + + - :ref:`class Barrier ` + - :ref:`class ConditionVariable ` + - :ref:`class Mutex ` + - :ref:`class Semaphore ` .. |API_s4u_Actors| replace:: **Actors** .. _API_s4u_Actors: #api-s4u-actor @@ -169,18 +158,14 @@ use :cpp:func:`s4u::Activity::wait_for() `. Finally, to wait at most until a specified time limit, use :cpp:func:`s4u::Activity::wait_until() `. -Every kind of activity can be asynchronous: - - - :ref:`s4u::CommPtr ` are created with - :cpp:func:`s4u::Mailbox::put_async() ` and - :cpp:func:`s4u::Mailbox::get_async() `. - - :ref:`s4u::IoPtr ` are created with - :cpp:func:`s4u::Disk::read_async() ` and - :cpp:func:`s4u::Disk::write_async() `. - - :ref:`s4u::ExecPtr ` are created with - :cpp:func:`s4u::Host::exec_async() `. - - In the future, it will become possible to have asynchronous IPC - such as asynchronous mutex lock requests. +Every kind of activity can be asynchronous. +:ref:`s4u::CommPtr ` are created with :cpp:func:`s4u::Mailbox::put_async() ` and +:cpp:func:`s4u::Mailbox::get_async() `; +:ref:`s4u::IoPtr ` are created with :cpp:func:`s4u::Disk::read_async() ` and +:cpp:func:`s4u::Disk::write_async() `; and +:ref:`s4u::ExecPtr ` are created with +:cpp:func:`s4u::Host::exec_async() `. +In the future, it will become possible to have asynchronous IPC such as asynchronous mutex lock requests. The following example shows how to have several concurrent communications ongoing. First, you have to declare a vector in which @@ -191,20 +176,18 @@ vector of mailboxes. :language: c++ :start-after: init-begin :end-before: init-end - :dedent: 4 + :dedent: 2 Then, you start all the communications that should occur concurrently with :cpp:func:`s4u::Mailbox::put_async() `. Finally, the actor waits for the completion of all of them at once -with -:cpp:func:`s4u::Comm::wait_all() `. +with :cpp:func:`s4u::Comm::wait_all() `. .. literalinclude:: ../../examples/cpp/comm-waitall/s4u-comm-waitall.cpp :language: c++ :start-after: put-begin :end-before: put-end - :dedent: 4 - + :dedent: 2 ===================== Activities Life cycle @@ -632,14 +615,14 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Actor::on_creation - .. doxygenvariable:: simgrid::s4u::Actor::on_suspend - .. doxygenvariable:: simgrid::s4u::Actor::on_host_change - .. doxygenvariable:: simgrid::s4u::Actor::on_resume - .. doxygenvariable:: simgrid::s4u::Actor::on_sleep - .. doxygenvariable:: simgrid::s4u::Actor::on_wake_up - .. doxygenvariable:: simgrid::s4u::Actor::on_termination - .. doxygenvariable:: simgrid::s4u::Actor::on_destruction + .. doxygenfunction:: simgrid::s4u::Actor::on_creation_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_suspend_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_host_change_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_resume_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_sleep_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_wake_up_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_termination_cb + .. doxygenfunction:: simgrid::s4u::Actor::on_destruction_cb .. _API_s4u_this_actor: @@ -1202,9 +1185,9 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Disk::on_creation - .. doxygenvariable:: simgrid::s4u::Disk::on_destruction - .. doxygenvariable:: simgrid::s4u::Disk::on_state_change + .. doxygenfunction:: simgrid::s4u::Disk::on_creation_cb + .. doxygenfunction:: simgrid::s4u::Disk::on_destruction_cb + .. doxygenfunction:: simgrid::s4u::Disk::on_state_change_cb .. _API_s4u_Host: @@ -1999,15 +1982,15 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_creation - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_destruction - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_migration_end - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_migration_start - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_resume - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_shutdown - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_start - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_started - .. doxygenvariable:: simgrid::s4u::VirtualMachine::on_suspend + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_creation_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_destruction_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_end_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_start_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_resume_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_shutdown_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_start_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_started_cb + .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_suspend_cb .. _API_s4u_Activity: @@ -2192,6 +2175,7 @@ Signals .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Comm::on_start_cb .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb @@ -2376,6 +2360,16 @@ Life cycle .. automethod:: simgrid.Io.wait_any_for .. automethod:: simgrid.Io.wait_any +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Io::on_start_cb + .. doxygenfunction:: simgrid::s4u::Io::on_completion_cb + .. _API_s4u_Synchronizations: ======================= diff --git a/examples/README.rst b/examples/README.rst index 8645aff881..7d6dc0b499 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -86,8 +86,8 @@ actors. This example shows how to attach a callback to: - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()` - - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()` - - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()` + - the end of any actor: :cpp:func:`simgrid::s4u::Actor::on_termination_cb` + - the destruction of any actor: :cpp:func:`simgrid::s4u::Actor::on_destruction_cb` .. example-tab:: examples/c/actor-exiting/actor-exiting.c diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 9e253158f4..017a8a71fd 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -240,7 +240,7 @@ public: /** Add a callback fired when an actor terminates its code. * @beginrst * The actor may continue to exist if it is still referenced in the simulation, but it's not active anymore. - * If you want to free extra data when the actor's destructor is called, use :cpp:var:`Actor::on_destruction`. + * If you want to free extra data when the actor's destructor is called, use :cpp:func:`Actor::on_destruction_cb`. * If you want to register to the termination of a given actor, use :cpp:func:`this_actor::on_exit()` instead. * @endrst */ diff --git a/include/simgrid/s4u/Io.hpp b/include/simgrid/s4u/Io.hpp index c3bb33c539..c3118c357d 100644 --- a/include/simgrid/s4u/Io.hpp +++ b/include/simgrid/s4u/Io.hpp @@ -25,13 +25,15 @@ class XBT_PUBLIC Io : public Activity_T { friend kernel::EngineImpl; #endif + static xbt::signal on_start; + protected: explicit Io(kernel::activity::IoImplPtr pimpl); public: enum class OpType { READ, WRITE }; - static xbt::signal on_start; + static void on_start_cb(const std::function& cb) { on_start.connect(cb); } static IoPtr init(); Io* start() override; diff --git a/src/plugins/host_load.cpp b/src/plugins/host_load.cpp index 61a67f4533..3484d05f69 100644 --- a/src/plugins/host_load.cpp +++ b/src/plugins/host_load.cpp @@ -21,12 +21,12 @@ SIMGRID_REGISTER_PLUGIN(host_load, "Cpu load", &sg_host_load_plugin_init) In addition, this constitutes a good introductory example on how to write a plugin. It attaches an extension to each host to store some data, and places callbacks in the following signals: - - :cpp:member:`simgrid::s4u::Host::on_creation`: Attach a new extension to the newly created host. - - :cpp:member:`simgrid::s4u::Exec::on_start`: Make note that a new execution started, increasing the load. - - :cpp:member:`simgrid::s4u::Exec::on_completion`: Make note that an execution completed, decreasing the load. - - :cpp:member:`simgrid::s4u::Host::on_state_change`: Do what is appropriate when the host gets suspended, turned off + - :cpp:func:`simgrid::s4u::Host::on_creation_cb`: Attach a new extension to the newly created host. + - :cpp:func:`simgrid::s4u::Exec::on_start_cb`: Make note that a new execution started, increasing the load. + - :cpp:func:`simgrid::s4u::Exec::on_completion_cb`: Make note that an execution completed, decreasing the load. + - :cpp:func:`simgrid::s4u::Host::on_state_change_cb`: Do what is appropriate when the host gets suspended, turned off or similar. - - :cpp:member:`simgrid::s4u::Host::on_speed_change`: Do what is appropriate when the DVFS is modified. + - :cpp:func:`simgrid::s4u::Host::on_speed_change_cb`: Do what is appropriate when the DVFS is modified. Note that extensions are automatically destroyed when the host gets destroyed. @endrst