Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
there is no need for a SimDag's link type
[simgrid.git] / include / simgrid / simdag.h
1 /* Copyright (c) 2006-2010, 2012-2014. The SimGrid Team.
2  * All rights reserved.                                                     */
3
4 /* This program is free software; you can redistribute it and/or modify it
5  * under the terms of the license (GNU LGPL) which comes with this package. */
6
7 #ifndef SIMDAG_SIMDAG_H
8 #define SIMDAG_SIMDAG_H
9
10 #include "xbt/misc.h"
11 #include "xbt/dynar.h"
12 #include "xbt/dict.h"
13
14 #include "simgrid/link.h"
15
16 SG_BEGIN_DECL()
17 /** @brief Workstation datatype
18     @ingroup SD_datatypes_management
19
20     A workstation is a place where a task can be executed.
21     A workstation is represented as a <em>physical
22     resource with computing capabilities</em> and has a <em>name</em>.
23
24     @see SD_workstation_management */
25 typedef xbt_dictelm_t SD_workstation_t;
26
27 /** @brief Workstation access mode
28     @ingroup SD_datatypes_management
29
30     By default, a workstation resource is shared, i.e. several tasks
31     can be executed at the same time on a workstation. The CPU power of
32     the workstation is shared between the running tasks on the workstation.
33     In sequential mode, only one task can use the workstation, and the other
34     tasks wait in a FIFO.
35
36     @see SD_workstation_get_access_mode(), SD_workstation_set_access_mode() */
37 typedef enum {
38   SD_WORKSTATION_SHARED_ACCESS,     /**< @brief Several tasks can be executed at the same time */
39   SD_WORKSTATION_SEQUENTIAL_ACCESS  /**< @brief Only one task can be executed, the others wait in a FIFO. */
40 } e_SD_workstation_access_mode_t;
41
42 /** @brief Link datatype
43     @ingroup SD_datatypes_management
44
45     A link is a network node represented as a <em>name</em>, a <em>current
46     bandwidth</em> and a <em>current latency</em>. A route is a list of
47     links between two workstations.
48
49     @see SD_link_management */
50 typedef Link *SD_link_t;
51
52 /** @brief Task datatype
53     @ingroup SD_datatypes_management
54
55     A task is some <em>computing amount</em> that can be executed
56     in parallel on several workstations. A task may depend on other
57     tasks, this means that the task cannot start until the other tasks are done.
58     Each task has a <em>\ref e_SD_task_state_t "state"</em> indicating whether
59     the task is scheduled, running, done, etc.
60
61     @see SD_task_management */
62 typedef struct SD_task *SD_task_t;
63
64 /** @brief Task states
65     @ingroup SD_datatypes_management
66
67     @see SD_task_management */
68 typedef enum {
69   SD_NOT_SCHEDULED = 0,      /**< @brief Initial state (not valid for SD_watch and SD_unwatch). */
70   SD_SCHEDULABLE = 0x0001,               /**< @brief A task becomes SD_SCHEDULABLE as soon as its dependencies are satisfied */
71   SD_SCHEDULED = 0x0002,     /**< @brief A task becomes SD_SCHEDULED when you call function
72                                   SD_task_schedule. SD_simulate will execute it when it becomes SD_RUNNABLE. */
73   SD_RUNNABLE = 0x0004,      /**< @brief A scheduled task becomes runnable is SD_simulate as soon as its dependencies are satisfied. */
74   SD_IN_FIFO = 0x0008,       /**< @brief A runnable task can have to wait in a workstation fifo if the workstation is sequential */
75   SD_RUNNING = 0x0010,       /**< @brief An SD_RUNNABLE or SD_IN_FIFO becomes SD_RUNNING when it is launched. */
76   SD_DONE = 0x0020,          /**< @brief The task is successfully finished. */
77   SD_FAILED = 0x0040         /**< @brief A problem occurred during the execution of the task. */
78 } e_SD_task_state_t;
79
80 /** @brief Task kinds
81     @ingroup SD_datatypes_management
82
83     @see SD_task_management */
84 typedef enum {
85   SD_TASK_NOT_TYPED = 0,      /**< @brief no specified type */
86   SD_TASK_COMM_E2E = 1,       /**< @brief end to end communication */
87   SD_TASK_COMP_SEQ = 2,        /**< @brief sequential computation */
88   SD_TASK_COMP_PAR_AMDAHL = 3, /**< @brief parallel computation (Amdahl's law) */
89   SD_TASK_COMM_PAR_MXN_1D_BLOCK = 4 /**< @brief MxN data redistribution (1D Block distribution) */
90 } e_SD_task_kind_t;
91
92
93 /** @brief Storage datatype
94     @ingroup SD_datatypes_management
95
96  TODO PV: comment it !
97
98     @see SD_storage_management */
99 typedef xbt_dictelm_t SD_storage_t;
100
101 /************************** AS handling *************************************/
102 XBT_PUBLIC(xbt_dict_t) SD_as_router_get_properties(const char *as);
103 XBT_PUBLIC(const char*) SD_as_router_get_property_value(const char * as,
104                                                   const char *name);
105
106 /************************** Link handling ***********************************/
107 /** @defgroup SD_link_management Links
108  *  @brief Functions for managing the network links
109  *
110  *  This section describes the functions for managing the network links.
111  *
112  *  A link is a network node represented as a <em>name</em>, a <em>current
113  *  bandwidth</em> and a <em>current latency</em>. The links are created
114  *  when you call the function SD_create_environment.
115  *
116  *  @see SD_link_t
117  *  @{
118  */
119 XBT_PUBLIC(const SD_link_t *) SD_link_get_list(void);
120 XBT_PUBLIC(int) SD_link_get_number(void);
121 /** @brief Returns the user data of a link */
122 static inline void *SD_link_get_data(SD_link_t link) {
123   return surf_network_link_data(link);
124 }
125
126 /** @brief Sets the user data of a link
127  *
128  * The new data can be \c NULL. The old data should have been freed first
129  * if it was not \c NULL.
130  */
131 static inline void SD_link_set_data(SD_link_t link, void *data) {
132         surf_network_link_data_set(link, data);
133 }
134 /** @Returns the name of a link  */
135 static inline const char *SD_link_get_name(SD_link_t link) {
136   return surf_network_link_get_name(link);
137 }
138 /** @brief Returns the current bandwidth of a link (in bytes per second) */
139 static inline double SD_link_get_current_bandwidth(SD_link_t link) {
140   return surf_network_link_get_bandwidth(link);
141 }
142 /** @brief Returns the current latency of a link (in seconds) */
143 static inline double SD_link_get_current_latency(SD_link_t link){
144   return surf_network_link_get_latency(link);
145 }
146 /** @brief Returns the sharing policy of this workstation.
147  *  @return true if the link is shared, and false if it's a fatpipe
148  */
149 static inline int SD_link_is_shared(SD_link_t link) {
150   return surf_network_link_is_shared(link);
151 }
152 /** @} */
153
154 /************************** Workstation handling ****************************/
155
156 /** @defgroup SD_workstation_management Workstations
157  *  @brief Functions for managing the workstations
158  *
159  *  This section describes the functions for managing the workstations.
160  *
161  *  A workstation is a place where a task can be executed.
162  *  A workstation is represented as a <em>physical
163  *  resource with computing capabilities</em> and has a <em>name</em>.
164  *
165  *  The workstations are created when you call the function SD_create_environment.
166  *
167  *  @see SD_workstation_t
168  *  @{
169  */
170 XBT_PUBLIC(SD_workstation_t) SD_workstation_get_by_name(const char *name);
171 XBT_PUBLIC(const SD_workstation_t *) SD_workstation_get_list(void);
172 XBT_PUBLIC(int) SD_workstation_get_number(void);
173 XBT_PUBLIC(void) SD_workstation_set_data(SD_workstation_t workstation,
174                                          void *data);
175 XBT_PUBLIC(void *) SD_workstation_get_data(SD_workstation_t workstation);
176 XBT_PUBLIC(const char *) SD_workstation_get_name(SD_workstation_t
177                                                  workstation);
178 /*property handling functions*/
179 XBT_PUBLIC(xbt_dict_t) SD_workstation_get_properties(SD_workstation_t
180                                                      workstation);
181 XBT_PUBLIC(const char *) SD_workstation_get_property_value(SD_workstation_t
182                                                            workstation,
183                                                            const char
184                                                            *name);
185 XBT_PUBLIC(void) SD_workstation_dump(SD_workstation_t ws);
186 XBT_PUBLIC(const SD_link_t *) SD_route_get_list(SD_workstation_t src,
187                                                 SD_workstation_t dst);
188 XBT_PUBLIC(int) SD_route_get_size(SD_workstation_t src,
189                                   SD_workstation_t dst);
190 XBT_PUBLIC(double) SD_workstation_get_power(SD_workstation_t workstation);
191 XBT_PUBLIC(double) SD_workstation_get_available_power(SD_workstation_t
192                                                       workstation);
193 XBT_PUBLIC(int) SD_workstation_get_cores(SD_workstation_t workstation);
194 XBT_PUBLIC(e_SD_workstation_access_mode_t)
195     SD_workstation_get_access_mode(SD_workstation_t workstation);
196 XBT_PUBLIC(void) SD_workstation_set_access_mode(SD_workstation_t
197                                                 workstation,
198                                                 e_SD_workstation_access_mode_t
199                                                 access_mode);
200
201 XBT_PUBLIC(double) SD_workstation_get_computation_time(SD_workstation_t workstation,
202                                                        double flops_amount);
203 XBT_PUBLIC(double) SD_route_get_current_latency(SD_workstation_t src,
204                                                 SD_workstation_t dst);
205 XBT_PUBLIC(double) SD_route_get_current_bandwidth(SD_workstation_t src,
206                                                   SD_workstation_t dst);
207 XBT_PUBLIC(double) SD_route_get_communication_time(SD_workstation_t src,
208                                                    SD_workstation_t dst,
209                                                    double bytes_amount);
210
211 XBT_PUBLIC(SD_task_t) SD_workstation_get_current_task(SD_workstation_t workstation);
212 XBT_PUBLIC(xbt_dict_t)
213     SD_workstation_get_mounted_storage_list(SD_workstation_t workstation);
214 XBT_PUBLIC(xbt_dynar_t)
215     SD_workstation_get_attached_storage_list(SD_workstation_t workstation);
216 XBT_PUBLIC(const char*) SD_storage_get_host(SD_storage_t storage);
217 /** @} */
218
219 /************************** Task handling ************************************/
220
221 /** @defgroup SD_task_management Tasks
222  *  @brief Functions for managing the tasks
223  *
224  *  This section describes the functions for managing the tasks.
225  *
226  *  A task is some <em>working amount</em> that can be executed
227  *  in parallel on several workstations. A task may depend on other
228  *  tasks, this means that the task cannot start until the other tasks are done.
229  *  Each task has a <em>\ref e_SD_task_state_t "state"</em> indicating whether
230  *  the task is scheduled, running, done, etc.
231  *
232  *  @see SD_task_t, SD_task_dependency_management
233  *  @{
234  */
235 XBT_PUBLIC(SD_task_t) SD_task_create(const char *name, void *data,
236                                      double amount);
237 XBT_PUBLIC(void *) SD_task_get_data(SD_task_t task);
238 XBT_PUBLIC(void) SD_task_set_data(SD_task_t task, void *data);
239 XBT_PUBLIC(e_SD_task_state_t) SD_task_get_state(SD_task_t task);
240 XBT_PUBLIC(const char *) SD_task_get_name(SD_task_t task);
241 XBT_PUBLIC(void) SD_task_set_name(SD_task_t task, const char *name);
242 XBT_PUBLIC(void) SD_task_set_rate(SD_task_t task, double rate);
243
244 XBT_PUBLIC(void) SD_task_watch(SD_task_t task, e_SD_task_state_t state);
245 XBT_PUBLIC(void) SD_task_unwatch(SD_task_t task, e_SD_task_state_t state);
246 XBT_PUBLIC(double) SD_task_get_amount(SD_task_t task);
247 XBT_PUBLIC(void) SD_task_set_amount(SD_task_t task, double amount);
248 XBT_PUBLIC(double) SD_task_get_alpha(SD_task_t task);
249 XBT_PUBLIC(double) SD_task_get_remaining_amount(SD_task_t task);
250 XBT_PUBLIC(double) SD_task_get_execution_time(SD_task_t task,
251                                               int workstation_nb,
252                                               const SD_workstation_t *
253                                               workstation_list,
254                                               const double *flops_amount,
255                                                                                           const double *bytes_amount);
256 XBT_PUBLIC(int) SD_task_get_kind(SD_task_t task);
257 XBT_PUBLIC(void) SD_task_schedule(SD_task_t task, int workstation_nb,
258                                   const SD_workstation_t *
259                                   workstation_list,
260                                   const double *flops_amount,
261                                   const double *bytes_amount,
262                                   double rate);
263 XBT_PUBLIC(void) SD_task_unschedule(SD_task_t task);
264 XBT_PUBLIC(double) SD_task_get_start_time(SD_task_t task);
265 XBT_PUBLIC(double) SD_task_get_finish_time(SD_task_t task);
266 XBT_PUBLIC(xbt_dynar_t) SD_task_get_parents(SD_task_t task);
267 XBT_PUBLIC(xbt_dynar_t) SD_task_get_children(SD_task_t task);
268 XBT_PUBLIC(int) SD_task_get_workstation_count(SD_task_t task);
269 XBT_PUBLIC(SD_workstation_t *) SD_task_get_workstation_list(SD_task_t
270                                                             task);
271 XBT_PUBLIC(void) SD_task_destroy(SD_task_t task);
272 XBT_PUBLIC(void) SD_task_dump(SD_task_t task);
273 XBT_PUBLIC(void) SD_task_dotty(SD_task_t task, void *out_FILE);
274
275 XBT_PUBLIC(SD_task_t) SD_task_create_comp_seq(const char *name, void *data,
276                                               double amount);
277 XBT_PUBLIC(SD_task_t) SD_task_create_comp_par_amdahl(const char *name,
278                                                      void *data,
279                                                      double amount,
280                                                      double alpha);
281 XBT_PUBLIC(SD_task_t) SD_task_create_comm_e2e(const char *name, void *data,
282                                               double amount);
283 XBT_PUBLIC(SD_task_t) SD_task_create_comm_par_mxn_1d_block(const char *name,
284                                                            void *data,
285                                                            double amount);
286
287 XBT_PUBLIC(void) SD_task_distribute_comp_amdahl(SD_task_t task, int ws_count);
288 XBT_PUBLIC(void) SD_task_schedulev(SD_task_t task, int count,
289                                    const SD_workstation_t * list);
290 XBT_PUBLIC(void) SD_task_schedulel(SD_task_t task, int count, ...);
291
292
293 /** @brief A constant to use in SD_task_schedule to mean that there is no cost.
294  *
295  *  For example, create a pure computation task (no comm) like this:
296  *
297  *  SD_task_schedule(task, my_workstation_nb,
298  *                   my_workstation_list,
299  *                   my_flops_amount,
300  *                   SD_TASK_SCHED_NO_COST,
301  *                   my_rate);
302  */
303 #define SD_SCHED_NO_COST NULL
304
305 /** @} */
306
307
308 /** @defgroup SD_task_dependency_management Tasks dependencies
309  *  @brief Functions for managing the task dependencies
310  *
311  *  This section describes the functions for managing the dependencies between the tasks.
312  *
313  *  @see SD_task_management
314  *  @{
315  */
316 XBT_PUBLIC(void) SD_task_dependency_add(const char *name, void *data,
317                                         SD_task_t src, SD_task_t dst);
318 XBT_PUBLIC(void) SD_task_dependency_remove(SD_task_t src, SD_task_t dst);
319 XBT_PUBLIC(const char *) SD_task_dependency_get_name(SD_task_t src,
320                                                      SD_task_t dst);
321 XBT_PUBLIC(void *) SD_task_dependency_get_data(SD_task_t src,
322                                                SD_task_t dst);
323 XBT_PUBLIC(int) SD_task_dependency_exists(SD_task_t src, SD_task_t dst);
324 /** @} */
325
326 /************************** Global *******************************************/
327
328 /** @defgroup SD_simulation Simulation
329  *  @brief Functions for creating the environment and launching the simulation
330  *
331  *  This section describes the functions for initialising SimDag, launching
332  *  the simulation and exiting SimDag.
333  *
334  *  @{
335  */
336 XBT_PUBLIC(void) SD_init(int *argc, char **argv);
337 XBT_PUBLIC(void) SD_config(const char *key, const char *value);
338 XBT_PUBLIC(void) SD_application_reinit(void);
339 XBT_PUBLIC(void) SD_create_environment(const char *platform_file);
340 XBT_PUBLIC(xbt_dynar_t) SD_simulate(double how_long);
341 XBT_PUBLIC(double) SD_get_clock(void);
342 XBT_PUBLIC(void) SD_exit(void);
343 XBT_PUBLIC(xbt_dynar_t) SD_daxload(const char *filename);
344 XBT_PUBLIC(xbt_dynar_t) SD_dotload(const char *filename);
345 XBT_PUBLIC(xbt_dynar_t) SD_PTG_dotload(const char *filename);
346 XBT_PUBLIC(xbt_dynar_t) SD_dotload_with_sched(const char *filename);
347 XBT_PUBLIC(void) uniq_transfer_task_name(SD_task_t task);
348
349 /** @} */
350
351 #include "simgrid/instr.h"
352
353 SG_END_DECL()
354 #endif