From bf2eac918e4a2b27667268c0f4355f0797fd5af4 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sun, 12 Jan 2020 15:32:50 +0100 Subject: [PATCH 1/1] start documenting Hosts in the new way --- docs/find-missing.ignore | 2 +- docs/source/app_s4u.rst | 129 ++++++++++++++++++++++++++++++--- include/simgrid/host.h | 20 ++--- include/simgrid/s4u/Engine.hpp | 7 +- include/simgrid/s4u/Host.hpp | 30 +++++++- src/s4u/s4u_Host.cpp | 35 --------- 6 files changed, 161 insertions(+), 62 deletions(-) diff --git a/docs/find-missing.ignore b/docs/find-missing.ignore index a996761322..b9309f7324 100644 --- a/docs/find-missing.ignore +++ b/docs/find-missing.ignore @@ -171,4 +171,4 @@ It is only used by find-missing, that will not report any definition linked here .. autodoxyvar:: ::const_sg_bar_t .. autodoxyvar:: ::const_sg_mutex_t .. autodoxyvar:: ::const_sg_sem_t - +.. autodoxyvar:: ::const_sg_host_t diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 7ff904f7bf..f66286ea01 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -454,8 +454,8 @@ Creating actors .. autodoxymethod:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties) .. autodoxymethod:: sg_actor_detach() -Searching specific actors -------------------------- +Retrieving actors +----------------- .. tabs:: @@ -474,8 +474,8 @@ Searching specific actors .. autodoxymethod:: sg_actor_by_PID(aid_t pid) .. autodoxymethod:: sg_actor_self() -Querying info about actors --------------------------- +Querying info +------------- .. tabs:: @@ -835,6 +835,10 @@ Retrieving hosts .. automethod:: simgrid.Engine.get_all_hosts + .. group-tab:: C + + See also :cpp:func:`sg_host_list` and :cpp:func:`sg_host_count`. + Retrieving links ---------------- @@ -1059,6 +1063,116 @@ Signals ⁣  class Host ============= +.. autodoxyclass:: simgrid::s4u::Host + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + Note that there is no HostPtr 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 Host + + .. group-tab:: C + + .. code:: C + + #include + + .. doxygentypedef:: sg_host_t + .. cpp:type:: const s4u_Host* const_sg_host_t + + Pointer to a constant host object. + +Retrieving hosts +---------------- + +.. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Engine::get_all_hosts`. + + .. autodoxymethod:: simgrid::s4u::Host::by_name(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Host::by_name_or_null(const std::string &name) + .. autodoxymethod:: simgrid::s4u::Host::current() + + .. group-tab:: Python + + See also :py:func:`simgrid.Engine.get_all_hosts`. + + .. automethod:: simgrid.Host.by_name + .. automethod:: simgrid.Host.current + + .. group-tab:: C + + .. autodoxymethod:: sg_host_by_name(const char *name) + .. autodoxymethod:: sg_host_count() + .. autodoxymethod:: sg_host_list() + .. autodoxymethod:: sg_hosts_as_dynar() + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. 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() + + .. group-tab:: Python + + .. autoattribute:: simgrid.Exec.host + .. autoattribute:: simgrid.Host.name + + .. group-tab:: C + + .. autodoxymethod:: ::sg_host_core_count(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_name(const_sg_host_t host) + +DVFS +---- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Host::get_pstate() + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_count() + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_speed(int pstate_index) + .. autodoxymethod:: simgrid::s4u::Host::set_pstate(int pstate_index) + .. autodoxymethod:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p) + .. autodoxymethod:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p) + + .. group-tab:: Python + + .. automethod:: simgrid.Host.get_pstate_count + .. automethod:: simgrid.Host.get_pstate_speed + + .. group-tab:: C + + .. autodoxymethod:: sg_host_get_available_speed(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_nb_pstates(const_sg_host_t host) + .. autodoxymethod:: sg_host_get_pstate(const_sg_host_t host) + .. 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: @@ -1455,13 +1569,6 @@ Class Host .. autoclass:: simgrid.Host :members: -============= -Class Mailbox -============= - -.. autoclass:: simgrid.Mailbox - :members: - .. |hr| raw:: html
diff --git a/include/simgrid/host.h b/include/simgrid/host.h index c2287220af..85d17a22c3 100644 --- a/include/simgrid/host.h +++ b/include/simgrid/host.h @@ -11,16 +11,15 @@ #include SG_BEGIN_DECL -/** @brief Host datatype. +/** Returns an array of all existing hosts (use sg_host_count() to know the array size). * - * A location (or host) is any possible place where an actor may run. Thus it is represented as a - * physical resource with computing capabilities, some mailboxes to enable running actors to - * communicate with remote ones, and some private data that can be only accessed by local actors. + * @remark The host order in this array is generally different from the + * creation/declaration order in the XML platform (we use a hash table + * internally). */ - XBT_PUBLIC sg_host_t* sg_host_list(); -/** @brief Return the current number of hosts. */ +/** Returns the amount of hosts existing in the platform. */ XBT_PUBLIC size_t sg_host_count(); /** @@ -33,15 +32,10 @@ XBT_PUBLIC xbt_dynar_t sg_hosts_as_dynar(); XBT_PUBLIC size_t sg_host_extension_create(void (*deleter)(void*)); XBT_PUBLIC void* sg_host_extension_get(const_sg_host_t host, size_t rank); -/** @brief Finds a sg_host_t using its name. - * - * This is a name directory service - * @param name the name of an host. - * @return the corresponding host - */ +/** Finds an host from its name */ XBT_PUBLIC sg_host_t sg_host_by_name(const char* name); -/** @brief Return the name of the #sg_host_t. */ +/** @brief Return the name of the sg_host_t. */ XBT_PUBLIC const char* sg_host_get_name(const_sg_host_t host); // ========== User Data ============== diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp index 234a82bddc..6cc8c60a2f 100644 --- a/include/simgrid/s4u/Engine.hpp +++ b/include/simgrid/s4u/Engine.hpp @@ -91,8 +91,13 @@ protected: #endif /*DOXYGEN*/ public: + /** Returns the amount of hosts existing in the platform. */ size_t get_host_count(); - /** @brief Returns the list of all hosts found in the platform */ + /** Returns a vector of all hosts found in the platform. + * + * The order is generally different from the creation/declaration order in the XML platform because we use a hash + * table internally. + */ std::vector get_all_hosts(); std::vector get_filtered_hosts(const std::function& filter); Host* host_by_name(const std::string& name); diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp index 4870a86239..0375c7c159 100644 --- a/include/simgrid/s4u/Host.hpp +++ b/include/simgrid/s4u/Host.hpp @@ -36,6 +36,7 @@ namespace s4u { * @endrst */ class XBT_PUBLIC Host : public xbt::Extendable { +#ifndef DOXYGEN friend vm::VMModel; // Use the pimpl_cpu to compute the VM sharing friend vm::VirtualMachineImpl; // creates the the pimpl_cpu friend kernel::routing::NetZoneImpl; @@ -43,13 +44,13 @@ class XBT_PUBLIC Host : public xbt::Extendable { public: explicit Host(const std::string& name); - /** Host destruction logic */ protected: virtual ~Host(); void set_netpoint(kernel::routing::NetPoint* netpoint) { pimpl_netpoint_ = netpoint; } private: bool currently_destroying_ = false; +#endif public: /** Called on each newly created host */ @@ -63,9 +64,11 @@ public: static xbt::signal on_speed_change; virtual void destroy(); +#ifndef DOXYGEN // No copy/move Host(Host const&) = delete; Host& operator=(Host const&) = delete; +#endif /** Retrieve a host from its name, or return nullptr */ static Host* by_name_or_null(const std::string& name); @@ -107,9 +110,34 @@ public: void set_state_profile(kernel::profile::Profile* p); void set_speed_profile(kernel::profile::Profile* p); + /** @brief Get the peak computing speed in flops/s at the current pstate, NOT taking the external load into account. + * + * The amount of flops per second available for computing depends on several things: + * - The current pstate determines the maximal peak computing speed (use @ref get_pstate_speed() to retrieve the + * computing speed you would get at another pstate) + * - If you declared an external load (with @ref simgrid::surf::Cpu::set_speed_profile()), you must multiply the + * result of get_speed() by get_available_speed() to retrieve what a new computation would get. + * + * The remaining speed is then shared between the executions located on this host. + * You can retrieve the amount of tasks currently running on this host with @ref get_load(). + * + * The host may have multiple cores, and your executions may be able to use more than a single core. + * + * Finally, executions of priority 2 get twice the amount of flops than executions of priority 1. + */ double get_speed() const; + /** @brief Get the available speed ratio, between 0 and 1. + * + * This accounts for external load (see @ref simgrid::surf::Cpu::set_speed_profile()). + */ double get_available_speed() const; + /** Returns the number of core of the processor. */ int get_core_count() const; + /** Returns the current computation load (in flops per second) + * + * The external load (coming from an availability trace) is not taken in account. + * You may also be interested in the load plugin. + */ double get_load() const; double get_pstate_speed(int pstate_index) const; diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp index 038bb3e6c8..d4841f2ca8 100644 --- a/src/s4u/s4u_Host.cpp +++ b/src/s4u/s4u_Host.cpp @@ -227,44 +227,19 @@ double Host::get_pstate_speed(int pstate_index) const return this->pimpl_cpu->get_pstate_peak_speed(pstate_index); } -/** @brief Get the peak computing speed in flops/s at the current pstate, NOT taking the external load into account. - * - * The amount of flops per second available for computing depends on several things: - * - The current pstate determines the maximal peak computing speed (use @ref get_pstate_speed() to retrieve the - * computing speed you would get at another pstate) - * - If you declared an external load (with @ref simgrid::surf::Cpu::set_speed_profile()), you must multiply the - * result of get_speed() by get_available_speed() to retrieve what a new computation would get. - * - * The remaining speed is then shared between the executions located on this host. - * You can retrieve the amount of tasks currently running on this host with @ref get_load(). - * - * The host may have multiple cores, and your executions may be able to use more than a single core. - * - * Finally, executions of priority 2 get twice the amount of flops than executions of priority 1. - */ double Host::get_speed() const { return this->pimpl_cpu->get_speed(1.0); } -/** @brief Returns the current computation load (in flops per second) - * - * The external load (coming from an availability trace) is not taken in account. - * You may also be interested in the load plugin. - */ double Host::get_load() const { return this->pimpl_cpu->get_load(); } -/** @brief Get the available speed ratio, between 0 and 1. - * - * This accounts for external load (see @ref simgrid::surf::Cpu::set_speed_profile()). - */ double Host::get_available_speed() const { return this->pimpl_cpu->get_speed_ratio(); } -/** @brief Returns the number of core of the processor. */ int Host::get_core_count() const { return this->pimpl_cpu->get_core_count(); @@ -336,16 +311,6 @@ size_t sg_host_count() { return simgrid::s4u::Engine::get_instance()->get_host_count(); } -/** @brief Returns the host list - * - * Uses sg_host_count() to know the array size. - * - * @return an array of @ref sg_host_t containing all the hosts in the platform. - * @remark The host order in this array is generally different from the - * creation/declaration order in the XML platform (we use a hash table - * internally). - * @see sg_host_count() - */ sg_host_t* sg_host_list() { xbt_assert(sg_host_count() > 0, "There is no host!"); -- 2.20.1