From: Martin Quinson Date: Tue, 21 Nov 2023 12:08:53 +0000 (+0100) Subject: further improvement to the doxygen doc X-Git-Tag: v3.35~9 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/cef6554994ae17d8f56c9245ad2c10c7cf39af8c further improvement to the doxygen doc --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 8c5a6e8ffe..cf257475d5 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -1200,11 +1200,17 @@ Querying info .. doxygenfunction:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value) .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy + .. doxygenenum:: simgrid::s4u::Disk::Operation + .. doxygenenum:: simgrid::s4u::Disk::SharingPolicy + .. group-tab:: Python .. autoattribute:: simgrid.Disk.name .. automethod:: simgrid.Disk.set_sharing_policy + .. autoclass:: simgrid.Disk.Operation + .. autoclass:: simgrid.Disk.SharingPolicy + I/O operations -------------- @@ -1611,52 +1617,70 @@ Querying info .. group-tab:: C++ - .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const .. doxygenfunction:: simgrid::s4u::Link::get_cname() const - .. doxygenfunction:: simgrid::s4u::Link::get_latency() const .. doxygenfunction:: simgrid::s4u::Link::get_name() const - .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const - .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const .. doxygenfunction:: simgrid::s4u::Link::get_load() const .. doxygenfunction:: simgrid::s4u::Link::is_used() const .. group-tab:: Python - .. autoattribute:: simgrid.Link.bandwidth - .. autoattribute:: simgrid.Link.latency + .. autoattribute:: simgrid.Link.name .. group-tab:: C - .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link) - .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link) .. doxygenfunction:: sg_link_get_name(const_sg_link_t link) .. doxygenfunction:: sg_link_is_shared(const_sg_link_t link) -Modifying characteristics -------------------------- +Performance +----------- .. tabs:: .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const + .. doxygenfunction:: simgrid::s4u::Link::get_latency() const .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth(double value) .. doxygenfunction:: simgrid::s4u::Link::set_latency(double value) .. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value) - .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit) - .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy .. group-tab:: Python + .. autoattribute:: simgrid.Link.bandwidth + .. autoattribute:: simgrid.Link.latency .. automethod:: simgrid.Link.set_bandwidth .. automethod:: simgrid.Link.set_latency - .. automethod:: simgrid.Link.set_concurrency_limit - .. automethod:: simgrid.Link.set_sharing_policy .. group-tab:: C + .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link) + .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link) .. doxygenfunction:: sg_link_set_bandwidth(sg_link_t link, double value) .. doxygenfunction:: sg_link_set_latency(sg_link_t link, double value) +Model policy +------------ + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenenum:: simgrid::s4u::Link::SharingPolicy + + .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const + .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy + + .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const + .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit) + + .. group-tab:: Python + + .. automethod:: simgrid.Link.set_concurrency_limit + .. automethod:: simgrid.Link.set_sharing_policy + + .. group-tab:: C + + User data and properties ------------------------ diff --git a/include/simgrid/s4u/Link.hpp b/include/simgrid/s4u/Link.hpp index c79ca462ac..c2ac18e036 100644 --- a/include/simgrid/s4u/Link.hpp +++ b/include/simgrid/s4u/Link.hpp @@ -45,7 +45,21 @@ protected: #endif public: - enum class SharingPolicy { NONLINEAR = 4, WIFI = 3, SPLITDUPLEX = 2, SHARED = 1, FATPIPE = 0 }; + /** Specifies how a given link is shared between concurrent communications */ + enum class SharingPolicy { + /// This policy takes a callback that specifies the maximal capacity as a function of the number of usage. See the + /// examples with 'degradation' in their name. + NONLINEAR = 4, + /// Pseudo-sharing policy requesting wifi-specific sharing. + WIFI = 3, + /// Each link is split in 2, UP and DOWN, one per direction. These links are SHARED. + SPLITDUPLEX = 2, + /// The bandwidth is shared between all comms using that link, regardless of their direction. + SHARED = 1, + /// Each comm can use the link fully, with no sharing (only a maximum). This is intended to represent the backbone + /// links that cannot be saturated by concurrent links, but have a maximal bandwidth. + FATPIPE = 0 + }; kernel::resource::StandardLinkImpl* get_impl() const; diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp index 8dd178a1ab..41e86465b6 100644 --- a/src/bindings/python/simgrid_python.cpp +++ b/src/bindings/python/simgrid_python.cpp @@ -571,11 +571,17 @@ PYBIND11_MODULE(simgrid, m) "__repr__", [](const Link* l) { return "Link(" + l->get_name() + ")"; }, "Textual representation of the Link"); py::enum_(link, "SharingPolicy") - .value("NONLINEAR", Link::SharingPolicy::NONLINEAR) - .value("WIFI", Link::SharingPolicy::WIFI) - .value("SPLITDUPLEX", Link::SharingPolicy::SPLITDUPLEX) - .value("SHARED", Link::SharingPolicy::SHARED) - .value("FATPIPE", Link::SharingPolicy::FATPIPE); + .value("NONLINEAR", Link::SharingPolicy::NONLINEAR, + "This policy takes a callback that specifies the maximal capacity as a function of the number of usage. " + "See the examples with 'degradation' in their name.") + .value("WIFI", Link::SharingPolicy::WIFI, "Pseudo-sharing policy requesting wifi-specific sharing.") + .value("SPLITDUPLEX", Link::SharingPolicy::SPLITDUPLEX, + "Each link is split in 2, UP and DOWN, one per direction. These links are SHARED.") + .value("SHARED", Link::SharingPolicy::SHARED, + "The bandwidth is shared between all comms using that link, regardless of their direction.") + .value("FATPIPE", Link::SharingPolicy::FATPIPE, + "Each comm can use the link fully, with no sharing (only a maximum). This is intended to represent the " + "backbone links that cannot be saturated by concurrent links, but have a maximal bandwidth."); /* Class LinkInRoute */ py::class_ linkinroute(m, "LinkInRoute", "Abstraction to add link in routes");