Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
50c52f72c49434c15ce4c7e48bf740668e376db8
[simgrid.git] / 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 SURF_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 global variables \ref host_list.
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_bandwith();
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     When the simulation is over, just call surf_exit() to clean the memory.
76
77     Have a look at the implementation of \ref MSG_API "MSG" and \ref SD_API "Simdag" to see how these module
78     interact with SURF. But if you want to create a new API on top of SURF,
79     we strongly recommend you to contact us before anyway.
80
81 */
82
83 /**
84 @defgroup SURF_c_bindings   SURF C bindings
85 @ingroup SURF_API
86 @brief Describes the c bindings of SURF
87 */
88
89 /**
90 @defgroup SURF_interface   SURF Interface
91 @ingroup SURF_API
92 @brief Describes the general interface for all components (Cpu, Network, Storage, Host, VM)
93 */
94
95 /**
96 @defgroup SURF_cpu_interface   SURF Cpu Interface
97 @ingroup SURF_API
98 @brief Describes the general Cpu interface for all Cpu implementations
99 */
100
101 /**
102 @defgroup SURF_network_interface   SURF Network Interface
103 @ingroup SURF_API
104 @brief Describes the general Network interface for all Network implementations
105 */
106
107 /**
108 @defgroup SURF_storage_interface   SURF Storage Interface
109 @ingroup SURF_API
110 @brief Describes the general  interface for all Storage implementations
111 */
112
113 /**
114 @defgroup SURF_host_interface   SURF Host Interface
115 @ingroup SURF_API
116 @brief Describes the general  interface for all Host implementations
117 */
118
119 /**
120 @defgroup SURF_vm_interface   SURF VM Interface
121 @ingroup SURF_API
122 @brief Describes the general  interface for all VM implementations
123 */
124
125 /**
126 @defgroup SURF_lmm   SURF Linear MaxMin
127 @ingroup SURF_API
128 @brief Describes how the linear MaxMin system work
129 */
130
131 /**
132 @defgroup SURF_callbacks   SURF callbacks
133 @ingroup SURF_API
134 @brief Describes how to use the SURF callbacks
135 */
136
137 /**
138 @defgroup SURF_plugin_energy   SURF Energy Plugin
139 @ingroup SURF_API
140 @brief Describes how to use the energy plugin.
141 */