From d09b6d83ee00344fd67cfdc6895fe46f41ee37f6 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 21 May 2016 07:21:41 +0200 Subject: [PATCH 1/1] shuffle a bit the MSG and SimDag documentation --- doc/Doxyfile.in | 2 +- doc/Layout.xml | 2 +- doc/doxygen/module-index.doc | 26 +----------------- doc/doxygen/module-msg.doc | 21 ++++++--------- doc/doxygen/module-sd.doc | 52 ++++++++++++++++++++---------------- doc/doxygen/module-xbt.doc | 2 +- examples/msg/README.doc | 1 - include/simgrid/simdag.h | 48 +++++++++++++-------------------- include/xbt/file.h | 2 +- src/simdag/sd_global.cpp | 4 +-- 10 files changed, 62 insertions(+), 98 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index e33acbee36..fce8f59ed8 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -665,9 +665,9 @@ INPUT = doxygen/index.doc \ doxygen/tracing.doc \ doxygen/FAQ.doc \ doxygen/module-msg.doc \ + doxygen/module-sd.doc \ doxygen/module-index.doc \ doxygen/module-xbt.doc \ - doxygen/module-sd.doc \ doxygen/module-surf.doc \ doxygen/module-simix.doc \ doxygen/module-smpi.doc \ diff --git a/doc/Layout.xml b/doc/Layout.xml index 6ed5725b3b..b34e45100a 100644 --- a/doc/Layout.xml +++ b/doc/Layout.xml @@ -115,7 +115,7 @@ - + diff --git a/doc/doxygen/module-index.doc b/doc/doxygen/module-index.doc index f02e254a45..607bd988a0 100644 --- a/doc/doxygen/module-index.doc +++ b/doc/doxygen/module-index.doc @@ -1,34 +1,10 @@ -/** \defgroup SD_API SimDag - \brief Programming environment for DAG applications - - SimDag provides some functionnalities to simulate parallel task scheduling - with DAGs models (Direct Acyclic Graphs). - The old versions of SimGrid were based on DAGs. But the DAG part (named SG) - was removed in SimGrid 3 because the new kernel (\ref SURF_API) was implemented. \ref SURF_API - was much faster and more flexible than SG and did not use DAGs. - SimDag is a new implementation of DAGs handling and it is built on top of \ref SURF_API. - - \section SD_who Who should use this (and who shouldn't) - - You should use this programming environment of the SimGrid suite if you want - to study algorithms and heuristics with DAGs of parallel tasks. - If you don't need to use DAGs for your simulation, have a look at the - \ref MSG_API programming environment. - If you want to study an existing MPI program, have a look at the - \ref SMPI_API one. - If none of those programming environments fits your needs, you may - consider implementing your own directly on top of \ref SURF_API (but you - probably want to contact us before). -*/ - /** \defgroup SMPI_API SMPI \brief Programming environment for the simulation of MPI applications */ - /** @defgroup XBT_API XBT -@brief The core toolbox of SimGrid, containing usefull datatypes and friends +@brief The core toolbox of SimGrid, containing useful datatypes and friends */ /** diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index 1636eb9324..6212e569cb 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -34,7 +34,7 @@ may want to use one of the following: /** @defgroup msg_simulation Main MSG simulation Functions @ingroup MSG_API -@brief Describes how to setup and control your simulation. +@brief How to setup and control your simulation. The basic workflow is the following (check the \ref MSG_examples for details). @@ -56,20 +56,18 @@ details). /** @defgroup m_host_management Host Management Functions * @ingroup MSG_API - * @brief This section describes the host structure of MSG + * @brief Host structure of MSG */ /** @defgroup m_task_management Task Management Functions * @ingroup MSG_API - * @brief This section describes the task structure of MSG - * (#msg_task_t) and the functions for managing it. See + * @brief Task structure of MSG (#msg_task_t) and associated functions. See * \ref msg_task_usage to see how to put the tasks in action. */ /** @defgroup msg_mailbox_management Mailbox Management Functions * @ingroup MSG_API - * @brief This section describes the mailbox structure of MSG - * (#msg_mailbox_t) and the functions for managing it. + * @brief Mailbox structure of MSG (#msg_mailbox_t) and associated functions. */ /** @defgroup msg_task_usage Task Actions @@ -80,15 +78,14 @@ details). /** @defgroup msg_synchro Explicit Synchronization Functions * @ingroup MSG_API - * @brief This section describes several explicit synchronization - * mechanisms existing in MSG: semaphores (#msg_sem_t) and friends. + * @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends. * * In some situations, these things are very helpful to synchronize processes without message exchanges. */ /** @defgroup msg_VMs VMs * @ingroup MSG_API - * @brief This section describes the interface created to mimic IaaS clouds. + * @brief Interface created to mimic IaaS clouds. * * With it, you can create virtual machines to put your processes * into, and interact directly with the VMs to manage groups of @@ -105,14 +102,12 @@ details). /** @defgroup msg_storage_management Storage Management Functions * @ingroup MSG_API - * @brief This section describes the storage structure of MSG - * (#msg_storage_t) and the functions for managing it. It - * is based on POSIX functions. + * @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX. */ /** @defgroup msg_file File Management Functions @ingroup MSG_API - @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX file handling. + @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX. */ /** diff --git a/doc/doxygen/module-sd.doc b/doc/doxygen/module-sd.doc index 1a687db41c..0bb49538cf 100644 --- a/doc/doxygen/module-sd.doc +++ b/doc/doxygen/module-sd.doc @@ -1,27 +1,33 @@ -/** @addtogroup SD_API +/** @defgroup SD_API SimDag for DAG applications + @brief Programming environment for DAG applications - \section SD_func Offered functionnalities - - \ref SD_datatypes_management - - \ref SD_workstation_management - - \ref SD_link_management - - \ref SD_task_management - - \ref SD_task_dependency_management - - \ref SD_simulation +SimDag provides functionnalities to simulate parallel task scheduling +arranged in DAGs (Direct Acyclic Graphs). Only centralized algorithms +can be expressed with SimDag; consider using @ref MSG_API "MSG" for +distributed algorithms). +SimDag is the oldest interface in SimGrid, even if it was temporarly +removed when the new superfast kernel was added in SimGrid v3.0. + + @{ + + @defgroup SD_host_api Hosts + @brief Host management + + @defgroup SD_link_api Links + @brief Link management + + @defgroup SD_task_api Tasks + @brief Task management + + @defgroup SD_task_dependency_api Tasks dependencies + @brief Functions to specify the dependencies between tasks + + @defgroup SD_storage_api Storages + @brief Storage management + + @defgroup SD_simulation Simulation + @brief Functions to create the environment and launch the simulation + @} */ -/** @defgroup SD_datatypes_management SD Data Types - @ingroup SD_API - @brief This section describes the different datatypes provided by SD. - */ -/** @addtogroup SD_datatypes_management */ -/** \addtogroup SD_workstation_management - \ingroup SD_API */ -/** \addtogroup SD_link_management - \ingroup SD_API */ -/** \addtogroup SD_task_management - \ingroup SD_API */ -/** \addtogroup SD_task_dependency_management - \ingroup SD_API */ -/** \addtogroup SD_simulation - \ingroup SD_API */ diff --git a/doc/doxygen/module-xbt.doc b/doc/doxygen/module-xbt.doc index 30df3723e7..14273f6fb9 100644 --- a/doc/doxygen/module-xbt.doc +++ b/doc/doxygen/module-xbt.doc @@ -27,7 +27,7 @@ @{ */ /** @defgroup XBT_grounding Grounding features */ /** @defgroup XBT_adt Usual data structures */ - /** @defgroup XBT_misc Misc general purposes library components */ + /** @defgroup XBT_misc Miscellaneous */ /** @} */ diff --git a/examples/msg/README.doc b/examples/msg/README.doc index db0ce0d273..57baa42e16 100644 --- a/examples/msg/README.doc +++ b/examples/msg/README.doc @@ -269,7 +269,6 @@ top of the example file). /** -@defgroup MSG_ex_examples ignored @example examples/msg/app-pingpong/app-pingpong.c @example examples/msg/app-token-ring/app-token-ring.c @example examples/msg/app-masterworker/app-masterworker.c diff --git a/include/simgrid/simdag.h b/include/simgrid/simdag.h index 2546414690..77f9ea6eee 100644 --- a/include/simgrid/simdag.h +++ b/include/simgrid/simdag.h @@ -17,29 +17,26 @@ SG_BEGIN_DECL() -/** @brief Link datatype - @ingroup SD_datatypes_management +/** @brief Link opaque datatype + @ingroup SD_link_api A link is a network node represented as a name, a bandwidth and a latency. - A route is a list of links between two workstations. - - @see SD_link_management */ + A route is a list of links between two hosts. + */ typedef Link *SD_link_t; -/** @brief Task datatype - @ingroup SD_datatypes_management +/** @brief Task opaque datatype + @ingroup SD_task_api A task is some computing amount that can be executed in parallel on several hosts. A task may depend on other tasks, which means that the task cannot start until the other tasks are done. Each task has a \ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... - @see SD_task_management */ + */ typedef struct SD_task *SD_task_t; /** @brief Task states - @ingroup SD_datatypes_management - - @see SD_task_management */ + @ingroup SD_task_api */ typedef enum { SD_NOT_SCHEDULED = 0, /**< @brief Initial state (not valid for SD_watch and SD_unwatch). */ SD_SCHEDULABLE = 0x0001, /**< @brief A task becomes SD_SCHEDULABLE as soon as its dependencies are satisfied */ @@ -52,9 +49,7 @@ typedef enum { } e_SD_task_state_t; /** @brief Task kinds - @ingroup SD_datatypes_management - - @see SD_task_management */ + @ingroup SD_task_api */ typedef enum { SD_TASK_NOT_TYPED = 0, /**< @brief no specified type */ SD_TASK_COMM_E2E = 1, /**< @brief end to end communication */ @@ -64,21 +59,16 @@ typedef enum { } e_SD_task_kind_t; /** @brief Storage datatype - @ingroup SD_datatypes_management - - @see SD_storage_management */ + @ingroup SD_storage_api */ typedef xbt_dictelm_t SD_storage_t; /************************** Workstation handling ****************************/ -/** @defgroup sg_host_management Hosts - * @brief Functions for managing the Hosts - * - * This section describes the functions for managing the hosts. +/** @addtogroup SD_host_api * * A host is a place where a task can be executed. * A host is represented as a physical resource with computing capabilities and has a name. * - * The hosts are created when you call the function SD_create_environment. + * The hosts are created from the description file when you call the function SD_create_environment. * * @see sg_host_t * @{ @@ -93,7 +83,7 @@ XBT_PUBLIC(const char*) SD_storage_get_host(SD_storage_t storage); /** @} */ /************************** Task handling ************************************/ -/** @defgroup SD_task_management Tasks +/** @defgroup SD_task_api Tasks * @brief Functions for managing the tasks * * This section describes the functions for managing the tasks. @@ -102,7 +92,7 @@ XBT_PUBLIC(const char*) SD_storage_get_host(SD_storage_t storage); * A task may depend on other tasks, which means that the task cannot start until the other tasks are done. * Each task has a \ref e_SD_task_state_t "state" indicating whether the task is scheduled, running, done, ... * - * @see SD_task_t, SD_task_dependency_management + * @see SD_task_t, @see SD_task_dependency_api * @{ */ XBT_PUBLIC(SD_task_t) SD_task_create(const char *name, void *data, double amount); @@ -155,12 +145,11 @@ XBT_PUBLIC(void) SD_task_schedulel(SD_task_t task, int count, ...); /** @} */ -/** @defgroup SD_task_dependency_management Tasks dependencies - * @brief Functions for managing the task dependencies - * +/** @addtogroup SD_task_dependency_api + * * This section describes the functions for managing the dependencies between the tasks. * - * @see SD_task_management + * @see SD_task_api * @{ */ XBT_PUBLIC(void) SD_task_dependency_add(const char *name, void *data, SD_task_t src, SD_task_t dst); @@ -171,8 +160,7 @@ XBT_PUBLIC(int) SD_task_dependency_exists(SD_task_t src, SD_task_t dst); /** @} */ /************************** Global *******************************************/ -/** @defgroup SD_simulation Simulation - * @brief Functions for creating the environment and launching the simulation +/** @addtogroup SD_simulation Simulation * * This section describes the functions for initializing SimDag, launching the simulation and exiting SimDag. * diff --git a/include/xbt/file.h b/include/xbt/file.h index a907eaad60..8f6941a540 100644 --- a/include/xbt/file.h +++ b/include/xbt/file.h @@ -19,7 +19,7 @@ SG_BEGIN_DECL() /** @defgroup XBT_file File manipulation functions - * @ingroup XBT + * @ingroup XBT_misc * * This module redefine some quite classical functions such as xbt_getline() or xbt_dirname() for the platforms * lacking them. diff --git a/src/simdag/sd_global.cpp b/src/simdag/sd_global.cpp index 20476dcd06..4c22ce617b 100644 --- a/src/simdag/sd_global.cpp +++ b/src/simdag/sd_global.cpp @@ -75,11 +75,11 @@ void SD_config(const char *key, const char *value){ /** * \brief Creates the environment * - * The environment (i.e. the \ref sg_host_management "hosts" and the \ref SD_link_management "links") is created with + * The environment (i.e. the \ref SD_host_api "hosts" and the \ref SD_link_api "links") is created with * the data stored in the given XML platform file. * * \param platform_file name of an XML file describing the environment to create - * \see sg_host_management, SD_link_management + * \see SD_host_api, SD_link_api * * The XML file follows this DTD: * -- 2.20.1