From 9b4039c4e39984806de45eaa25ecb9dd1568a8bf Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Wed, 20 Jan 2021 20:49:09 +0100 Subject: [PATCH] Fix a bunch of issues with the documentation Broken links, undocumented symbols, examples that were moved around, undocumented examples... --- docs/source/app_s4u.rst | 58 ++++++++++++++++++++++++---------- examples/README.rst | 47 +++++++++++++++++++-------- include/simgrid/s4u/Engine.hpp | 8 +++-- 3 files changed, 80 insertions(+), 33 deletions(-) diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index be046e3f65..3cf6cdb6c4 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -187,7 +187,7 @@ communications ongoing. First, you have to declare a vector in which we will store the ongoing communications. It is also useful to have a vector of mailboxes. -.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp +.. literalinclude:: ../../examples/s4u/comm-waitall/s4u-comm-waitall.cpp :language: c++ :start-after: init-begin :end-before: init-end @@ -199,7 +199,7 @@ Finally, the actor waits for the completion of all of them at once with :cpp:func:`s4u::Comm::wait_all() `. -.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp +.. literalinclude:: ../../examples/s4u/comm-waitall/s4u-comm-waitall.cpp :language: c++ :start-after: put-begin :end-before: put-end @@ -317,7 +317,7 @@ announced (it waits until both :cpp:func:`put() ` and :cpp:func:`get() ` are posted). In TCP, since you establish connections beforehand, the data starts to flow as soon as the sender posts it, even if the receiver did not post -its :cpp:func:`recv() ` yet. +its :cpp:func:`put() ` yet. To model this in SimGrid, you can declare a specific receiver to a given mailbox (with the function @@ -444,6 +444,7 @@ Creating actors .. group-tab:: C + .. autodoxymethod:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, const char *const *argv) .. autodoxymethod:: sg_actor_init(const char *name, sg_host_t host) .. autodoxymethod:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, const char *const *argv) @@ -635,7 +636,7 @@ Querying info .. autodoxymethod:: simgrid::s4u::this_actor::is_maestro() .. autodoxymethod:: simgrid::s4u::this_actor::get_host() - .. autodoxymethod:: simgrid::s4u::this_actor::set_host(simgrid::s4u::Host *new_host) + .. autodoxymethod:: simgrid::s4u::this_actor::set_host(Host *new_host) .. group-tab:: Python @@ -667,6 +668,10 @@ Suspending and resuming .. autofunction:: simgrid.this_actor.suspend .. autofunction:: simgrid.this_actor.yield_ + .. group-tab:: C + + .. autodoxymethod:: sg_actor_yield() + Logging messages ---------------- @@ -724,7 +729,10 @@ the execution, or start an asynchronous activity. .. group-tab:: C - .. autodoxymethod:: sg_actor_self_execute(double flops) + .. autodoxymethod:: sg_actor_execute(double flops) + .. autodoxymethod:: sg_actor_execute_with_priority(double flops, double priority) + .. autodoxymethod:: sg_actor_exec_init(double computation_amount) + .. autodoxymethod:: sg_actor_exec_async(double computation_amount) Exiting ------- @@ -769,9 +777,12 @@ Initialization .. autodoxymethod:: simgrid::s4u::Engine::load_platform .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name) .. autodoxymethod:: simgrid::s4u::Engine::register_actor(const std::string &name, F code) - .. autodoxymethod:: simgrid::s4u::Engine::register_default(void(*code)(int, char **)) - .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(std::vector< std::string >)) - .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, void(*code)(int, char **)) + .. autodoxymethod:: simgrid::s4u::Engine::register_default(const std::function< void(int, char **)> &code) + .. autodoxymethod:: simgrid::s4u::Engine::register_default(const kernel::actor::ActorCodeFactory &factory) + + .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(int, char **)> &code) + .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(std::vector< std::string >)> &code) + .. autodoxymethod:: simgrid::s4u::Engine::register_function(const std::string &name, const kernel::actor::ActorCodeFactory &factory) .. group-tab:: Python @@ -917,6 +928,14 @@ Basic management .. automethod:: simgrid.Mailbox.by_name + .. code-block:: C + + #include + + .. autodoxymethod:: sg_mailbox_by_name(const char *alias) + + .. group-tab:: C + Querying info ------------- @@ -949,6 +968,12 @@ Sending data .. automethod:: simgrid.Mailbox.put .. automethod:: simgrid.Mailbox.put_async + .. group-tab: C + + .. autodoxymethod:: sg_mailbox_put(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes) + .. autodoxymethod:: sg_mailbox_put_init(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes) + .. autodoxymethod:: sg_mailbox_put_async(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes) + Receiving data -------------- @@ -961,7 +986,7 @@ Receiving data .. autodoxymethod:: simgrid::s4u::Mailbox::front .. autodoxymethod:: simgrid::s4u::Mailbox::get() .. autodoxymethod:: simgrid::s4u::Mailbox::get(double timeout) - .. autodoxymethod:: simgrid::s4u::Mailbox::get_async(void **data) + .. autodoxymethod:: simgrid::s4u::Mailbox::get_async(T **data) .. autodoxymethod:: simgrid::s4u::Mailbox::get_init() .. autodoxymethod:: simgrid::s4u::Mailbox::iprobe(int type, bool(*match_fun)(void *, void *, kernel::activity::CommImpl *), void *data) .. autodoxymethod:: simgrid::s4u::Mailbox::listen @@ -973,6 +998,9 @@ Receiving data .. group-tab:: C + .. autodoxymethod:: sg_mailbox_get(sg_mailbox_t mailbox) + .. autodoxymethod:: sg_mailbox_get_async(sg_mailbox_t mailbox, void **data) + .. autodoxymethod:: sg_mailbox_get_name(const_sg_mailbox_t mailbox) .. autodoxymethod:: sg_mailbox_listen(const char *alias) Receiving actor @@ -1169,7 +1197,7 @@ User data and properties .. 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_properties(const std::unordered_map< std::string, std::string > &properties) .. autodoxymethod:: simgrid::s4u::Host::set_property(const std::string &key, const std::string &value) .. group-tab:: C @@ -1187,7 +1215,7 @@ Retrieving components .. group-tab:: C++ - .. autodoxymethod:: simgrid::s4u::Host::add_disk(const Disk* disk) + .. autodoxymethod:: simgrid::s4u::Host::add_disk(const Disk *disk) .. autodoxymethod:: simgrid::s4u::Host::get_actor_count() const .. autodoxymethod:: simgrid::s4u::Host::get_all_actors() const .. autodoxymethod:: simgrid::s4u::Host::get_disks() const @@ -1377,8 +1405,8 @@ Modifying characteristics .. group-tab:: C - .. autodoxymethod:: sg_link_set_bandwidth(const_sg_link_t link, double value) - .. autodoxymethod:: sg_link_set_latency(const_sg_link_t link, double value) + .. autodoxymethod:: sg_link_set_bandwidth(sg_link_t link, double value) + .. autodoxymethod:: sg_link_set_latency(sg_link_t link, double value) User data and properties ------------------------ @@ -1790,7 +1818,6 @@ Querying info .. 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 ---------- @@ -1824,8 +1851,7 @@ Signals .. group-tab:: C++ .. autodoxyvar:: simgrid::s4u::Comm::on_completion - .. autodoxyvar:: simgrid::s4u::Comm::on_receiver_start - .. autodoxyvar:: simgrid::s4u::Comm::on_sender_start + .. autodoxyvar:: simgrid::s4u::Comm::on_start .. _API_s4u_Exec: diff --git a/examples/README.rst b/examples/README.rst index 735ca8f79c..bb40b474ea 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -78,7 +78,7 @@ Starting and Stopping Actors This example shows how to attach a callback to: - - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()` + - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()` - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()` - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()` @@ -95,7 +95,7 @@ Starting and Stopping Actors .. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`, - :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`. + :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`. .. example-tab:: examples/python/actor-kill/actor-kill.py @@ -282,6 +282,18 @@ Activities: what Actors do Communications on the Network ----------------------------- + - **Basic communications:** + This simple example just sends one message back and forth. + The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to + the simulators (as detailed in Section :ref:`options`). + + .. tabs:: + + .. example-tab:: examples/s4u/comm-pingpong/s4u-comm-pingpong.cpp + + .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c + + - **Basic asynchronous communications:** Illustrates how to have non-blocking communications, that are communications running in the background leaving the process free @@ -301,6 +313,15 @@ Communications on the Network See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`. + - **Waiting communications with timeouts:** + This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication. + + .. tabs:: + + .. example-tab:: examples/s4u/comm-waituntil/s4u-comm-waituntil.cpp + + See also :cpp:func:`simgrid::s4u::Mailbox::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`. + - **Suspending communications:** The ``suspend()`` and ``resume()`` functions allow to block the progression of a given communication for a while and then unblock it. @@ -532,13 +553,20 @@ Classical synchronization objects .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp - - **Condition variable:** + - **Condition variable: basic usage** Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects. .. tabs:: .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp + - **Condition variable: timeouts** + Shows how to specify timeouts when blocking on condition variables. + + .. tabs:: + + .. example-tab:: examples/s4u/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp + - **Mutex:** Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects. @@ -553,6 +581,8 @@ Classical synchronization objects .. example-tab:: examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp + .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c + ============================= Interacting with the Platform ============================= @@ -796,17 +826,6 @@ Larger SimGrid Examplars This section contains application examples that are somewhat larger than the previous examples. - - **Ping Pong:** - This simple example just sends one message back and forth. - The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to - the simulators (as detailed in Section :ref:`options`). - - .. tabs:: - - .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp - - .. example-tab:: examples/c/app-pingpong/app-pingpong.c - - **Token ring:** Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant. diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp index f92b9a3680..8e7a74b5b2 100644 --- a/include/simgrid/s4u/Engine.hpp +++ b/include/simgrid/s4u/Engine.hpp @@ -48,18 +48,20 @@ public: void load_platform(const std::string& platf) const; +#ifndef DOXYGEN XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_function( const std::string& name, int (*code)(int, char**)); + XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_default( + int (*code)(int, char**)); +#endif void register_function(const std::string& name, const std::function& code); void register_function(const std::string& name, const std::function)>& code); + void register_function(const std::string& name, const kernel::actor::ActorCodeFactory& factory); - XBT_ATTRIB_DEPRECATED_v330("Please change the return code of your actors to void") void register_default( - int (*code)(int, char**)); void register_default(const std::function& code); void register_default(const kernel::actor::ActorCodeFactory& factory); - void register_function(const std::string& name, const kernel::actor::ActorCodeFactory& factory); template void register_actor(const std::string& name) { kernel::actor::ActorCodeFactory code_factory = [](std::vector args) { -- 2.20.1