From 471d0736505fc6cfd8f018bdeb8bd3846ee2adad Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 1 Feb 2020 16:25:52 +0100 Subject: [PATCH] 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. --- docs/find-missing.ignore | 5 + docs/source/app_s4u.rst | 135 ++++++++++++++++++++----- include/simgrid/s4u/VirtualMachine.hpp | 2 + include/simgrid/vm.h | 12 +-- 4 files changed, 120 insertions(+), 34 deletions(-) diff --git a/docs/find-missing.ignore b/docs/find-missing.ignore index 2d287b71a6..26a7c45141 100644 --- 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 1aa87ebadd..8123177b29 100644 --- 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 + + 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 + + .. 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 ` (started on and consumming disks). See also the :ref:`section on 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 0bbc6ae4bf..689afdd918 100644 --- 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 b9f77d0fec..a89e274e15 100644 --- 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); -- 2.20.1