From 80aa60c52bb2ab930c3eb28b1417726717caf847 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Thu, 16 Jun 2016 01:51:00 +0200 Subject: [PATCH] Improve the doc of the S4U actors --- doc/doxygen/index.doc | 2 +- doc/doxygen/module-s4u.doc | 6 +++ examples/s4u/basic/s4u_basic.cpp | 2 +- include/simgrid/s4u/actor.hpp | 89 +++++++++++++++++++++++++------- 4 files changed, 77 insertions(+), 22 deletions(-) diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index b68602d0f3..1dc3e3d9a0 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -14,7 +14,7 @@ - @subpage install - @subpage install_yours - @subpage application - - @subpage s4u_API + - @subpage s4u_api - @subpage MSG_API - @subpage SD_API - @subpage SMPI_API diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc index 2488d1d14b..9e629e1e6d 100644 --- a/doc/doxygen/module-s4u.doc +++ b/doc/doxygen/module-s4u.doc @@ -17,7 +17,13 @@ Unsurprisingly, the S4U interface matches the concepts presented in - @ref s4u_actor + @{ */ + +/** @defgroup s4u_actor Actors: simulation agents */ + +/** @} */ + - \ref msg_simulation - \ref m_process_management - \ref m_host_management diff --git a/examples/s4u/basic/s4u_basic.cpp b/examples/s4u/basic/s4u_basic.cpp index 13d01035ea..991b3f7e7f 100644 --- a/examples/s4u/basic/s4u_basic.cpp +++ b/examples/s4u/basic/s4u_basic.cpp @@ -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. */ diff --git a/include/simgrid/s4u/actor.hpp b/include/simgrid/s4u/actor.hpp index fbb3112fd0..a07c2bd1d0 100644 --- a/include/simgrid/s4u/actor.hpp +++ b/include/simgrid/s4u/actor.hpp @@ -14,10 +14,6 @@ namespace simgrid { namespace s4u { -/** @defgroup s4u_actor Actors: simulation agents - * @addtogroup S4U_API - */ - /** @addtogroup s4u_actor * * @tableofcontents @@ -31,37 +27,90 @@ namespace s4u { * An actor is located on a (simulated) host, but it can interact * with the whole simulated platform. * + * The s4u::Actor API is strongly inspired from the C++11 threads. + * The documentation + * of this standard may help to understand the philosophy of the S4U + * Actors. + * * (back to the @ref s4u_api "S4U documentation") * - * @section s4u_actor_def Defining an Actor + * @section s4u_actor_def Defining the skeleton of 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. + * %As in the C++11 + * standard, you can declare the code of your actor either as a + * pure function or as an object. It is very simple with functions: * - * For example, a Worker actor should be declared as follows: - * - * \code{.cpp} + * @code{.cpp} + * // Declare the code of your worker + * void worker() { + * printf("Hello s4u"); + * simgrid::s4u::this_actor::execute(5*1024*1024); // Get the worker executing a task of 5 MFlops + * }; + * + * // From your main or from another actor, create your actor on the host Jupiter + * new Actor("worker", simgrid::s4u::Host::by_name("Jupiter"), worker); + * @endcode + * + * But some people prefer to encapsulate their actors in classes and + * objects to save the actor state in a cleanly dedicated location. + * The syntax is slightly more complicated, but not much. + * + * @code{.cpp} * #include "s4u/actor.hpp" * + * // Declare the class representing your actors * class Worker { + * public: * void operator()() { // Two pairs of () because this defines the method called () * printf("Hello s4u"); * 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 + * // From your main or from another actor, create your actor. Note the () after Worker + * new Actor("worker", simgrid::s4u::Host::by_name("Jupiter"), Worker()); + * @endcode + * + * @section s4u_actor_flesh Fleshing your actor * - * // Then later in your main() function or so: - * ... - * new Actor("worker", host, Worker()); - * ... + * The body of your actor can use the functions of the + * simgrid::s4u::this_actor namespace to interact with the world. + * This namespace contains the methods to start new activities + * (executions, communications, etc), and to get informations about + * the currently running thread (its location, etc). + * + * Please refer to the @link simgrid::s4u::this_actor full API @endlink. * - * 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. + * + * @section s4u_actor_deploy Using a deployment file + * + * @warning This is currently not working with S4U. Sorry about that. + * + * The best practice is to use an external deployment file as + * follows, because it makes it easier to test your application in + * differing settings. Load this file with + * s4u::Engine::loadDeployment() before the simulation starts. + * Refer to the @ref deployment section for more information. + * + * @code{.xml} + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *