doc/doxygen/module-surf.doc

   1 /** @addtogroup SURF_API
   2
   3   @section SURF_doc Surf documentation
   4    Surf is composed several components:
   5    - @ref SURF_simulation
   6    - @ref SURF_models
   7    - @ref SURF_build_api
   8    - @ref SURF_c_bindings
   9    - @ref SURF_interface
  10    - @ref SURF_cpu_interface
  11    - @ref SURF_network_interface
  12    - @ref SURF_storage_interface
  13    - @ref SURF_host_interface
  14    - @ref SURF_vm_interface
  15    - @ref SURF_lmm
  16    - @ref SURF_callbacks
  17    - @ref plugin_energy
  18
  19
  20 */
  21
  22 /** @defgroup SURF_models Simulation Models
  23     @ingroup SURF_API
  24     @brief Functions to declare the kind of models that you want to use
  25     */
  26
  27 /** @defgroup SURF_simulation Simulation
  28     @ingroup SURF_API
  29     @brief Functions for creating the environment and launching the simulation
  30
  31     This section describes the functions for initializing SURF, performing
  32     the simulation and exiting SURF.
  33 */
  34
  35 /** @defgroup SURF_build_api Create a new API
  36     @ingroup SURF_API
  37     @brief How to build a new API on top of SURF
  38
  39     SURF provides the functionalities to simulate the platform. There are two main data types in SURF:
  40     the actions and the resources. Several types of resources exist:
  41         - the host resource,
  42         - the network resource,
  43         - the CPU resource,
  44         - the timer resource.
  45
  46     The implementation of these resources depends on the platform
  47     models you choose.  You can select your model by calling
  48     #surf_host_model_init_current_default() (which will give you a
  49     CLM03 model), or similar (see @ref SURF_models).
  50
  51     To initialize SURF, call #surf_init(). Then
  52     #surf_host_model_init_current_default() or #surf_host_model_init_ptask_L07()
  53     to create the platform.
  54
  55     Then you can access the hosts with the @ref simgrid::s4u::Engine::get_all_hosts.
  56     Some functions of the @ref SURF_host_interface and similar can give
  57     you some information about:
  58         - a host: get_speed(), get_available_speed();
  59         - a network link: get_link_name(), get_link_latency(), get_link_bandwidth();
  60         - a route: get_route(), get_route_size().
  61
  62     During the simulation, call @a surf_host_model->execute() to schedule a
  63     computation task on a host, or @a surf_host_model->communicate()
  64     to schedule a communication task between two hosts. You can also create parallel task
  65     with @a surf_host_model->extension_public->execute_parallel_task(). These functions return
  66     a new action that represents the task you have just created.
  67
  68     To execute the actions created with @a execute(), @a communicate() or @a execute_parallel_task(), call
  69     surf_solve(). The function surf_solve() is where the simulation takes place. It returns the
  70     time elapsed to execute the actions. You can know what actions have changed their state thanks
  71     to the states sets. For example, if your want to know what actions are finished,
  72     extract them from @a surf_host_model->common_public->states.done_action_set.
  73     Depending on these results, you can schedule other tasks and call surf_solve() again.
  74
  75     Have a look at the implementation of @ref MSG_API "MSG" and @ref SD_API "Simdag" to see how these module
  76     interact with SURF. But if you want to create a new API on top of SURF,
  77     we strongly recommend you to contact us before anyway.
  78
  79 */
  80
  81 /**
  82 @defgroup SURF_c_bindings   SURF C bindings
  83 @ingroup SURF_API
  84 @brief Describes the c bindings of SURF
  85 */
  86
  87 /**
  88 @defgroup SURF_interface   SURF Interface
  89 @ingroup SURF_API
  90 @brief Describes the general interface for all components (Cpu, Network, Storage, Host, VM)
  91 */
  92
  93 /**
  94 @defgroup SURF_cpu_interface   SURF Cpu Interface
  95 @ingroup SURF_API
  96 @brief Describes the general Cpu interface for all Cpu implementations
  97 */
  98
  99 /**
 100 @defgroup SURF_network_interface   SURF Network Interface
 101 @ingroup SURF_API
 102 @brief Describes the general Network interface for all Network implementations
 103 */
 104
 105 /**
 106 @defgroup SURF_storage_interface   SURF Storage Interface
 107 @ingroup SURF_API
 108 @brief Describes the general  interface for all Storage implementations
 109 */
 110
 111 /**
 112 @defgroup SURF_host_interface   SURF Host Interface
 113 @ingroup SURF_API
 114 @brief Describes the general  interface for all Host implementations
 115 */
 116
 117 /**
 118 @defgroup SURF_vm_interface   SURF VM Interface
 119 @ingroup SURF_API
 120 @brief Describes the general  interface for all VM implementations
 121 */
 122
 123 /**
 124 @defgroup SURF_lmm   SURF Linear MaxMin
 125 @ingroup SURF_API
 126 @brief Describes how the linear MaxMin system work
 127 */
 128
 129 /**
 130 @defgroup SURF_callbacks   SURF callbacks
 131 @ingroup SURF_API
 132 @brief Describes how to use the SURF callbacks
 133 */
 134
 135 /**
 136 @defgroup plugin_energy   Energy Plugin
 137 @ingroup SURF_API
 138 @brief Describes how to use the energy plugin.
 139 */