From dbb0053e46341918b4d5ba5ec69ddbd54c01f5de Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 2 Nov 2019 01:12:59 +0100 Subject: [PATCH] start documenting the C API in sphinx --- docs/Build.sh | 12 ++++++++++++ docs/ignored_symbols | 3 ++- docs/source/Doxyfile | 14 ++++++++++++++ docs/source/app_s4u.rst | 28 +++++++++++++++++++++++++++- docs/source/platform.rst | 4 ++-- include/simgrid/engine.h | 33 +++++++++++++++++++++++++++++++-- include/simgrid/s4u/Engine.hpp | 16 +--------------- src/s4u/s4u_Engine.cpp | 28 ++++++++++++++++++---------- 8 files changed, 107 insertions(+), 31 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index d51e6edc09..7e1e60c201 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -41,6 +41,18 @@ perl -pe 's/(xlink:href="(?:http|.*\.html))/target="_top" $1/' \ echo "List of missing references:" for f in $( (grep '' build/xml/msg_8h.xml; \ grep '' build/xml/namespacesimgrid_1_1s4u.xml; \ + grep '' build/xml/actor_8h.xml ; \ + grep '' build/xml/barrier_8h.xml ; \ + grep '' build/xml/cond_8h.xml ; \ + grep '' build/xml/engine_8h.xml ; \ + grep '' build/xml/host_8h.xml ; \ + grep '' build/xml/link_8h.xml ; \ + grep '' build/xml/mailbox_8h.xml ; \ + grep '' build/xml/msg_8h.xml ; \ + grep '' build/xml/mutex_8h.xml ; \ + grep '' build/xml/semaphore_8h.xml ; \ + grep '' build/xml/vm_8h.xml ; \ + grep '' build/xml/zone_8h.xml ; \ grep ']*>//g' | sort ) do diff --git a/docs/ignored_symbols b/docs/ignored_symbols index f8f924418b..d039c80c44 100644 --- a/docs/ignored_symbols +++ b/docs/ignored_symbols @@ -15,4 +15,5 @@ MSG_init_nocheck intrusive_ptr_release intrusive_ptr_add_ref get_filtered_netzones_recursive -simgrid::s4u::Storage \ No newline at end of file +simgrid::s4u::Storage +simgrid::s4u::Activity_T diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index 95c020c295..464237c5bc 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -2,6 +2,18 @@ INPUT = ../../include/simgrid/forward.h INPUT += ../../include/simgrid/s4u INPUT += ../../include/simgrid/msg.h +INPUT += ../../include/simgrid/actor.h +INPUT += ../../include/simgrid/barrier.h +INPUT += ../../include/simgrid/cond.h +INPUT += ../../include/simgrid/engine.h +INPUT += ../../include/simgrid/host.h +#INPUT += ../../include/simgrid/instr.h +INPUT += ../../include/simgrid/link.h +INPUT += ../../include/simgrid/mailbox.h +INPUT += ../../include/simgrid/mutex.h +INPUT += ../../include/simgrid/semaphore.h +INPUT += ../../include/simgrid/vm.h +INPUT += ../../include/simgrid/zone.h INPUT += ../../src/msg/ INPUT += ../../src/plugins/ RECURSIVE = YES @@ -31,6 +43,8 @@ SKIP_FUNCTION_MACROS = NO PREDEFINED += \ __cplusplus \ DOXYGEN \ + SG_BEGIN_DECL= \ + SG_END_DECL= \ XBT_PUBLIC= \ XBT_EXPORT_NO_IMPORT= \ XBT_IMPORT_NO_EXPORT= \ diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 885a6a932d..e422a7045a 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -601,11 +601,37 @@ s4u::VirtualMachine :protected-members: :undoc-members: +C API Reference +*************** + +============== +Main functions +============== + +.. doxygenfunction:: simgrid_init +.. doxygenfunction:: simgrid_get_clock +.. doxygenfunction:: simgrid_load_deployment +.. doxygenfunction:: simgrid_load_platform +.. doxygenfunction:: simgrid_register_default +.. doxygenfunction:: simgrid_register_function +.. doxygenfunction:: simgrid_run + +================== +Condition Variable +================== + +See also the :ref:`C++ API `. + +.. doxygenfunction:: sg_cond_init +.. doxygenfunction:: sg_cond_notify_all +.. doxygenfunction:: sg_cond_notify_one +.. doxygenfunction:: sg_cond_wait +.. doxygenfunction:: sg_cond_wait_for Python API Reference ******************** -The Python API is generated with pybind11. It closely mimicks the C++ +The Python API is automatically generated with pybind11. It closely mimicks the C++ API, to which you should refer for more information. ========== diff --git a/docs/source/platform.rst b/docs/source/platform.rst index bc020e714c..7d18c8abda 100644 --- a/docs/source/platform.rst +++ b/docs/source/platform.rst @@ -1,5 +1,3 @@ -.. _platform: - .. raw:: html @@ -12,6 +10,8 @@

+.. _platform: + Describing your Simulated Platform ################################## diff --git a/include/simgrid/engine.h b/include/simgrid/engine.h index d4caeecaa9..2add0558ae 100644 --- a/include/simgrid/engine.h +++ b/include/simgrid/engine.h @@ -8,17 +8,46 @@ #include -/* C interface */ -SG_BEGIN_DECL +SG_BEGIN_DECL /* C interface */ +/** Initialize the SimGrid engine, taking the command line parameters of your main function. */ XBT_PUBLIC void simgrid_init(int* argc, char** argv); + +/** Creates a new platform, including hosts, links, and the routing table. + * + * \rst + * See also: :ref:`platform`. + * \endrst + */ XBT_PUBLIC void simgrid_load_platform(const char* filename); +/** Load a deployment file and launch the actors that it contains + * + * \rst + * See also: :ref:`deploy`. + * \endrst + */ XBT_PUBLIC void simgrid_load_deployment(const char* filename); +/** Run the simulation after initialization */ XBT_PUBLIC void simgrid_run(); +/** Registers the main function of an actor that will be launched from the deployment file */ XBT_PUBLIC void simgrid_register_function(const char* name, int (*code)(int, char**)); +/** Registers a function as the default main function of actors + * + * It will be used as fallback when the function requested from the deployment file was not registered. + * It is used for trace-based simulations (see examples/s4u/replay-comms and similar). + */ XBT_PUBLIC void simgrid_register_default(int (*code)(int, char**)); +/** Retrieve the simulation time (in seconds) */ XBT_PUBLIC double simgrid_get_clock(); +/** @brief Allow other libraries to react to the --help flag, too + * + * When finding --help on the command line, simgrid usually stops right after displaying its help message. + * If you are writing a library using simgrid, you may want to display your own help message before everything stops. + * If so, just call this function before having simgrid parsing the command line, and you will be given the control + * even if the user is asking for help. + */ XBT_PUBLIC void sg_config_continue_after_help(); + SG_END_DECL #endif /* INCLUDE_SIMGRID_ENGINE_H_ */ diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp index ea53d1c8e4..1741d9a19c 100644 --- a/include/simgrid/s4u/Engine.hpp +++ b/include/simgrid/s4u/Engine.hpp @@ -36,7 +36,7 @@ public: /** Finalize the default engine and all its dependencies */ static void shutdown(); - /** @brief Run the simulation */ + /** @brief Run the simulation after initialization */ void run(); /** @brief Retrieve the simulation time (in seconds) */ @@ -44,23 +44,10 @@ public: /** @brief Retrieve the engine singleton */ static s4u::Engine* get_instance(); - /** @brief Load a platform file describing the environment - * - * The environment is either a XML file following the simgrid.dtd formalism, or a lua file. - * Some examples can be found in the directory examples/platforms. - */ void load_platform(const std::string& platf); - /** Registers the main function of an actor that will be launched from the deployment file */ void register_function(const std::string& name, int (*code)(int, char**)); - /** Registers the main function of an actor that will be launched from the deployment file */ void register_function(const std::string& name, void (*code)(std::vector)); - - /** Registers a function as the default main function of actors - * - * It will be used as fallback when the function requested from the deployment file was not registered. - * It is used for trace-based simulations (see examples/s4u/replay-comms and similar). - */ void register_default(int (*code)(int, char**)); template void register_actor(const std::string& name) @@ -80,7 +67,6 @@ public: }); } - /** @brief Load a deployment file and launch the actors that it contains */ void load_deployment(const std::string& deploy); protected: diff --git a/src/s4u/s4u_Engine.cpp b/src/s4u/s4u_Engine.cpp index 1d12c11bdb..8b05e049c5 100644 --- a/src/s4u/s4u_Engine.cpp +++ b/src/s4u/s4u_Engine.cpp @@ -74,16 +74,11 @@ double Engine::get_clock() } /** - * @brief A platform loader. + * Creates a new platform, including hosts, links, and the routing table. * - * Creates a new platform, including hosts, links, and the routing_table. - * @param platf a filename of the XML description of a platform. This file follows this DTD : - * - * @include src/surf/xml/simgrid.dtd - * - * Here is a small example of such a platform - * - * @include examples/platforms/small_platform.xml + * \rst + * See also: :ref:`platform`. + * \endrst */ void Engine::load_platform(const std::string& platf) { @@ -98,23 +93,36 @@ void Engine::load_platform(const std::string& platf) XBT_DEBUG("PARSE TIME: %g", (end - start)); } +/** Registers the main function of an actor that will be launched from the deployment file */ void Engine::register_function(const std::string& name, int (*code)(int, char**)) { SIMIX_function_register(name, code); } +/** Registers the main function of an actor that will be launched from the deployment file */ void Engine::register_function(const std::string& name, void (*code)(std::vector)) { SIMIX_function_register(name, code); } +/** Registers a function as the default main function of actors + * + * It will be used as fallback when the function requested from the deployment file was not registered. + * It is used for trace-based simulations (see examples/s4u/replay-comms and similar). + */ void Engine::register_default(int (*code)(int, char**)) { SIMIX_function_register_default(code); } +/** Load a deployment file and launch the actors that it contains + * + * \rst + * See also: :ref:`deploy`. + * \endrst + */ void Engine::load_deployment(const std::string& deploy) { SIMIX_launch_application(deploy); } -/** @brief Returns the amount of hosts in the platform */ +/** Returns the amount of hosts in the platform */ size_t Engine::get_host_count() { return pimpl->hosts_.size(); -- 2.20.1