--- /dev/null
+/**
+@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 <b>S4U is not ready for public use yet</b>. 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 <b>examples/msg/actions/actions.c</b> for details.
+
+ *
-/* 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. */
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:
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);
};
-}} // 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 */
