doc/doxygen/module-s4u.doc

   1 /**
   2 @defgroup s4u_api  S4U: Next Generation SimGrid API
   3 @brief Future core API, mixing the full power of SimGrid to the power of C++.
   4
   5 The S4U API is currently under heavy work, but will eventually
   6 deprecate the MSG and SimDag APIs. Everything that you can do in
   7 SimGrid will be possible in S4U.
   8
   9 @warning <b>S4U is not ready for public use yet</b>. You should not go
  10          that path unless you know what you are doing.  If unsure,
  11          proceed to @ref MSG_API instead.
  12
  13 @section s4u_funct Offered functionalities
  14
  15 Unsurprisingly, the S4U interface matches the concepts presented in
  16 @ref starting_components "the introduction":
  17
  18   - @ref s4u_actor
  19
  20   @{
  21 */
  22
  23 /** @defgroup  s4u_actor Actors: simulation agents */
  24
  25 /** @} */
  26
  27    - \ref msg_simulation
  28    - \ref m_process_management
  29    - \ref m_host_management
  30    - \ref m_task_management
  31    - \ref msg_mailbox_management
  32    - @ref msg_file
  33    - \ref msg_task_usage
  34    - \ref msg_VMs
  35    - \ref msg_synchro
  36    - \ref msg_trace_driven
  37    - \ref MSG_examples
  38
  39 @defgroup msg_simulation   Main MSG simulation Functions
  40 @ingroup MSG_API
  41 @brief How to setup and control your simulation.
  42
  43 The basic workflow is the following (check the \ref MSG_examples for
  44 details).
  45
  46  -# Initialize the library with #MSG_init
  47  -# Create a platform (usually by parsing a file with
  48     #MSG_create_environment)
  49  -# Register the functions that your processes are supposed to run with
  50     #MSG_function_register (and maybe #MSG_function_register_default)
  51  -# Launch your processes from a deployment file with #MSG_launch_application
  52  -# Run the simulation with #MSG_main
  53 *
  54
  55 ** @defgroup m_process_management Process Management Functions
  56  *  @ingroup MSG_API
  57  *  @brief This section describes the process structure of MSG
  58  *         (#msg_process_t) and the functions for managing it.
  59  */
  60
  61 ** @defgroup m_host_management Host Management Functions
  62  *  @ingroup MSG_API
  63  *  @brief Host structure of MSG
  64  *
  65
  66 ** @defgroup m_task_management Task Management Functions
  67  *  @ingroup MSG_API
  68  *  @brief Task structure of MSG (#msg_task_t) and associated functions. See
  69  *         \ref msg_task_usage to see how to put the tasks in action.
  70  *
  71
  72 ** @defgroup msg_mailbox_management Mailbox Management Functions
  73  *  @ingroup MSG_API
  74  *  @brief Mailbox structure of MSG (#msg_mailbox_t) and associated functions.
  75  *
  76
  77 ** @defgroup msg_task_usage Task Actions
  78  *  @ingroup MSG_API
  79  *  @brief This section describes the functions that can be used
  80  *         by a process to execute, communicate or otherwise handle some task.
  81  *
  82
  83 ** @defgroup msg_synchro Explicit Synchronization Functions
  84  *  @ingroup MSG_API
  85  *  @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
  86  *
  87  * In some situations, these things are very helpful to synchronize processes without message exchanges.
  88  *
  89
  90 ** @defgroup msg_VMs VMs
  91  *  @ingroup MSG_API
  92  *  @brief Interface created to mimic IaaS clouds.
  93  *
  94  *  With it, you can create virtual machines to put your processes
  95  *  into, and interact directly with the VMs to manage groups of
  96  *  processes.
  97  *
  98  *  This interface is highly experimental at this point. Testing is
  99  *  welcomed, but do not expect too much of it right now. Even the
 100  *  interfaces may be changed in future releases of SimGrid (although
 101  *  things are expected to stabilize nicely before SimGrid v3.8).
 102  *  There is no guaranty on the rest of SimGrid, and there is less
 103  *  than that on this part.
 104  *
 105  *
 106
 107 ** @defgroup msg_storage_management Storage Management Functions
 108  *  @ingroup MSG_API
 109  *  @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
 110  *
 111
 112 ** @defgroup msg_file File Management Functions
 113     @ingroup MSG_API
 114     @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
 115 *
 116
 117 **
 118 @defgroup msg_trace_driven Trace-driven simulations
 119 @ingroup MSG_API
 120 @brief This section describes the functions allowing to build trace-driven simulations.
 121
 122 This is very handy when you want to test an algorithm or protocol that
 123 does nothing unless it receives some events from outside. For example,
 124 a P2P protocol reacts to requests from the user, but does nothing if
 125 there is no such event.
 126
 127 In such situations, SimGrid allows to write your protocol in your C
 128 file, and the events to react to in a separate text file. Declare a
 129 function handling each of the events that you want to accept in your
 130 trace files, register them using #xbt_replay_action_register in your main,
 131 and then use #MSG_action_trace_run to launch the simulation. You can
 132 either have one trace file containing all your events, or a file per
 133 simulated process.
 134
 135 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 136
 137  *