From a379d5f99cd15cf485f80ea5ec45e884d16a6bb8 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Wed, 15 Jun 2016 22:49:19 +0200 Subject: [PATCH 1/1] start including S4U in the doc --- doc/Doxyfile.in | 1 + doc/doxygen/index.doc | 1 + doc/doxygen/inside_extending.doc | 6 +- doc/doxygen/module-s4u.doc | 131 +++++++++++++++++++++++++++++++ include/simgrid/s4u/actor.hpp | 75 +++++++++++------- tools/cmake/DefinePackages.cmake | 1 + 6 files changed, 185 insertions(+), 30 deletions(-) create mode 100644 doc/doxygen/module-s4u.doc diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index a935ef6176..bde45d237c 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -678,6 +678,7 @@ INPUT = doxygen/index.doc \ doxygen/module-sd.doc \ doxygen/module-index.doc \ doxygen/module-xbt.doc \ + doxygen/module-s4u.doc \ doxygen/module-surf.doc \ doxygen/module-simix.doc \ doxygen/module-smpi.doc \ diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index e63863b48d..b68602d0f3 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -14,6 +14,7 @@ - @subpage install - @subpage install_yours - @subpage application + - @subpage s4u_API - @subpage MSG_API - @subpage SD_API - @subpage SMPI_API diff --git a/doc/doxygen/inside_extending.doc b/doc/doxygen/inside_extending.doc index efb30072e5..9c7466e9b7 100644 --- a/doc/doxygen/inside_extending.doc +++ b/doc/doxygen/inside_extending.doc @@ -1,5 +1,5 @@ -/*! -\page inside_extending Extending SimGrid +/** +@page inside_extending Extending SimGrid \tableofcontents @@ -174,3 +174,5 @@ define a new section which will be replace by a "ifdef" in the generated code. You should not do something like that. Please work instead to make XML avoidable, ie to make the C++ interface nice and usable. + +*/ \ No newline at end of file diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc new file mode 100644 index 0000000000..2488d1d14b --- /dev/null +++ b/doc/doxygen/module-s4u.doc @@ -0,0 +1,131 @@ +/** +@defgroup s4u_api S4U: Next Generation SimGrid API +@brief Future core API, mixing the full power of SimGrid to the power of C++. + +The S4U API is currently under heavy work, but will eventually +deprecate the MSG and SimDag APIs. Everything that you can do in +SimGrid will be possible in S4U. + +@warning S4U is not ready for public use yet. You should not go + that path unless you know what you are doing. If unsure, + proceed to @ref MSG_API instead. + +@section s4u_funct Offered functionalities + +Unsurprisingly, the S4U interface matches the concepts presented in +@ref starting_components "the introduction": + + - @ref s4u_actor + +*/ + - \ref msg_simulation + - \ref m_process_management + - \ref m_host_management + - \ref m_task_management + - \ref msg_mailbox_management + - @ref msg_file + - \ref msg_task_usage + - \ref msg_VMs + - \ref msg_synchro + - \ref msg_trace_driven + - \ref MSG_examples + +@defgroup msg_simulation Main MSG simulation Functions +@ingroup MSG_API +@brief How to setup and control your simulation. + +The basic workflow is the following (check the \ref MSG_examples for +details). + + -# Initialize the library with #MSG_init + -# Create a platform (usually by parsing a file with + #MSG_create_environment) + -# Register the functions that your processes are supposed to run with + #MSG_function_register (and maybe #MSG_function_register_default) + -# Launch your processes from a deployment file with #MSG_launch_application + -# Run the simulation with #MSG_main +* + +** @defgroup m_process_management Process Management Functions + * @ingroup MSG_API + * @brief This section describes the process structure of MSG + * (#msg_process_t) and the functions for managing it. + */ + +** @defgroup m_host_management Host Management Functions + * @ingroup MSG_API + * @brief Host structure of MSG + * + +** @defgroup m_task_management Task Management Functions + * @ingroup MSG_API + * @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 Mailbox structure of MSG (#msg_mailbox_t) and associated functions. + * + +** @defgroup msg_task_usage Task Actions + * @ingroup MSG_API + * @brief This section describes the functions that can be used + * by a process to execute, communicate or otherwise handle some task. + * + +** @defgroup msg_synchro Explicit Synchronization Functions + * @ingroup MSG_API + * @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 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 + * processes. + * + * This interface is highly experimental at this point. Testing is + * welcomed, but do not expect too much of it right now. Even the + * interfaces may be changed in future releases of SimGrid (although + * things are expected to stabilize nicely before SimGrid v3.8). + * There is no guaranty on the rest of SimGrid, and there is less + * than that on this part. + * + * + +** @defgroup msg_storage_management Storage Management Functions + * @ingroup MSG_API + * @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. +* + +** +@defgroup msg_trace_driven Trace-driven simulations +@ingroup MSG_API +@brief This section describes the functions allowing to build trace-driven simulations. + +This is very handy when you want to test an algorithm or protocol that +does nothing unless it receives some events from outside. For example, +a P2P protocol reacts to requests from the user, but does nothing if +there is no such event. + +In such situations, SimGrid allows to write your protocol in your C +file, and the events to react to in a separate text file. Declare a +function handling each of the events that you want to accept in your +trace files, register them using #xbt_replay_action_register in your main, +and then use #MSG_action_trace_run to launch the simulation. You can +either have one trace file containing all your events, or a file per +simulated process. + +Check the examples in examples/msg/actions/actions.c for details. + + * diff --git a/include/simgrid/s4u/actor.hpp b/include/simgrid/s4u/actor.hpp index f479cf5144..fbb3112fd0 100644 --- a/include/simgrid/s4u/actor.hpp +++ b/include/simgrid/s4u/actor.hpp @@ -1,4 +1,4 @@ -/* Copyright (c) 2006-2015. The SimGrid Team. All rights reserved. */ +/* Copyright (c) 2006-2016. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ @@ -14,32 +14,59 @@ namespace simgrid { namespace s4u { -/** @brief Simulation Agent - * - * An actor may be defined as a code executing in a location (host). - * - * All actors should be started from the XML deployment file (using the @link{s4u::Engine::loadDeployment()}), - * even if you can also start new actors directly. - * Separating the deployment in the XML from the logic in the code is a good habit as it makes your simulation easier - * to adapt to new settings. +/** @defgroup s4u_actor Actors: simulation agents + * @addtogroup S4U_API + */ + +/** @addtogroup s4u_actor + * + * @tableofcontents + * + * An actor is an independent stream of execution in your distributed application. * - * The code that you define for a given actor should be placed in the main method that is virtual. + * 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. + * + * An actor is located on a (simulated) host, but it can interact + * with the whole simulated platform. + * + * (back to the @ref s4u_api "S4U documentation") + * + * @section s4u_actor_def Defining an Actor + * + * The code of an actor (ie, the code that this actor will run when starting) the () operator. + * In this code, your actor can use the functions of the simgrid::s4u::this_actor namespace to interact with the world. + * * For example, a Worker actor should be declared as follows: * - * \verbatim + * \code{.cpp} * #include "s4u/actor.hpp" * * class Worker { - * void operator()() { + * void operator()() { // Two pairs of () because this defines the method called () * printf("Hello s4u"); - * return 0; + * simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops * } * }; + * \endcode + * + * @section s4u_actor_new Creating a new instance of your Actor + * + * // Then later in your main() function or so: + * ... + * new Actor("worker", host, Worker()); + * ... * - * new Actor("worker", host, Worker()); - * \endverbatim - * + * You can start your actors with simple @c new, for example from the @c main function, + * but this is usually considered as a bad habit as it makes it harder to test your application + * in differing settings. Instead, you are advised to use an XML deployment file using + * s4u::Engine::loadDeployment() to start your actors. + * + * @{ */ + +/** @brief Simulation Agent (see \ref s4u_actor)*/ XBT_PUBLIC_CLASS Actor { explicit Actor(smx_process_t smx_proc); public: @@ -93,10 +120,9 @@ private: smx_process_t pimpl_ = nullptr; }; +/** @brief Static methods working on the current actor (see @ref s4u_actor) */ namespace this_actor { - // Static methods working on the current actor: - /** Block the actor sleeping for that amount of seconds (may throws hostFailure) */ XBT_PUBLIC(void) sleep(double duration); @@ -117,16 +143,9 @@ namespace this_actor { }; -}} // namespace simgrid::s4u +/** @} */ -#endif /* SIMGRID_S4U_ACTOR_HPP */ +}} // namespace simgrid::s4u -#if 0 -public final class Actor { - - public Actor(String name, Host host, double killTime, Runnable code); - // .... - -} -#endif +#endif /* SIMGRID_S4U_ACTOR_HPP */ diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 586f2aec7b..2bd4041d86 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -819,6 +819,7 @@ set(DOC_SOURCES doc/doxygen/tutorial.doc doc/doxygen/models.doc doc/doxygen/module-msg.doc + doc/doxygen/module-s4u.doc doc/doxygen/module-sd.doc doc/doxygen/module-simix.doc doc/doxygen/module-smpi.doc -- 2.20.1