document Virtual machines

Even if I hate to document code that should change. Here, we should
kill the fact that s4u::VirtualMachine extends s4u::Host, as it only
complicates things for nothing. It probably requires that we
dupplicate the methods this_actor::exec() and Actor::set_host() to add
a variant taking a VM instead of the host, but that would still be an
improvement.

Also, the zone C type should probably be renamed into netzone for
consistency.

diff --git a/docs/find-missing.ignore b/docs/find-missing.ignore
index 2d287b7..26a7c45 100644 (file)
--- a/docs/find-missing.ignore
+++ b/docs/find-missing.ignore
@@ -2,6 +2,9 @@ This file lists the symbols ignored in the documentation.
 It follows the RST syntact but is completely ignored by sphinx. 
 It is only used by find-missing, that will not report any definition linked here as missing.
 
+# This one triggers a bug in doxygen or sphinx when I try to document it with autodoxy
+.. autodoxyvar:: simgrid::s4u::Link::on_communicate
+
 # I don't plan to document MSG in the new way.
 .. autodoxymethod:: ::MSG_barrier_destroy(const_sg_bar_t bar)
 .. autodoxymethod:: ::MSG_barrier_init(unsigned int count)
@@ -181,6 +184,8 @@ member ::msg_error_t is of kind enum
 # These should not be public
 .. autodoxymethod:: simgrid::s4u::Link::get_impl()
 .. autodoxymethod:: simgrid::s4u::NetZone::get_impl()
+.. autodoxymethod:: simgrid::s4u::VirtualMachine::get_impl()
+
 
 # These ones are a bug of Doxygen, that parse them as variables instead of types.
 # So we don't use this bogus parse result, but go directly for cpp:type directives in app_s4u.rst

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 1aa87eb..8123177 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -1474,7 +1474,7 @@ Querying info
 
    .. group-tab:: C
 
-      .. autodoxymethod:: ::sg_zone_get_name(const_sg_netzone_t zone)
+      .. autodoxymethod:: sg_zone_get_name(const_sg_netzone_t zone)
 
 User data and properties
 ------------------------
@@ -1489,8 +1489,8 @@ User data and properties
 
    .. 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)
+      .. 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
 ---------------------
@@ -1546,23 +1546,110 @@ Signals
 ⁣  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:
 
@@ -1578,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.
 
-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_impl
 
-Activities lifecycle
---------------------
+Activities life cycle
+---------------------
 
    .. autodoxymethod:: simgrid::s4u::Activity::start
    .. autodoxymethod:: simgrid::s4u::Activity::cancel
@@ -1595,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::vetoable_start()
 
 .. _API_s4u_Comm:
 

diff --git a/include/simgrid/s4u/VirtualMachine.hpp b/include/simgrid/s4u/VirtualMachine.hpp
index 0bbc6ae..689afdd 100644 (file)
--- a/include/simgrid/s4u/VirtualMachine.hpp
+++ b/include/simgrid/s4u/VirtualMachine.hpp
@@ -28,9 +28,11 @@ public:
   explicit VirtualMachine(const std::string& name, Host* physical_host, int core_amount);
   explicit VirtualMachine(const std::string& name, Host* physical_host, int core_amount, size_t ramsize);
 
+#ifndef DOXYGEN
   // No copy/move
   VirtualMachine(VirtualMachine const&) = delete;
   VirtualMachine& operator=(VirtualMachine const&) = delete;
+#endif
 
   enum class state {
     CREATED, /**< created, but not yet started */

diff --git a/include/simgrid/vm.h b/include/simgrid/vm.h
index b9f77d0..a89e274 100644 (file)
--- a/include/simgrid/vm.h
+++ b/include/simgrid/vm.h
@@ -1,4 +1,4 @@
-/* Public interface to the Link datatype                                    */
+/* Public interface to the Virtual Machine datatype                         */
 
 /* Copyright (c) 2018-2020. The SimGrid Team. All rights reserved.          */
 
@@ -14,16 +14,8 @@
 /* C interface */
 SG_BEGIN_DECL
 
-/** @brief Opaque type describing a Virtual Machine.
- *  @ingroup msg_VMs
- *
- * All this is highly experimental and the interface will probably change in the future.
- * Please don't depend on this yet (although testing is welcomed if you feel so).
- * Usual lack of guaranty of any kind applies here, and is even increased.
- *
- */
 XBT_PUBLIC sg_vm_t sg_vm_create_core(sg_host_t pm, const char* name);
-XBT_PUBLIC sg_vm_t sg_vm_create_multicore(sg_host_t pm, const char* name, int coreAmount);
+XBT_PUBLIC sg_vm_t sg_vm_create_multicore(sg_host_t pm, const char* name, int core_amount);
 
 XBT_PUBLIC int sg_vm_is_created(sg_vm_t vm);
 XBT_PUBLIC int sg_vm_is_running(sg_vm_t vm);