X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/6c1487ed9411709f547ffb549cd21a6fb7b0aab2..8094530954d92c511f27c2647d9f15791a404734:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index a3c853cf79..74fb609f32 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -5,11 +5,11 @@ The S4U Interface .. raw:: html - +
@@ -20,7 +20,7 @@ with the full power of C++. This is the preferred interface to describe abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar settings. -Currently (v3.21), S4U is definitely the way to go for long-term +Since v3.20 (June 2018), S4U is definitely the way to go for long-term projects. It is feature complete, but may still evolve slightly in the future releases. It can already be used to do everything that can be done in SimGrid, but you may have to adapt your code in future @@ -28,7 +28,7 @@ releases. When this happens, compiling your code will produce deprecation warnings for 4 releases (one year) before the removal of the old symbols. If you want an API that will never ever evolve in the future, you -should use the deprecated MSG API instead. +should use the :ref:`deprecated MSG API ` instead. Main Concepts ************* @@ -39,7 +39,7 @@ S4U interface to express their :ref:`computation `, :ref:`communication `, :ref:`disk usage `, and other |API_s4u_Activities|_, so that they get reflected within the simulator. These activities take place on resources such as |API_s4u_Hosts|_, -|API_s4u_Links|_ and |API_s4u_Storages|_. SimGrid predicts the time taken by each +|API_s4u_Links|_ and |API_s4u_Disks|_. SimGrid predicts the time taken by each activity and orchestrates the actors accordingly, waiting for the completion of these activities. @@ -56,7 +56,10 @@ synchronization mechanisms** such as |API_s4u_Barrier|_, |API_s4u_Semaphore|_, Each actor is located on a simulated |API_s4u_Host|_. Each host is located itself in a |API_s4u_NetZone|_, that knows the networking path between one resource to another. Each NetZone is included in another one, forming -a tree of NetZones which root zone contains the whole platform. +a tree of NetZones which root zone contains the whole platform. The +actors can also be located on a |API_s4U_VirtualMachine|_ that may +restrict the activities it contains to a limited amount of cores. +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. @@ -72,14 +75,14 @@ provides many helper functions to simplify the code of actors. - **Platform Elements** + - :ref:`class s4u::Disk ` + Resource on which actors can write and read data. - :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, Links, 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. @@ -91,7 +94,7 @@ provides many helper functions to simplify the code of actors. - :ref:`class s4u::Exec ` Computation activity, started on Host and consuming CPU resources. - :ref:`class s4u::Io ` - I/O activity, started on and consumming Storages. + I/O activity, started on and consumming disks. - **Synchronization Mechanisms**: Classical IPC that actors can use @@ -113,11 +116,10 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Links| replace:: **Links** .. _API_s4u_Links: #s4u-link -.. |API_s4u_Storages| replace:: **Storages** -.. _API_s4u_Storages: #s4u-storage +.. |API_s4u_Disks| replace:: **Disks** +.. _API_s4u_Disks: #s4u-disk -.. |API_s4u_VirtualMachines| replace:: **VirtualMachines** -.. _API_s4u_VirtualMachines: #s4u-virtualmachine +.. |API_s4u_VirtualMachine| replace:: **VirtualMachines** .. |API_s4u_Host| replace:: **Host** @@ -136,15 +138,11 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Mutex| replace:: **Mutex** -.. THE EXAMPLES - -.. include:: ../../examples/s4u/README.rst - Activities ********** Activities represent the actions that consume a resource, such as a -:ref:`s4u::Comm ` that consumes the *transmiting power* of +:ref:`s4u::Comm ` that consumes the *transmitting power* of :ref:`s4u::Link ` resources. ======================= @@ -171,14 +169,14 @@ Finally, to wait at most until a specified time limit, use wait_for and wait_until are currently not implemented for Exec and Io activities. -Every kind of activities can be asynchronous: +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::Storage::read_async() ` and - :cpp:func:`s4u::Storage::write_async() `. + :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 @@ -298,7 +296,7 @@ balancing for free if more than one actor pulls from the mailbox: the first actor that can deal with the request will handle it. ========================================= -How put() and get() Requests are Matched? +How are put() and get() requests matched? ========================================= The matching algorithm simple: first come, first serve. When a new @@ -315,9 +313,9 @@ Declaring a Receiving Actor The last twist is that by default in the simulator, the data starts to be exchanged only when both the sender and the receiver are -declared (it waits until both :cpp:func:`put() ` +announced (it waits until both :cpp:func:`put() ` and :cpp:func:`get() ` are posted). -In TCP, since you establish connexions beforehand, the data starts to +In TCP, since you establish connections beforehand, the data starts to flow as soon as the sender posts it, even if the receiver did not post its :cpp:func:`recv() ` yet. @@ -329,19 +327,25 @@ posted to that mailbox will start as soon as possible, and the data will already be there on the receiver host when the receiver actor posts its :cpp:func:`get() ` +Note that being permanent receivers of a mailbox prevents actors to be +garbage-collected. If your simulation creates many short-lived actors +that marked as permanent receiver, you should call +``mailbox->set_receiver(nullptr)`` by the end of the actors so that their +memory gets properly reclaimed. This call should be at the end of the +actor's function, not in a on_exit callback. + Memory Management ***************** For sake of simplicity, we use `RAII `_ -everywhere in S4U. This is an idiom where resources are automatically +for many classes in S4U. This is an idiom where resources are automatically managed through the context. Provided that you never manipulate objects of type Foo directly but always FooPtr references (which are defined as `boost::intrusive_ptr `_ -), you will never have to explicitely release the resource that +), you will never have to explicitly release the resource that you use nor to free the memory of unused objects. - Here is a little example: .. code-block:: cpp @@ -356,9 +360,28 @@ Here is a little example: } // The mutex gets automatically freed because the only existing reference gets out of scope +Note that Mailboxes, Hosts and Links are not handled thought smart +pointers (yet?). This means that it is currently impossible to destroy a +mailbox or a link. You can still destroy an host (but probably +shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`. + +.. THE EXAMPLES + +.. include:: ../../examples/README.rst + API Reference ************* +.. _API_s4u_this_actor: + +================================== +Interacting with the current actor +================================== + +Static methods working on the current actor (see :ref:`API_s4u_Actor`). + +.. doxygennamespace:: simgrid::s4u::this_actor + .. _API_s4u_Activity: ============= @@ -372,16 +395,153 @@ s4u::Activity .. _API_s4u_Actor: -========== -s4u::Actor -========== +=========== +class Actor +=========== .. doxygentypedef:: ActorPtr -.. doxygenclass:: simgrid::s4u::Actor - :members: - :protected-members: - :undoc-members: +.. doxygentypedef:: aid_t + +.. autodoxyclass:: simgrid::s4u::Actor + +Creating actors +--------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args) + .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector< std::string > args) + + .. autodoxymethod:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host) + .. autodoxymethod:: simgrid::s4u::Actor::start(const std::function< void()> &code) + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.create + +Searching specific actors +------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::by_pid(aid_t pid) + .. autodoxymethod:: simgrid::s4u::Actor::self() + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.by_pid + .. automethod:: simgrid.Actor.self + +Querying info about actors +-------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::get_cname + .. autodoxymethod:: simgrid::s4u::Actor::get_name + .. autodoxymethod:: simgrid::s4u::Actor::get_pid + .. autodoxymethod:: simgrid::s4u::Actor::get_ppid + .. autodoxymethod:: simgrid::s4u::Actor::get_properties() const + .. autodoxymethod:: simgrid::s4u::Actor::get_property(const std::string &key) const + .. autodoxymethod:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value) + + .. autodoxymethod:: simgrid::s4u::Actor::get_host + .. autodoxymethod:: simgrid::s4u::Actor::migrate + + .. autodoxymethod:: simgrid::s4u::Actor::get_refcount() + .. autodoxymethod:: simgrid::s4u::Actor::get_impl() + + .. group-tab:: Python + + .. autoattribute:: simgrid.Actor.name + .. autoattribute:: simgrid.Actor.host + .. autoattribute:: simgrid.Actor.pid + .. autoattribute:: simgrid.Actor.ppid + + .. automethod:: simgrid.Actor.migrate + +Suspending and resuming actors +------------------------------ + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::suspend() + .. autodoxymethod:: simgrid::s4u::Actor::resume() + .. autodoxymethod:: simgrid::s4u::Actor::is_suspended() + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.resume + .. automethod:: simgrid.Actor.suspend + .. automethod:: simgrid.Actor.is_suspended + +Killing actors +-------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::kill() + .. autodoxymethod:: simgrid::s4u::Actor::kill_all() + .. autodoxymethod:: simgrid::s4u::Actor::set_kill_time(double time) + .. autodoxymethod:: simgrid::s4u::Actor::get_kill_time() + + .. autodoxymethod:: simgrid::s4u::Actor::restart() + .. autodoxymethod:: simgrid::s4u::Actor::daemonize() + .. autodoxymethod:: simgrid::s4u::Actor::is_daemon + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.kill + .. automethod:: simgrid.Actor.kill_all + + .. automethod:: simgrid.Actor.daemonize + .. automethod:: simgrid.Actor.is_daemon + +Reacting to the end of actors +----------------------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Actor::on_exit(const std::function< void(bool)> &fun) + .. autodoxymethod:: simgrid::s4u::Actor::join() + .. autodoxymethod:: simgrid::s4u::Actor::join(double timeout) + .. autodoxymethod:: simgrid::s4u::Actor::set_auto_restart(bool autorestart) + + .. group-tab:: Python + + .. automethod:: simgrid.Actor.join + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Actor::on_creation + .. autodoxyvar:: simgrid::s4u::Actor::on_suspend + .. autodoxyvar:: simgrid::s4u::Actor::on_resume + .. autodoxyvar:: simgrid::s4u::Actor::on_sleep + .. autodoxyvar:: simgrid::s4u::Actor::on_wake_up + .. autodoxyvar:: simgrid::s4u::Actor::on_migration_start + .. autodoxyvar:: simgrid::s4u::Actor::on_migration_end + .. autodoxyvar:: simgrid::s4u::Actor::on_termination + .. autodoxyvar:: simgrid::s4u::Actor::on_destruction .. _API_s4u_Barrier: @@ -422,6 +582,17 @@ s4u::ConditionVariable :protected-members: :undoc-members: +.. _API_s4u_Disk: + +============ +s4u::Disk +============ + +.. doxygenclass:: simgrid::s4u::Disk + :members: + :protected-members: + :undoc-members: + .. _API_s4u_Engine: =========== @@ -446,6 +617,32 @@ s4u::Exec :protected-members: :undoc-members: +.. _API_s4u_ExecSeq: + +============ +s4u::ExecSeq +============ + +.. doxygentypedef:: ExecSeqPtr + +.. doxygenclass:: simgrid::s4u::ExecSeq + :members: + :protected-members: + :undoc-members: + +.. _API_s4u_ExecPar: + +============ +s4u::ExecPar +============ + +.. doxygentypedef:: ExecParPtr + +.. doxygenclass:: simgrid::s4u::ExecPar + :members: + :protected-members: + :undoc-members: + .. _API_s4u_Host: ========= @@ -489,8 +686,6 @@ s4u::Mailbox Please also refer to the :ref:`full doc on s4u::Mailbox `. -.. doxygentypedef:: MailboxPtr - .. doxygenclass:: simgrid::s4u::Mailbox :members: :protected-members: @@ -533,17 +728,6 @@ s4u::Semaphore :protected-members: :undoc-members: -.. _API_s4u_Storage: - -============ -s4u::Storage -============ - -.. doxygenclass:: simgrid::s4u::Storage - :members: - :protected-members: - :undoc-members: - .. _API_s4u_VirtualMachine: =================== @@ -555,11 +739,88 @@ s4u::VirtualMachine :protected-members: :undoc-members: -.. _API_s4u_this_actor: +C API Reference +*************** -========================= -namespace s4u::this_actor -========================= +============== +Main functions +============== +.. doxygenfunction:: simgrid_init +.. doxygenfunction:: simgrid_get_clock +.. doxygenfunction:: simgrid_load_deployment +.. doxygenfunction:: simgrid_load_platform +.. doxygenfunction:: simgrid_register_default +.. doxygenfunction:: simgrid_register_function +.. doxygenfunction:: simgrid_run -.. doxygennamespace:: simgrid::s4u::this_actor +================== +Condition Variable +================== + +See also the :ref:`C++ API `. + +.. doxygenfunction:: sg_cond_init +.. doxygenfunction:: sg_cond_notify_all +.. doxygenfunction:: sg_cond_notify_one +.. doxygenfunction:: sg_cond_wait +.. doxygenfunction:: sg_cond_wait_for + +Python API Reference +******************** + +The Python API is automatically generated with pybind11. It closely mimicks the C++ +API, to which you should refer for more information. + +========== +this_actor +========== + +.. automodule:: simgrid.this_actor + :members: + +=========== +Class Actor +=========== + +.. autoclass:: simgrid.Actor + :members: + +========== +Class Comm +========== + +.. autoclass:: simgrid.Comm + :members: + +============ +Class Engine +============ + +.. autoclass:: simgrid.Engine + :members: + +========== +Class Exec +========== + +.. autoclass:: simgrid.Exec + :members: + +========== +Class Host +========== + +.. autoclass:: simgrid.Host + :members: + +============= +Class Mailbox +============= + +.. autoclass:: simgrid.Mailbox + :members: + +.. |hr| raw:: html + +