From a52d0511bbb8a3de2d2d9a808f1118c1f323244a Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Fri, 24 Aug 2018 01:39:10 +0200 Subject: [PATCH] doc s4u: finish the 'Main Concepts' section --- docs/source/application.rst | 84 +++++++++++++++++++++++++++------ include/simgrid/s4u/Storage.hpp | 6 ++- 2 files changed, 74 insertions(+), 16 deletions(-) diff --git a/docs/source/application.rst b/docs/source/application.rst index c3555f21b2..40686073f9 100644 --- a/docs/source/application.rst +++ b/docs/source/application.rst @@ -36,24 +36,75 @@ Main Concepts A typical SimGrid simulation is composed of several |Actors|_, that execute user-provided functions. The actors have to explicitly use the -S4U interface to express their computation, communication, disk usage +S4U interface to express their +:ref:`computation `, +:ref:`communication `, +:ref:`disk usage `, and other |Activities|_, so that they get reflected within the -simulator. These activities take place on resources: |Hosts|_, -|Links|_, |Storages|_ and |VirtualMachines|_. SimGrid predicts the -time taken by each activity and orchestrates accordingly the actors -waiting for the completion of these activities. +simulator. These activities take place on resources such as |Hosts|_, +|Links|_ and |Storages|_. SimGrid predicts the time taken by each +activity and orchestrates accordingly the actors waiting for the +completion of these activities. + + +When **communicating**, data is not directly sent to other actors but +posted onto a |Mailbox|_ that serve as rendez-vous point between +communicating actors. This means that you don't need to know who you +are talking to, you just put your communication `Send` request in a +mailbox, and it will be matched with a complementary `Receive` +request. Alternatively, actors can interact through **classical +synchronization mechanisms** such as |Barrier|_, |Semaphore|_, +|Mutex|_ and |ConditionVariable|_. + +Each actor is located on a simulated |Host|_. Each host is located +itself in a |NetZone|_, that route communications through the +links. Each NetZone is included in another one, forming a tree of +NetZones which root zone contains the whole platform. + +The :ref:`simgrid::s4u::this_actor +` namespace provides many helper +functions to simplify the code of actors. + +- **Global Classes** + + - :ref:`class s4u::Actor `: + Active entities executing your application. + - :ref:`class s4u::Engine ` + Simulation engine (singleton). + - :ref:`class s4u::Mailbox ` + Communication rendez-vous. + +- **Platform Elements** + + - :ref:`class s4u::Host `: + Actor location, providing computational power. + - :ref:`class s4u::Link ` + Interconnecting hosts. + - :ref:`class s4u::NetZone `: + Sub-region of the platform, containing resources (Hosts, Link, etc). + - :ref:`class s4u::Storage ` + Resource on which actors can write and read data. + - :ref:`class s4u::VirtualMachine `: + Execution containers that can be moved between Hosts. + +- **Activities** (:ref:`class s4u::Activity `): + The things that actors can do on resources + + - :ref:`class s4u::Comm ` + Communication activity, started on Mailboxes and consuming links. + - :ref:`class s4u::Exec ` + Computation activity, started on Host and consuming CPU resources. + - :ref:`class s4u::Io ` + I/O activities, started on and consumming Storages. + +- **Synchronization Mechanisms**: Classical IPC that actors can use + + - :ref:`class s4u::Barrier ` + - :ref:`class s4u::ConditionVariable ` + - :ref:`class s4u::Mutex ` + - :ref:`class s4u::Semaphore ` -Each actor executes a user-provided function on a simulated |Host|_, -with which it can interact using the :ref:`simgrid::s4u::this_actor -` namespace. **Communications** -are not directly sent to actors, but posted onto a |Mailbox|_ that -serve as rendez-vous point between communicating actors. Actors can -also interact through **classical synchronization mechanisms** such as -|Barrier|_, |Semaphore|_, |Mutex|_ and |ConditionVariable|_. - -.. todo:: Add NetZone - .. |Actors| replace:: **Actors** .. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html @@ -78,6 +129,9 @@ also interact through **classical synchronization mechanisms** such as .. |Mailbox| replace:: **Mailbox** .. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html +.. |NetZone| replace:: **NetZone** +.. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html + .. |Barrier| replace:: **Barrier** .. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html diff --git a/include/simgrid/s4u/Storage.hpp b/include/simgrid/s4u/Storage.hpp index b6ec31fd4c..2f5f89d34d 100644 --- a/include/simgrid/s4u/Storage.hpp +++ b/include/simgrid/s4u/Storage.hpp @@ -24,7 +24,11 @@ namespace s4u { XBT_ATTRIB_DEPRECATED_v322("Please use Engine::get_all_storages()") XBT_PUBLIC void getStorageList(std::map* whereTo); #endif -/** Storage represent the disk resources, usually associated to a given host */ +/** Storage represent the disk resources, usually associated to a given host + * + * By default, SimGrid does not keep track of the actual data being written but + * only computes the time taken by the corresponding data movement. + */ class XBT_PUBLIC Storage : public simgrid::xbt::Extendable { friend simgrid::s4u::Engine; -- 2.20.1