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