From 130ebf7e744bbad1687a85f67fdb80a2b4f2734c Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 11 Nov 2019 01:17:00 +0100 Subject: [PATCH] further API doc improvement --- docs/find-missing.py | 18 ++-- docs/source/app_s4u.rst | 106 ++++++++++++++------- include/simgrid/kernel/resource/Action.hpp | 9 +- include/simgrid/s4u/Activity.hpp | 13 +-- include/simgrid/s4u/Actor.hpp | 2 +- include/simgrid/s4u/Barrier.hpp | 5 +- include/simgrid/s4u/ConditionVariable.hpp | 3 + 7 files changed, 95 insertions(+), 61 deletions(-) diff --git a/docs/find-missing.py b/docs/find-missing.py index 02a18d1f67..4e1afee8bf 100755 --- a/docs/find-missing.py +++ b/docs/find-missing.py @@ -22,7 +22,7 @@ import xml.etree.ElementTree as ET import inspect xml_files = [ -# 'build/xml/classsimgrid_1_1s4u_1_1Activity.xml', + 'build/xml/classsimgrid_1_1s4u_1_1Activity.xml', 'build/xml/classsimgrid_1_1s4u_1_1Actor.xml', 'build/xml/classsimgrid_1_1s4u_1_1Barrier.xml', 'build/xml/classsimgrid_1_1s4u_1_1Comm.xml', @@ -113,7 +113,7 @@ for kind in python_decl: # Dump the missing ones for kind in python_decl: for fullname in python_decl[kind]: - print("Missing decl: .. auto{}:: {}".format(kind, fullname)) + print(" .. auto{}:: {}".format(kind, fullname)) ################ And now deal with Doxygen declarations ################ @@ -122,7 +122,7 @@ doxy_funs = {} # {classname: {func_name: [args]} } doxy_vars = {} # {classname: [names]} # find the declarations in the XML files -for arg in xml_files[:1]: +for arg in xml_files[:3]: if arg[-4:] != '.xml': print ("Argument '{}' does not end with '.xml'".format(arg)) continue @@ -192,12 +192,12 @@ with os.popen('grep autodoxyvar:: source/*rst|sed \'s/^.*autodoxyvar:: //\'') as del doxy_vars[klass] # Dump the undocumented Doxygen declarations -for obj in doxy_funs: - for meth in doxy_funs[obj]: - for args in doxy_funs[obj][meth]: - print("Missing decl: .. autodoxymethod:: {}::{}{}".format(obj, meth, args)) +for obj in sorted(doxy_funs): + for meth in sorted(doxy_funs[obj]): + for args in sorted(doxy_funs[obj][meth]): + print(".. autodoxymethod:: {}::{}{}".format(obj, meth, args)) for obj in doxy_vars: - for meth in doxy_vars[obj]: - print("Missing decl: .. autodoxyvar:: {}::{}".format(obj, meth)) + for meth in sorted(doxy_vars[obj]): + print(".. autodoxyvar:: {}::{}".format(obj, meth)) diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 4ad60bd808..46f3d92c89 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -66,58 +66,58 @@ provides many helper functions to simplify the code of actors. - **Global Classes** - - :ref:`class s4u::Actor `: + - :ref:`class Actor `: Active entities executing your application. - - :ref:`class s4u::Engine ` + - :ref:`class Engine ` Simulation engine (singleton). - - :ref:`class s4u::Mailbox ` + - :ref:`class Mailbox ` Communication rendez-vous. - **Platform Elements** - - :ref:`class s4u::Disk ` + - :ref:`class Disk ` Resource on which actors can write and read data. - - :ref:`class s4u::Host `: + - :ref:`class Host `: Actor location, providing computational power. - - :ref:`class s4u::Link ` + - :ref:`class Link ` Interconnecting hosts. - - :ref:`class s4u::NetZone `: + - :ref:`class NetZone `: Sub-region of the platform, containing resources (Hosts, Links, etc). - - :ref:`class s4u::VirtualMachine `: + - :ref:`class VirtualMachine `: Execution containers that can be moved between Hosts. -- **Activities** (:ref:`class s4u::Activity `): +- **Activities** (:ref:`class Activity `): The things that actors can do on resources - - :ref:`class s4u::Comm ` + - :ref:`class Comm ` Communication activity, started on Mailboxes and consuming links. - - :ref:`class s4u::Exec ` + - :ref:`class Exec ` Computation activity, started on Host and consuming CPU resources. - - :ref:`class s4u::Io ` + - :ref:`class Io ` I/O activity, started on and consumming disks. - **Synchronization Mechanisms**: Classical IPC that actors can use - - :ref:`class s4u::Barrier ` - - :ref:`class s4u::ConditionVariable ` - - :ref:`class s4u::Mutex ` - - :ref:`class s4u::Semaphore ` + - :ref:`class Barrier ` + - :ref:`class ConditionVariable ` + - :ref:`class Mutex ` + - :ref:`class Semaphore ` .. |API_s4u_Actors| replace:: **Actors** -.. _API_s4u_Actors: #s4u-actor +.. _API_s4u_Actors: #api-s4u-actor .. |API_s4u_Activities| replace:: **Activities** -.. _API_s4u_Activities: #s4u-activity +.. _API_s4u_Activities: #api-s4u-activity .. |API_s4u_Hosts| replace:: **Hosts** -.. _API_s4u_Hosts: #s4u-host +.. _API_s4u_Hosts: #api-s4u-host .. |API_s4u_Links| replace:: **Links** -.. _API_s4u_Links: #s4u-link +.. _API_s4u_Links: #api-s4u-link .. |API_s4u_Disks| replace:: **Disks** -.. _API_s4u_Disks: #s4u-disk +.. _API_s4u_Disks: #api-s4u-disk .. |API_s4u_VirtualMachine| replace:: **VirtualMachines** @@ -138,12 +138,16 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Mutex| replace:: **Mutex** +.. _s4u_Activities: + Activities ********** Activities represent the actions that consume a resource, such as a -:ref:`s4u::Comm ` that consumes the *transmitting power* of -:ref:`s4u::Link ` resources. +:ref:`Comm ` that consumes the *transmitting power* of +:ref:`Link ` resources, or an :ref:`Exec ` +that consumes the *computing power* of :ref:`Host ` resources. +See also the :ref:`full API ` below. ======================= Asynchronous Activities @@ -384,14 +388,36 @@ Static methods working on the current actor (see :ref:`API_s4u_Actor`). .. _API_s4u_Activity: -============= -s4u::Activity -============= +============== +class Activity +============== + +.. autodoxyclass:: simgrid::s4u::Activity + + **Known subclasses:** + :ref:`Communications ` (started on Mailboxes and consuming links), + :ref:`Executions ` (started on Host and consuming CPU resources) + :ref:`I/O ` (started on and consumming disks). + See also the :ref:`section on activities ` above. + +Querying info about activities +------------------------------ + + .. 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 +-------------------- + + .. autodoxymethod:: simgrid::s4u::Activity::cancel + .. autodoxymethod:: simgrid::s4u::Activity::start + .. 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) -.. doxygenclass:: simgrid::s4u::Activity - :members: - :protected-members: - :undoc-members: .. _API_s4u_Actor: @@ -545,16 +571,22 @@ Signals .. _API_s4u_Barrier: -============ -s4u::Barrier -============ +============= +class Barrier +============= .. doxygentypedef:: BarrierPtr -.. doxygenclass:: simgrid::s4u::Barrier - :members: - :protected-members: - :undoc-members: +.. autodoxyclass:: simgrid::s4u::Barrier + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Barrier::Barrier(unsigned int count) + .. autodoxymethod:: simgrid::s4u::Barrier::create(unsigned int expected_actors) + .. autodoxymethod:: simgrid::s4u::Barrier::wait() + .. _API_s4u_Comm: diff --git a/include/simgrid/kernel/resource/Action.hpp b/include/simgrid/kernel/resource/Action.hpp index 2821e7f5c6..00ae0df8de 100644 --- a/include/simgrid/kernel/resource/Action.hpp +++ b/include/simgrid/kernel/resource/Action.hpp @@ -47,7 +47,14 @@ public: /** @details An action is a consumption on a resource (e.g.: a communication for the network). * * It is related (but still different) from activities, that are the stuff on which an actor can be blocked. - * See simgrid::s4u::Activity for more details. + * + * - A sequential execution activity encompasses 2 actions: one for the exec itself, + * and a time-limited sleep used as timeout detector. + * - A point-to-point communication activity encompasses 3 actions: one for the comm itself + * (which spans on all links of the path), and one infinite sleep used as failure detector + * on both sender and receiver hosts. + * - Synchronization activities may possibly be connected to no action. + */ class XBT_PUBLIC Action { friend ActionHeap; diff --git a/include/simgrid/s4u/Activity.hpp b/include/simgrid/s4u/Activity.hpp index b846b3c90f..c7bc18d08c 100644 --- a/include/simgrid/s4u/Activity.hpp +++ b/include/simgrid/s4u/Activity.hpp @@ -19,16 +19,6 @@ namespace s4u { * * This class is the ancestor of every activities that an actor can undertake. * That is, activities are all the things that do take time to the actor in the simulated world. - * - * They are somewhat linked but not identical to simgrid::kernel::resource::Action, - * that are stuff occurring on a resource: - * - * - A sequential execution activity encompasses 2 actions: one for the exec itself, - * and a time-limited sleep used as timeout detector. - * - A point-to-point communication activity encompasses 3 actions: one for the comm itself - * (which spans on all links of the path), and one infinite sleep used as failure detector - * on both sender and receiver hosts. - * - Synchronization activities may possibly be connected to no action. */ class XBT_PUBLIC Activity { friend Comm; @@ -86,8 +76,7 @@ public: * It is forbidden to change the amount of work once the Activity is started */ Activity* set_remaining(double remains); - /** Put some user data onto the Activity */ - + /** Returns the internal implementation of this Activity */ kernel::activity::ActivityImpl* get_impl() const { return pimpl_.get(); } private: diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 210d2526c3..d0b6d4c091 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -28,7 +28,7 @@ namespace s4u { * You can think of an actor as a process in your distributed application, or as a thread in a multithreaded program. * This is the only component in SimGrid that actually does something on its own, executing its own code. * A resource will not get used if you don't schedule activities on them. This is the code of Actors that create and - * schedule these activities. Please refer to the :ref:`examples ` for more information. + * schedule these activities. **Please refer to the** :ref:`examples ` **for more information.** * * This API is strongly inspired from the C++11 threads. * The `documentation of this standard `_ diff --git a/include/simgrid/s4u/Barrier.hpp b/include/simgrid/s4u/Barrier.hpp index 6a2dcb7a9d..db8e05e830 100644 --- a/include/simgrid/s4u/Barrier.hpp +++ b/include/simgrid/s4u/Barrier.hpp @@ -29,14 +29,17 @@ private: std::atomic_int_fast32_t refcount_{0}; public: + /** Creates a barrier for the given amount of actors */ explicit Barrier(unsigned int count); - ~Barrier() = default; #ifndef DOXYGEN + ~Barrier() = default; Barrier(Barrier const&) = delete; Barrier& operator=(Barrier const&) = delete; #endif + /** Creates a barrier for the given amount of actors */ static BarrierPtr create(unsigned int expected_actors); + /** Blocks into the barrier. Every waiting actors will be unlocked once the expected amount of actors reaches the barrier */ int wait(); #ifndef DOXYGEN diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp index f11df5c7a7..946a2d53a7 100644 --- a/include/simgrid/s4u/ConditionVariable.hpp +++ b/include/simgrid/s4u/ConditionVariable.hpp @@ -30,11 +30,14 @@ private: public: explicit ConditionVariable(kernel::activity::ConditionVariableImpl* cond) : cond_(cond) {} + +#ifndef DOXYGEN ConditionVariable(ConditionVariable const&) = delete; ConditionVariable& operator=(ConditionVariable const&) = delete; friend XBT_PUBLIC void intrusive_ptr_add_ref(ConditionVariable * cond); friend XBT_PUBLIC void intrusive_ptr_release(ConditionVariable * cond); +#endif static ConditionVariablePtr create(); -- 2.20.1