document Virtual machines

[simgrid.git] / docs / source / app_s4u.rst

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index f66286e..8123177 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -1080,6 +1080,8 @@ Basic management
       idiom on hosts because SimGrid does not allow (yet) to create nor
       destroy resources once the simulation is started. 
 
       idiom on hosts because SimGrid does not allow (yet) to create nor
       destroy resources once the simulation is started. 
 

+      .. autodoxymethod:: simgrid::s4u::Host::destroy()
+

    .. group-tab:: Python
 
       .. code:: Python
    .. group-tab:: Python
 
       .. code:: Python


@@ -1133,18 +1135,79 @@ Querying info
 
       .. autodoxymethod:: simgrid::s4u::Host::get_cname()
       .. autodoxymethod:: simgrid::s4u::Host::get_core_count()
 
       .. autodoxymethod:: simgrid::s4u::Host::get_cname()
       .. autodoxymethod:: simgrid::s4u::Host::get_core_count()

-      .. autodoxymethod:: simgrid::s4u::Host::get_disks()

       .. autodoxymethod:: simgrid::s4u::Host::get_name()
       .. autodoxymethod:: simgrid::s4u::Host::get_name()

+      .. autodoxymethod:: simgrid::s4u::Host::get_available_speed()
+      .. autodoxymethod:: simgrid::s4u::Host::get_load()
+      .. autodoxymethod:: simgrid::s4u::Host::get_speed()

 
    .. group-tab:: Python
 
 
    .. group-tab:: Python
 

-      .. autoattribute:: simgrid.Exec.host

       .. autoattribute:: simgrid.Host.name
       .. autoattribute:: simgrid.Host.name

+      .. autoattribute:: simgrid.Host.load
+      .. autoattribute:: simgrid.Host.pstate
+      .. autoattribute:: simgrid.Host.speed

 
    .. group-tab:: C
 
 
    .. group-tab:: C
 

-      .. autodoxymethod:: ::sg_host_core_count(const_sg_host_t host)
+      .. autodoxymethod:: sg_host_core_count(const_sg_host_t host)
+      .. autodoxymethod:: sg_host_dump(const_sg_host_t ws)

       .. autodoxymethod:: sg_host_get_name(const_sg_host_t host)
       .. autodoxymethod:: sg_host_get_name(const_sg_host_t host)

+      .. autodoxymethod:: sg_host_load(const_sg_host_t host)
+      .. autodoxymethod:: sg_host_speed(const_sg_host_t host)
+
+User data and properties
+------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Host::get_properties()
+      .. autodoxymethod:: simgrid::s4u::Host::get_property(const std::string &key)
+      .. autodoxymethod:: simgrid::s4u::Host::set_properties(const std::map< std::string, std::string > &properties)
+      .. autodoxymethod:: simgrid::s4u::Host::set_property(const std::string &key, const std::string &value)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_host_set_property_value(sg_host_t host, const char *name, const char *value)
+      .. autodoxymethod:: sg_host_get_properties(const_sg_host_t host)
+      .. autodoxymethod:: sg_host_get_property_value(const_sg_host_t host, const char *name)
+      .. autodoxymethod:: sg_host_extension_create(void(*deleter)(void *))
+      .. autodoxymethod:: sg_host_extension_get(const_sg_host_t host, size_t rank)
+
+Retrieving components
+---------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Host::add_disk(Disk *disk)
+      .. autodoxymethod:: simgrid::s4u::Host::get_actor_count()
+      .. autodoxymethod:: simgrid::s4u::Host::get_all_actors()
+      .. autodoxymethod:: simgrid::s4u::Host::get_disks()
+      .. autodoxymethod:: simgrid::s4u::Host::remove_disk(const std::string &disk_name)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_host_get_actor_list(const_sg_host_t host, xbt_dynar_t whereto)
+
+On/Off
+------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Host::is_on()
+      .. autodoxymethod:: simgrid::s4u::Host::turn_off()
+      .. autodoxymethod:: simgrid::s4u::Host::turn_on()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_host_is_on(const_sg_host_t host)
+      .. autodoxymethod:: sg_host_turn_off(sg_host_t host)
+      .. autodoxymethod:: sg_host_turn_on(sg_host_t host)

 
 DVFS
 ----
 
 DVFS
 ----


@@ -1173,10 +1236,48 @@ DVFS
       .. autodoxymethod:: sg_host_get_pstate_speed(const_sg_host_t host, int pstate_index)
       .. autodoxymethod:: sg_host_set_pstate(sg_host_t host, int pstate)
 
       .. autodoxymethod:: sg_host_get_pstate_speed(const_sg_host_t host, int pstate_index)
       .. autodoxymethod:: sg_host_set_pstate(sg_host_t host, int pstate)
 

-.. doxygenclass:: simgrid::s4u::Host
-   :members:
-   :protected-members:
-   :undoc-members:
+Execution
+---------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Host::exec_async(double flops_amounts)
+      .. autodoxymethod:: simgrid::s4u::Host::execute(double flops)
+      .. autodoxymethod:: simgrid::s4u::Host::execute(double flops, double priority)
+
+Platform and routing
+--------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Host::get_englobing_zone()
+      .. autodoxymethod:: simgrid::s4u::Host::get_netpoint()
+      .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency)
+      .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency)
+      .. autodoxymethod:: simgrid::s4u::Host::send_to(Host *dest, double byte_amount)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_host_route(const_sg_host_t from, const_sg_host_t to, xbt_dynar_t links)
+      .. autodoxymethod:: sg_host_route_bandwidth(const_sg_host_t from, const_sg_host_t to)
+      .. autodoxymethod:: sg_host_route_latency(const_sg_host_t from, const_sg_host_t to)
+      .. autodoxymethod:: sg_host_send_to(sg_host_t from, sg_host_t to, double byte_amount)
+
+Signals
+-------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxyvar:: simgrid::s4u::Host::on_creation
+      .. autodoxyvar:: simgrid::s4u::Host::on_destruction
+      .. autodoxyvar:: simgrid::s4u::Host::on_speed_change
+      .. autodoxyvar:: simgrid::s4u::Host::on_state_change

 
 .. _API_s4u_Link:
 
 
 .. _API_s4u_Link:
 


@@ -1184,10 +1285,132 @@ DVFS
 ⁣  class Link
 =============
 
 ⁣  class Link
 =============
 

-.. doxygenclass:: simgrid::s4u::Link
-   :members:
-   :protected-members:
-   :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Link
+
+Basic management
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. code-block:: C++
+
+         #include <simgrid/s4u/Link.hpp>
+
+      Note that there is no LinkPtr type, and that you cannot use the RAII
+      idiom on hosts because SimGrid does not allow (yet) to create nor
+      destroy resources once the simulation is started. 
+
+   .. group-tab:: Python
+
+      .. code:: Python
+
+         from simgrid import Link
+
+   .. group-tab:: C
+
+      .. code:: C
+
+         #include <simgrid/link.h>
+
+      .. doxygentypedef:: sg_link_t
+      .. cpp:type:: const s4u_Link* const_sg_link_t
+
+         Pointer to a constant link object.
+
+Retrieving links
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      See also :cpp:func:`simgrid::s4u::Engine::get_all_links`.
+
+      .. autodoxymethod:: simgrid::s4u::Link::by_name(const std::string &name)
+      .. autodoxymethod:: simgrid::s4u::Link::by_name_or_null(const std::string &name)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_link_by_name(const char *name)
+      .. autodoxymethod:: sg_link_count()
+      .. autodoxymethod:: sg_link_list()
+
+Querying info
+--------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Link::get_bandwidth()
+      .. autodoxymethod:: simgrid::s4u::Link::get_cname()
+      .. autodoxymethod:: simgrid::s4u::Link::get_latency()
+      .. autodoxymethod:: simgrid::s4u::Link::get_name()
+      .. autodoxymethod:: simgrid::s4u::Link::get_sharing_policy()
+      .. autodoxymethod:: simgrid::s4u::Link::get_usage()
+      .. autodoxymethod:: simgrid::s4u::Link::is_used()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_link_bandwidth(const_sg_link_t link)
+      .. autodoxymethod:: sg_link_is_shared(const_sg_link_t link)
+      .. autodoxymethod:: sg_link_latency(const_sg_link_t link)
+      .. autodoxymethod:: sg_link_name(const_sg_link_t link)
+
+User data and properties
+------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Link::get_property(const std::string &key)
+      .. autodoxymethod:: simgrid::s4u::Link::set_property(const std::string &key, const std::string &value)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_link_data(const_sg_link_t link)
+      .. autodoxymethod:: sg_link_data_set(sg_link_t link, void *data)
+
+On/Off
+------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      See also :cpp:func:`simgrid::s4u::Link::set_state_profile`.
+
+      .. autodoxymethod:: simgrid::s4u::Link::is_on()
+      .. autodoxymethod:: simgrid::s4u::Link::turn_off()
+      .. autodoxymethod:: simgrid::s4u::Link::turn_on()
+
+Dynamic profiles
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Link::set_bandwidth_profile(kernel::profile::Profile *profile)
+      .. autodoxymethod:: simgrid::s4u::Link::set_latency_profile(kernel::profile::Profile *profile)
+      .. autodoxymethod:: simgrid::s4u::Link::set_state_profile(kernel::profile::Profile *profile)
+
+Signals
+-------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxyvar:: simgrid::s4u::Link::on_bandwidth_change
+      .. cpp:var:: xbt::signal<void(kernel::resource::NetworkAction&, Host* src, Host* dst)> Link::on_communicate
+      .. autodoxyvar:: simgrid::s4u::Link::on_communication_state_change
+      .. autodoxyvar:: simgrid::s4u::Link::on_creation
+      .. autodoxyvar:: simgrid::s4u::Link::on_destruction
+      .. autodoxyvar:: simgrid::s4u::Link::on_state_change

 
 .. _API_s4u_NetZone:
 
 
 .. _API_s4u_NetZone:
 


@@ -1195,6 +1418,123 @@ DVFS
 ⁣  class NetZone
 ================
 
 ⁣  class NetZone
 ================
 

+.. autodoxyclass:: simgrid::s4u::NetZone
+
+Basic management
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. code-block:: C++
+
+         #include <simgrid/s4u/NetZone.hpp>
+
+      Note that there is no NetZonePtr type, and that you cannot use the RAII
+      idiom on network zones because SimGrid does not allow (yet) to create nor
+      destroy resources once the simulation is started. 
+
+   .. group-tab:: C
+
+      .. code:: C
+
+         #include <simgrid/zone.h>
+
+      .. doxygentypedef:: sg_netzone_t
+      .. cpp:type:: const s4u_NetZone* const_sg_netzone_t
+
+         Pointer to a constant network zone object.
+
+Retrieving zones
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      See :cpp:func:`simgrid::s4u::Engine::get_netzone_root`,
+      :cpp:func:`simgrid::s4u::Engine::netzone_by_name_or_null` and
+      :cpp:func:`simgrid::s4u::Engine::get_filtered_netzones`.
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_zone_get_by_name(const char *name)
+      .. autodoxymethod:: sg_zone_get_root()
+
+Querying info
+--------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_cname()
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_name()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_zone_get_name(const_sg_netzone_t zone)
+
+User data and properties
+------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_properties()
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_property(const std::string &key)
+      .. autodoxymethod:: simgrid::s4u::NetZone::set_property(const std::string &key, const std::string &value)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_zone_get_property_value(const_sg_netzone_t as, const char *name)
+      .. autodoxymethod:: sg_zone_set_property_value(sg_netzone_t netzone, const char *name, const char *value)
+
+Retrieving components
+---------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_all_hosts()
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_host_count()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
+
+Routing data
+------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::NetZone::add_bypass_route(kernel::routing::NetPoint *src, kernel::routing::NetPoint *dst, kernel::routing::NetPoint *gw_src, kernel::routing::NetPoint *gw_dst, std::vector< kernel::resource::LinkImpl * > &link_list, bool symmetrical)
+      .. autodoxymethod:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm)
+      .. autodoxymethod:: simgrid::s4u::NetZone::add_route(kernel::routing::NetPoint *src, kernel::routing::NetPoint *dst, kernel::routing::NetPoint *gw_src, kernel::routing::NetPoint *gw_dst, std::vector< kernel::resource::LinkImpl * > &link_list, bool symmetrical)
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_children()
+      .. autodoxymethod:: simgrid::s4u::NetZone::get_father()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
+
+Signals
+-------
+
+.. tabs::
+
+  .. group-tab:: C++
+
+     .. autodoxyvar:: simgrid::s4u::NetZone::on_creation
+     .. autodoxyvar:: simgrid::s4u::NetZone::on_route_creation
+     .. autodoxyvar:: simgrid::s4u::NetZone::on_seal
+
+

 .. doxygenclass:: simgrid::s4u::NetZone
    :members:
    :protected-members:
 .. doxygenclass:: simgrid::s4u::NetZone
    :members:
    :protected-members:


@@ -1206,23 +1546,110 @@ DVFS
 ⁣  class VirtualMachine
 =======================
 
 ⁣  class VirtualMachine
 =======================
 

-.. doxygenclass:: simgrid::s4u::VirtualMachine
-   :members:
-   :protected-members:
-   :undoc-members:

 
 

-.. autodoxymethod:: sg_vm_create_core
-.. autodoxymethod:: sg_vm_create_multicore
-.. autodoxymethod:: sg_vm_get_name
-.. autodoxymethod:: sg_vm_get_pm
-.. autodoxymethod:: sg_vm_is_created
-.. autodoxymethod:: sg_vm_is_running
-.. autodoxymethod:: sg_vm_is_suspended
-.. autodoxymethod:: sg_vm_start
-.. autodoxymethod:: sg_vm_suspend
-.. autodoxymethod:: sg_vm_resume
-.. autodoxymethod:: sg_vm_shutdown
-.. autodoxymethod:: sg_vm_destroy
+.. autodoxyclass:: simgrid::s4u::VirtualMachine
+
+Basic management
+----------------
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. code-block:: C++
+
+         #include <simgrid/s4u/VirtualMachine.hpp>
+
+      Note that there is no VirtualMachinePtr type, and that you cannot use the RAII
+      idiom on virtual machines. There is no good reason for that and should change in the future.
+
+   .. group-tab:: C
+
+      .. code:: C
+
+         #include <simgrid/vm.h>
+
+      .. doxygentypedef:: sg_vm_t
+      .. cpp:type:: const s4u_VirtualMachine* const_sg_vm_t
+
+         Pointer to a constant virtual machine object.
+
+Creating VMs
+------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::VirtualMachine(const std::string &name, Host *physical_host, int core_amount)
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::VirtualMachine(const std::string &name, Host *physical_host, int core_amount, size_t ramsize)
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::destroy()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_vm_create_core
+      .. autodoxymethod:: sg_vm_create_multicore
+      .. autodoxymethod:: sg_vm_destroy
+
+Querying info
+--------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_pm()
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_ramsize()
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_state()
+
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_bound(double bound)
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_pm(Host *pm)
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_ramsize(size_t ramsize)
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_vm_get_ramsize(const_sg_vm_t vm)
+      .. autodoxymethod:: sg_vm_set_bound(sg_vm_t vm, double bound)
+      .. autodoxymethod:: sg_vm_set_ramsize(sg_vm_t vm, size_t size)
+
+      .. autodoxymethod:: sg_vm_get_name
+      .. autodoxymethod:: sg_vm_get_pm
+      .. autodoxymethod:: sg_vm_is_created
+      .. autodoxymethod:: sg_vm_is_running
+      .. autodoxymethod:: sg_vm_is_suspended
+
+Life cycle
+----------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::resume()
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::shutdown()
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::start()
+      .. autodoxymethod:: simgrid::s4u::VirtualMachine::suspend()
+
+   .. group-tab:: C
+
+      .. autodoxymethod:: sg_vm_start
+      .. autodoxymethod:: sg_vm_suspend
+      .. autodoxymethod:: sg_vm_resume
+      .. autodoxymethod:: sg_vm_shutdown
+
+Signals
+-------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_migration_end
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_migration_start
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_resume
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_shutdown
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_start
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_started
+      .. autodoxyvar:: simgrid::s4u::VirtualMachine::on_suspend

 
 .. _API_s4u_Activity:
 
 
 .. _API_s4u_Activity:
 


@@ -1238,16 +1665,15 @@ class Activity
    :ref:`I/O <API_s4u_Io>` (started on and consumming disks).
    See also the :ref:`section on activities <s4u_Activities>` above.
 
    :ref:`I/O <API_s4u_Io>` (started on and consumming disks).
    See also the :ref:`section on activities <s4u_Activities>` above.
 

-Querying info about activities
-------------------------------
+Querying info
+-------------

 
    .. autodoxymethod:: simgrid::s4u::Activity::get_remaining()
    .. autodoxymethod:: simgrid::s4u::Activity::get_state()
    .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains)
 
    .. autodoxymethod:: simgrid::s4u::Activity::get_remaining()
    .. autodoxymethod:: simgrid::s4u::Activity::get_state()
    .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains)

-   .. autodoxymethod:: simgrid::s4u::Activity::get_impl

 
 

-Activities lifecycle
---------------------
+Activities life cycle
+---------------------

 
    .. autodoxymethod:: simgrid::s4u::Activity::start
    .. autodoxymethod:: simgrid::s4u::Activity::cancel
 
    .. autodoxymethod:: simgrid::s4u::Activity::start
    .. autodoxymethod:: simgrid::s4u::Activity::cancel


@@ -1255,6 +1681,7 @@ Activities lifecycle
    .. autodoxymethod:: simgrid::s4u::Activity::wait
    .. autodoxymethod:: simgrid::s4u::Activity::wait_for
    .. autodoxymethod:: simgrid::s4u::Activity::wait_until(double time_limit)
    .. autodoxymethod:: simgrid::s4u::Activity::wait
    .. autodoxymethod:: simgrid::s4u::Activity::wait_for
    .. autodoxymethod:: simgrid::s4u::Activity::wait_until(double time_limit)

+   .. autodoxymethod:: simgrid::s4u::Activity::vetoable_start()

 
 .. _API_s4u_Comm:
 
 
 .. _API_s4u_Comm:
 


@@ -1542,33 +1969,6 @@ Locking
          .. autodoxymethod:: sg_sem_release(sg_sem_t sem)
          .. autodoxymethod:: sg_sem_would_block(sg_sem_t sem)
 
          .. autodoxymethod:: sg_sem_release(sg_sem_t sem)
          .. autodoxymethod:: sg_sem_would_block(sg_sem_t sem)
 

-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.
-
-==========
-Class Comm
-==========
-
-.. autoclass:: simgrid.Comm
-   :members:
-
-==========
-Class Exec
-==========
-
-.. autoclass:: simgrid.Exec
-   :members:
-
-==========
-Class Host
-==========
-
-.. autoclass:: simgrid.Host
-   :members:
-

 .. |hr| raw:: html
 
    <hr />
 .. |hr| raw:: html
 
    <hr />