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