From 55491279cdea3f01da22d1b51874e2e168ac5116 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sun, 2 Feb 2020 00:46:50 +0100 Subject: [PATCH] finish the API under the new format - Add some 'const' method decorators on my way - We cannot drop the breathe extension of sphinx yet because autodoxy does not parse typedef (nor enums) yet so we use breathe for that - Other bugs surfaced in autodoxy, but I'm short on time so I worked around them. See find-missing.ignore for a list of weird things. --- docs/Build.sh | 2 +- docs/find-missing.ignore | 27 +- docs/source/_ext/autodoxy.py | 2 +- docs/source/app_s4u.rst | 374 +++++++++++++----- .../simgrid/kernel/routing/NetZoneImpl.hpp | 10 +- include/simgrid/s4u/Exec.hpp | 16 +- include/simgrid/s4u/Io.hpp | 2 +- include/simgrid/s4u/NetZone.hpp | 2 +- src/kernel/activity/IoImpl.hpp | 6 +- src/kernel/routing/NetZoneImpl.cpp | 4 +- src/s4u/s4u_Exec.cpp | 1 - src/s4u/s4u_Io.cpp | 5 +- src/s4u/s4u_Netzone.cpp | 2 +- 13 files changed, 329 insertions(+), 124 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index 51ab88da50..6a150ef8eb 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -13,7 +13,7 @@ if [ "x$1" != 'xdoxy' ] && [ -e build/xml ] ; then echo "Doxygen not rerun: 'doxy' was not provided as an argument" else rm -rf build/xml source/api/ - cd source; doxygen; cd .. + (cd source; doxygen 2>&1; cd ..) | grep -v "is not documented." #  XXXXX Reduce the verbosity for now fi if [ "x$1" != 'xjava' ] && [ -e source/java ] ; then diff --git a/docs/find-missing.ignore b/docs/find-missing.ignore index 26a7c45141..76933b7dea 100644 --- a/docs/find-missing.ignore +++ b/docs/find-missing.ignore @@ -2,8 +2,26 @@ 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 +# These ones trigger a bug in autodoxy, that get confused with the const in the function parameter +# So I document them manually in the rst for now. Shame, weak. .. autodoxyvar:: simgrid::s4u::Link::on_communicate +.. autodoxyvar:: simgrid::s4u::Actor::on_host_change +.. autodoxyvar:: simgrid::s4u::Exec::on_completion +.. autodoxyvar:: simgrid::s4u::Exec::on_start + +# This is a bug in find-missing, as these symbols are actually documented +.. 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) + + +# These could be hidden as private things, eg in s4u_Exec.cpp +.. autodoxymethod:: simgrid::s4u::ExecPar::get_remaining() +.. autodoxymethod:: simgrid::s4u::ExecPar::get_remaining_ratio() +.. autodoxymethod:: simgrid::s4u::ExecPar::start() +.. autodoxymethod:: simgrid::s4u::ExecSeq::get_remaining() +.. autodoxymethod:: simgrid::s4u::ExecSeq::get_remaining_ratio() +.. autodoxymethod:: simgrid::s4u::ExecSeq::set_host(Host *host) +.. autodoxymethod:: simgrid::s4u::ExecSeq::start() # I don't plan to document MSG in the new way. .. autodoxymethod:: ::MSG_barrier_destroy(const_sg_bar_t bar) @@ -185,7 +203,12 @@ member ::msg_error_t is of kind enum .. autodoxymethod:: simgrid::s4u::Link::get_impl() .. autodoxymethod:: simgrid::s4u::NetZone::get_impl() .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_impl() - +.. autodoxymethod:: simgrid::s4u::Activity::get_impl() +.. autodoxymethod:: simgrid::s4u::Comm::~Comm() +.. autodoxymethod:: simgrid::s4u::Exec::~Exec() +.. autodoxymethod:: simgrid::s4u::ExecPar::~ExecPar() +.. autodoxymethod:: simgrid::s4u::ExecSeq::~ExecSeq() +.. autodoxymethod:: simgrid::s4u::Io::~Io() # 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/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py index af672a227d..3d91b10d34 100644 --- a/docs/source/_ext/autodoxy.py +++ b/docs/source/_ext/autodoxy.py @@ -311,7 +311,7 @@ class DoxygenClassDocumenter(DoxygenDocumenter): xpath_query = './/compoundname[text()="%s"]/..' % self.fullname match = get_doxygen_root().xpath(xpath_query) if len(match) != 1: - raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried' + raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried ' 'the following xpath: "%s"' % (self.fullname, xpath_query)) self.object = match[0] diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 8123177b29..1991185198 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -604,6 +604,10 @@ Signals .. autodoxyvar:: simgrid::s4u::Actor::on_creation .. autodoxyvar:: simgrid::s4u::Actor::on_suspend + .. cpp:var:: xbt::signal Actor::on_host_change + + Signal fired when an actor is migrated from one host to another. + .. autodoxyvar:: simgrid::s4u::Actor::on_resume .. autodoxyvar:: simgrid::s4u::Actor::on_sleep .. autodoxyvar:: simgrid::s4u::Actor::on_wake_up @@ -919,8 +923,8 @@ Querying info .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Mailbox::get_cname() - .. autodoxymethod:: simgrid::s4u::Mailbox::get_name() + .. autodoxymethod:: simgrid::s4u::Mailbox::get_cname() const + .. autodoxymethod:: simgrid::s4u::Mailbox::get_name() const .. group-tab:: Python @@ -1023,13 +1027,13 @@ Querying info .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Disk::get_cname() - .. autodoxymethod:: simgrid::s4u::Disk::get_host() - .. autodoxymethod:: simgrid::s4u::Disk::get_name() - .. autodoxymethod:: simgrid::s4u::Disk::get_properties() - .. autodoxymethod:: simgrid::s4u::Disk::get_property(const std::string &key) - .. autodoxymethod:: simgrid::s4u::Disk::get_read_bandwidth() - .. autodoxymethod:: simgrid::s4u::Disk::get_write_bandwidth() + .. autodoxymethod:: simgrid::s4u::Disk::get_cname() const + .. autodoxymethod:: simgrid::s4u::Disk::get_host() const + .. autodoxymethod:: simgrid::s4u::Disk::get_name() const + .. autodoxymethod:: simgrid::s4u::Disk::get_properties() const + .. autodoxymethod:: simgrid::s4u::Disk::get_property(const std::string &key) const + .. autodoxymethod:: simgrid::s4u::Disk::get_read_bandwidth() const + .. autodoxymethod:: simgrid::s4u::Disk::get_write_bandwidth() const .. autodoxymethod:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value) I/O operations @@ -1133,12 +1137,12 @@ Querying info .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Host::get_cname() - .. autodoxymethod:: simgrid::s4u::Host::get_core_count() - .. 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() + .. autodoxymethod:: simgrid::s4u::Host::get_cname() const + .. autodoxymethod:: simgrid::s4u::Host::get_core_count() const + .. autodoxymethod:: simgrid::s4u::Host::get_name() const + .. autodoxymethod:: simgrid::s4u::Host::get_available_speed() const + .. autodoxymethod:: simgrid::s4u::Host::get_load() const + .. autodoxymethod:: simgrid::s4u::Host::get_speed() const .. group-tab:: Python @@ -1162,8 +1166,8 @@ User data and properties .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Host::get_properties() - .. autodoxymethod:: simgrid::s4u::Host::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::Host::get_properties() const + .. autodoxymethod:: simgrid::s4u::Host::get_property(const std::string &key) const .. 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) @@ -1183,9 +1187,9 @@ Retrieving components .. 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::get_actor_count() const + .. autodoxymethod:: simgrid::s4u::Host::get_all_actors() const + .. autodoxymethod:: simgrid::s4u::Host::get_disks() const .. autodoxymethod:: simgrid::s4u::Host::remove_disk(const std::string &disk_name) .. group-tab:: C @@ -1199,7 +1203,7 @@ On/Off .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Host::is_on() + .. autodoxymethod:: simgrid::s4u::Host::is_on() const .. autodoxymethod:: simgrid::s4u::Host::turn_off() .. autodoxymethod:: simgrid::s4u::Host::turn_on() @@ -1216,9 +1220,9 @@ DVFS .. 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::get_pstate() const + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_count() const + .. autodoxymethod:: simgrid::s4u::Host::get_pstate_speed(int pstate_index) const .. 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) @@ -1255,9 +1259,9 @@ Platform and routing .. 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::get_netpoint() const + .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const + .. autodoxymethod:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) const .. autodoxymethod:: simgrid::s4u::Host::send_to(Host *dest, double byte_amount) .. group-tab:: C @@ -1344,13 +1348,13 @@ Querying info .. 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() + .. autodoxymethod:: simgrid::s4u::Link::get_bandwidth() const + .. autodoxymethod:: simgrid::s4u::Link::get_cname() const + .. autodoxymethod:: simgrid::s4u::Link::get_latency() const + .. autodoxymethod:: simgrid::s4u::Link::get_name() const + .. autodoxymethod:: simgrid::s4u::Link::get_sharing_policy() const + .. autodoxymethod:: simgrid::s4u::Link::get_usage() const + .. autodoxymethod:: simgrid::s4u::Link::is_used() const .. group-tab:: C @@ -1366,7 +1370,7 @@ User data and properties .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Link::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::Link::get_property(const std::string &key) const .. autodoxymethod:: simgrid::s4u::Link::set_property(const std::string &key, const std::string &value) .. group-tab:: C @@ -1383,7 +1387,7 @@ On/Off See also :cpp:func:`simgrid::s4u::Link::set_state_profile`. - .. autodoxymethod:: simgrid::s4u::Link::is_on() + .. autodoxymethod:: simgrid::s4u::Link::is_on() const .. autodoxymethod:: simgrid::s4u::Link::turn_off() .. autodoxymethod:: simgrid::s4u::Link::turn_on() @@ -1469,8 +1473,8 @@ Querying info .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::NetZone::get_cname() - .. autodoxymethod:: simgrid::s4u::NetZone::get_name() + .. autodoxymethod:: simgrid::s4u::NetZone::get_cname() const + .. autodoxymethod:: simgrid::s4u::NetZone::get_name() const .. group-tab:: C @@ -1483,8 +1487,8 @@ User data and properties .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::NetZone::get_properties() - .. autodoxymethod:: simgrid::s4u::NetZone::get_property(const std::string &key) + .. autodoxymethod:: simgrid::s4u::NetZone::get_properties() const + .. autodoxymethod:: simgrid::s4u::NetZone::get_property(const std::string &key) const .. autodoxymethod:: simgrid::s4u::NetZone::set_property(const std::string &key, const std::string &value) .. group-tab:: C @@ -1499,8 +1503,8 @@ Retrieving components .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::NetZone::get_all_hosts() - .. autodoxymethod:: simgrid::s4u::NetZone::get_host_count() + .. autodoxymethod:: simgrid::s4u::NetZone::get_all_hosts() const + .. autodoxymethod:: simgrid::s4u::NetZone::get_host_count() const .. group-tab:: C @@ -1516,7 +1520,7 @@ Routing data .. 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_children() const .. autodoxymethod:: simgrid::s4u::NetZone::get_father() .. group-tab:: C @@ -1534,12 +1538,6 @@ Signals .. autodoxyvar:: simgrid::s4u::NetZone::on_route_creation .. autodoxyvar:: simgrid::s4u::NetZone::on_seal - -.. doxygenclass:: simgrid::s4u::NetZone - :members: - :protected-members: - :undoc-members: - .. _API_s4u_VirtualMachine: ======================= @@ -1582,7 +1580,7 @@ Creating VMs .. 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() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::destroy .. group-tab:: C @@ -1597,8 +1595,8 @@ Querying info .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_pm() - .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_ramsize() + .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_pm() const + .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_ramsize() const .. autodoxymethod:: simgrid::s4u::VirtualMachine::get_state() .. autodoxymethod:: simgrid::s4u::VirtualMachine::set_bound(double bound) @@ -1665,23 +1663,48 @@ class Activity :ref:`I/O ` (started on and consumming disks). See also the :ref:`section on activities ` above. +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: ActivityPtr + Querying info ------------- - .. autodoxymethod:: simgrid::s4u::Activity::get_remaining() - .. autodoxymethod:: simgrid::s4u::Activity::get_state() - .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains) +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Activity::get_cname + .. autodoxymethod:: simgrid::s4u::Activity::get_name + .. autodoxymethod:: simgrid::s4u::Activity::get_remaining() + .. autodoxymethod:: simgrid::s4u::Activity::get_state() + .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains) + .. autodoxymethod:: simgrid::s4u::Activity::set_state(Activity::State state) + Activities life cycle --------------------- - .. autodoxymethod:: simgrid::s4u::Activity::start - .. autodoxymethod:: simgrid::s4u::Activity::cancel - .. autodoxymethod:: simgrid::s4u::Activity::test - .. 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() +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Activity::start + .. autodoxymethod:: simgrid::s4u::Activity::cancel + .. autodoxymethod:: simgrid::s4u::Activity::test + .. 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: @@ -1689,12 +1712,81 @@ Activities life cycle ⁣  class Comm ============= -.. doxygentypedef:: CommPtr +.. autodoxyclass:: simgrid::s4u::Comm + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include -.. doxygenclass:: simgrid::s4u::Comm - :members: - :protected-members: - :undoc-members: + .. doxygentypedef:: CommPtr + + .. group-tab:: Python + + .. code:: Python + + from simgrid import Comm + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Comm::get_dst_data_size() + .. autodoxymethod:: simgrid::s4u::Comm::get_mailbox() + .. autodoxymethod:: simgrid::s4u::Comm::get_sender() + .. autodoxymethod:: simgrid::s4u::Comm::set_dst_data(void **buff) + .. autodoxymethod:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size) + .. autodoxymethod:: simgrid::s4u::Comm::detach() + .. autodoxymethod:: simgrid::s4u::Comm::detach(void(*clean_function)(void *)) + .. autodoxymethod:: simgrid::s4u::Comm::set_rate(double rate) + .. autodoxymethod:: simgrid::s4u::Comm::set_src_data(void *buff) + .. autodoxymethod:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size) + .. autodoxymethod:: simgrid::s4u::Comm::set_src_data_size(size_t size) + .. autodoxymethod:: simgrid::s4u::Comm::set_tracing_category(const std::string &category) + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Comm::cancel + .. autodoxymethod:: simgrid::s4u::Comm::start + .. autodoxymethod:: simgrid::s4u::Comm::test + .. autodoxymethod:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr > *comms) + .. autodoxymethod:: simgrid::s4u::Comm::wait + .. autodoxymethod:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr > *comms) + .. autodoxymethod:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr > *comms) + .. autodoxymethod:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr > *comms_in, double timeout) + .. autodoxymethod:: simgrid::s4u::Comm::wait_for + + .. group-tab:: Python + + .. automethod:: simgrid.Comm.test + .. automethod:: simgrid.Comm.wait + .. automethod:: simgrid.Comm.wait_all + .. automethod:: simgrid.Comm.wait_any + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxyvar:: simgrid::s4u::Comm::on_completion + .. autodoxyvar:: simgrid::s4u::Comm::on_receiver_start + .. autodoxyvar:: simgrid::s4u::Comm::on_sender_start .. _API_s4u_Exec: @@ -1702,38 +1794,87 @@ Activities life cycle ⁣  class Exec ============= -.. doxygentypedef:: ExecPtr +.. autodoxyclass:: simgrid::s4u::Exec -.. doxygenclass:: simgrid::s4u::Exec - :members: - :protected-members: - :undoc-members: +Basic management +---------------- -.. _API_s4u_ExecSeq: +.. tabs:: -================== -⁣    class ExecSeq -================== + .. group-tab:: C++ -.. doxygentypedef:: ExecSeqPtr + .. code-block:: C++ -.. doxygenclass:: simgrid::s4u::ExecSeq - :members: - :protected-members: - :undoc-members: + #include -.. _API_s4u_ExecPar: + .. doxygentypedef:: ExecPtr -================== -⁣    class ExecPar -================== + .. group-tab:: Python + + .. code:: Python + + from simgrid import Exec + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Exec::get_cost() const + .. autodoxymethod:: simgrid::s4u::Exec::get_finish_time() const + .. autodoxymethod:: simgrid::s4u::Exec::get_host() const + .. autodoxymethod:: simgrid::s4u::Exec::get_host_number() const + .. cpp:function:: double Exec::get_remaining() + + On sequential executions, returns the amount of flops that remain to be done; + This cannot be used on parallel executions. + + .. autodoxymethod:: simgrid::s4u::Exec::get_remaining_ratio + .. autodoxymethod:: simgrid::s4u::Exec::get_start_time() const + .. autodoxymethod:: simgrid::s4u::Exec::set_bound(double bound) + .. autodoxymethod:: simgrid::s4u::Exec::set_host + .. autodoxymethod:: simgrid::s4u::Exec::set_priority(double priority) + + .. group-tab:: Python + + .. autoattribute:: simgrid.Exec.host + .. autoattribute:: simgrid.Exec.remaining + .. autoattribute:: simgrid.Exec.remaining_ratio + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Exec::cancel + .. autodoxymethod:: simgrid::s4u::Exec::set_timeout(double timeout) + .. autodoxymethod:: simgrid::s4u::Exec::start + .. autodoxymethod:: simgrid::s4u::Exec::test + .. autodoxymethod:: simgrid::s4u::Exec::wait + .. autodoxymethod:: simgrid::s4u::Exec::wait_any(std::vector< ExecPtr > *execs) + .. autodoxymethod:: simgrid::s4u::Exec::wait_any_for(std::vector< ExecPtr > *execs, double timeout) + .. autodoxymethod:: simgrid::s4u::Exec::wait_for + + .. group-tab:: Python -.. doxygentypedef:: ExecParPtr + .. automethod:: simgrid.Exec.cancel + .. automethod:: simgrid.Exec.start + .. automethod:: simgrid.Exec.test + .. automethod:: simgrid.Exec.wait -.. doxygenclass:: simgrid::s4u::ExecPar - :members: - :protected-members: - :undoc-members: +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + + .. cpp:var:: xbt::signal Exec::on_completion + .. cpp:var:: xbt::signal Exec::on_start .. _API_s4u_Io: @@ -1741,12 +1882,43 @@ Activities life cycle ⁣  class Io =========== -.. doxygentypedef:: IoPtr +.. autodoxyclass:: simgrid::s4u::Io + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: IoPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Io::get_performed_ioops() const + .. autodoxymethod:: simgrid::s4u::Io::get_remaining + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ -.. doxygenclass:: simgrid::s4u::Io - :members: - :protected-members: - :undoc-members: + .. autodoxymethod:: simgrid::s4u::Io::cancel + .. autodoxymethod:: simgrid::s4u::Io::start + .. autodoxymethod:: simgrid::s4u::Io::test + .. autodoxymethod:: simgrid::s4u::Io::wait + .. autodoxymethod:: simgrid::s4u::Io::wait_for .. _API_s4u_Synchronizations: @@ -1878,8 +2050,8 @@ Basic management #include .. doxygentypedef:: sg_cond_t - .. doxygenfunction:: sg_cond_init - .. doxygenfunction:: sg_cond_destroy + .. autodoxymethod:: sg_cond_init + .. autodoxymethod:: sg_cond_destroy Waiting and notifying --------------------- @@ -1904,10 +2076,10 @@ Waiting and notifying .. group-tab:: C - .. doxygenfunction:: sg_cond_notify_all - .. doxygenfunction:: sg_cond_notify_one - .. doxygenfunction:: sg_cond_wait - .. doxygenfunction:: sg_cond_wait_for + .. autodoxymethod:: sg_cond_notify_all + .. autodoxymethod:: sg_cond_notify_one + .. autodoxymethod:: sg_cond_wait + .. autodoxymethod:: sg_cond_wait_for .. _API_s4u_Semaphore: diff --git a/include/simgrid/kernel/routing/NetZoneImpl.hpp b/include/simgrid/kernel/routing/NetZoneImpl.hpp index 66c979056e..585bc78682 100644 --- a/include/simgrid/kernel/routing/NetZoneImpl.hpp +++ b/include/simgrid/kernel/routing/NetZoneImpl.hpp @@ -103,9 +103,9 @@ public: resource::NetworkModel* network_model_; s4u::NetZone* get_iface() { return &piface_; } - unsigned int get_table_size() { return vertices_.size(); } - std::vector get_vertices() { return vertices_; } - NetZoneImpl* get_father() { return father_; } + unsigned int get_table_size() const { return vertices_.size(); } + std::vector get_vertices() const { return vertices_; } + NetZoneImpl* get_father() const { return father_; } /** @brief Returns the list of direct children (no grand-children). This returns the internal data, no copy. * Don't mess with it.*/ std::vector* get_children() { return &children_; } @@ -114,8 +114,8 @@ public: /** @brief Retrieves the name of that netzone as a C string */ const char* get_cname() const { return name_.c_str(); }; - std::vector get_all_hosts(); - int get_host_count(); + std::vector get_all_hosts() const; + int get_host_count() const; /** @brief Make a host within that NetZone */ s4u::Host* create_host(const std::string& name, const std::vector& speed_per_pstate, int core_count, diff --git a/include/simgrid/s4u/Exec.hpp b/include/simgrid/s4u/Exec.hpp index 6923409004..1bd4230d97 100644 --- a/include/simgrid/s4u/Exec.hpp +++ b/include/simgrid/s4u/Exec.hpp @@ -16,8 +16,18 @@ namespace s4u { /** Computation Activity, representing the asynchronous executions. * - * They are generated from this_actor::exec_init() or Host::execute(), and can be used to model pools of threads or - * similar mechanisms. + * @rst + * Most of them are created with :cpp:func:`simgrid::s4u::this_actor::exec_init()` or + * :cpp:func:`simgrid::s4u::Host::execute()`, and represent a classical (sequential) execution. This can be used to + * simulate some computation occuring in another thread when the calling actor is not blocked during the execution. + * + * You can also use :cpp:func:`simgrid::s4u::this_actor::parallel_execute()` to create *parallel* executions. These + * objects represent distributed computations involving computations on several hosts and communications between them. + * Such objects can for example represent a matrix multiplication done with ScaLAPACK on a real system. Once created, + * parallel Exec are very similar to the sequential ones. The only difference is that you cannot migrate them, and their + * remaining amount of work can only be defined as a ratio. See the doc of :cpp:func:`simgrid::s4u::Exec::get_remaining` + * and :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio` for more info. + * @endrst */ class XBT_PUBLIC Exec : public Activity_T { double priority_ = 1.0; @@ -40,6 +50,8 @@ public: static xbt::signal on_completion; Exec* start() override = 0; + /** @brief On sequential executions, returns the amount of flops that remain to be done; This cannot be used on + * parallel executions. */ virtual double get_remaining_ratio() = 0; virtual ExecPtr set_host(Host* host) = 0; diff --git a/include/simgrid/s4u/Io.hpp b/include/simgrid/s4u/Io.hpp index 3d54e818d0..06f7e90916 100644 --- a/include/simgrid/s4u/Io.hpp +++ b/include/simgrid/s4u/Io.hpp @@ -47,7 +47,7 @@ public: bool test() override; double get_remaining() override; - sg_size_t get_performed_ioops(); + sg_size_t get_performed_ioops() const; }; } // namespace s4u diff --git a/include/simgrid/s4u/NetZone.hpp b/include/simgrid/s4u/NetZone.hpp index 3ec8c8424a..741fa71435 100644 --- a/include/simgrid/s4u/NetZone.hpp +++ b/include/simgrid/s4u/NetZone.hpp @@ -38,7 +38,7 @@ public: NetZone* get_father(); std::vector get_all_hosts() const; - int get_host_count(); + int get_host_count() const; kernel::routing::NetZoneImpl* get_impl() const { return pimpl_; } diff --git a/src/kernel/activity/IoImpl.hpp b/src/kernel/activity/IoImpl.hpp index 897cfb5177..0b885d3441 100644 --- a/src/kernel/activity/IoImpl.hpp +++ b/src/kernel/activity/IoImpl.hpp @@ -34,9 +34,9 @@ public: timeout_detector_->set_activity(this); } - sg_size_t get_performed_ioops() { return performed_ioops_; } - resource::DiskImpl* get_disk() { return disk_; } - resource::StorageImpl* get_storage() { return storage_; } + sg_size_t get_performed_ioops() const { return performed_ioops_; } + resource::DiskImpl* get_disk() const { return disk_; } + resource::StorageImpl* get_storage() const { return storage_; } IoImpl* start(); void post() override; diff --git a/src/kernel/routing/NetZoneImpl.cpp b/src/kernel/routing/NetZoneImpl.cpp index 81a638323c..5085d81410 100644 --- a/src/kernel/routing/NetZoneImpl.cpp +++ b/src/kernel/routing/NetZoneImpl.cpp @@ -44,7 +44,7 @@ NetZoneImpl::~NetZoneImpl() * Only the hosts that are directly contained in this NetZone are retrieved, * not the ones contained in sub-netzones. */ -std::vector NetZoneImpl::get_all_hosts() +std::vector NetZoneImpl::get_all_hosts() const { std::vector res; for (auto const& card : get_vertices()) { @@ -54,7 +54,7 @@ std::vector NetZoneImpl::get_all_hosts() } return res; } -int NetZoneImpl::get_host_count() +int NetZoneImpl::get_host_count() const { int count = 0; for (auto const& card : get_vertices()) { diff --git a/src/s4u/s4u_Exec.cpp b/src/s4u/s4u_Exec.cpp index a0d3cc5302..9c75bcad98 100644 --- a/src/s4u/s4u_Exec.cpp +++ b/src/s4u/s4u_Exec.cpp @@ -166,7 +166,6 @@ ExecPtr ExecSeq::set_host(Host* host) return this; } -/** @brief Returns the amount of flops that remain to be done */ double ExecSeq::get_remaining() { return kernel::actor::simcall( diff --git a/src/s4u/s4u_Io.cpp b/src/s4u/s4u_Io.cpp index 73149eb614..be9a3ad1bf 100644 --- a/src/s4u/s4u_Io.cpp +++ b/src/s4u/s4u_Io.cpp @@ -96,10 +96,9 @@ double Io::get_remaining() [this]() { return boost::static_pointer_cast(pimpl_)->get_remaining(); }); } -sg_size_t Io::get_performed_ioops() +sg_size_t Io::get_performed_ioops() const { - return kernel::actor::simcall( - [this]() { return boost::static_pointer_cast(pimpl_)->get_performed_ioops(); }); + return boost::static_pointer_cast(pimpl_)->get_performed_ioops(); } } // namespace s4u diff --git a/src/s4u/s4u_Netzone.cpp b/src/s4u/s4u_Netzone.cpp index 2e13264b4e..4fab50aa6f 100644 --- a/src/s4u/s4u_Netzone.cpp +++ b/src/s4u/s4u_Netzone.cpp @@ -67,7 +67,7 @@ std::vector NetZone::get_all_hosts() const return pimpl_->get_all_hosts(); } -int NetZone::get_host_count() +int NetZone::get_host_count() const { return pimpl_->get_host_count(); } -- 2.20.1