Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Merge branch 'master' of github.com:simgrid/simgrid
[simgrid.git] / src / include / surf / surf.h
1 /* Copyright (c) 2004-2017. The SimGrid Team. All rights reserved.          */
2
3 /* This program is free software; you can redistribute it and/or modify it
4  * under the terms of the license (GNU LGPL) which comes with this package. */
5
6 #ifndef SURF_SURF_H
7 #define SURF_SURF_H
8
9 #include "xbt/swag.h"
10 #include "xbt/dynar.h"
11 #include "xbt/dict.h"
12 #include "xbt/graph.h"
13 #include "xbt/misc.h"
14 #include "xbt/config.h"
15 #include "src/internal_config.h"
16 #include "surf/datatypes.h"
17 #include "simgrid/datatypes.h"
18 #include "simgrid/forward.h"
19
20 SG_BEGIN_DECL()
21 /* Actions and models are highly connected structures... */
22
23 /* user-visible parameters */
24 extern XBT_PRIVATE double sg_tcp_gamma;
25 extern XBT_PRIVATE double sg_sender_gap;
26 extern XBT_PRIVATE double sg_latency_factor;
27 extern XBT_PRIVATE double sg_bandwidth_factor;
28 extern XBT_PRIVATE double sg_weight_S_parameter;
29 extern XBT_PRIVATE int sg_network_crosstraffic;
30
31 #ifdef __cplusplus
32
33 namespace simgrid {
34 namespace surf {
35
36 class Model;
37 class CpuModel;
38 class HostModel;
39 class NetworkModel;
40 class StorageModel;
41 class Resource;
42 class NetworkCm02Link;
43 class Action;
44 }
45 }
46
47 typedef simgrid::surf::Model surf_Model;
48 typedef simgrid::surf::CpuModel surf_CpuModel;
49 typedef simgrid::surf::Cpu surf_Cpu;
50 typedef simgrid::surf::HostModel surf_HostModel;
51 typedef simgrid::surf::NetworkModel surf_NetworkModel;
52 typedef simgrid::surf::StorageImpl surf_Storage;
53 typedef simgrid::surf::StorageModel surf_StorageModel;
54 typedef simgrid::surf::Resource surf_Resource;
55 typedef simgrid::surf::HostImpl surf_Host;
56 typedef simgrid::surf::Action surf_Action;
57
58 #else
59
60 typedef struct surf_Model surf_Model;
61 typedef struct surf_CpuModel surf_CpuModel;
62 typedef struct surf_Cpu surf_Cpu;
63 typedef struct surf_HostModel surf_HostModel;
64 typedef struct surf_NetworkModel surf_NetworkModel;
65 typedef struct surf_StorageImpl surf_Storage;
66 typedef struct surf_StorageModel surf_StorageModel;
67 typedef struct surf_Resource surf_Resource;
68 typedef struct surf_Host surf_Host;
69 typedef struct surf_Action surf_Action;
70
71 #endif
72
73 /** @ingroup SURF_c_bindings
74  *  \brief Model datatype
75  *
76  *  Generic data structure for a model. The hosts,
77  *  the CPUs and the network links are examples of models.
78  */
79 typedef surf_Model *surf_model_t;
80 typedef surf_CpuModel *surf_cpu_model_t;
81 typedef surf_HostModel *surf_host_model_t;
82 typedef surf_NetworkModel *surf_network_model_t;
83 typedef surf_StorageModel *surf_storage_model_t;
84 typedef surf_Storage* surf_storage_t;
85
86 /** @ingroup SURF_c_bindings
87  *  \brief Action structure
88  *
89  *  Never create s_surf_action_t by yourself ! The actions are created
90  *  on the fly when you call execute or communicate on a model.
91  *
92  *  \see e_surf_action_state_t
93  */
94 typedef surf_Action *surf_action_t;
95
96 typedef struct surf_file *surf_file_t;
97
98 /** \brief Resource model description
99  */
100 struct surf_model_description {
101   const char *name;
102   const char *description;
103   void_f_void_t model_init_preparse;
104 };
105 typedef struct surf_model_description  s_surf_model_description_t;
106 typedef struct surf_model_description* surf_model_description_t;
107
108 XBT_PUBLIC(int) find_model_description(s_surf_model_description_t * table, const char *name);
109 XBT_PUBLIC(void) model_help(const char *category, s_surf_model_description_t * table);
110
111 /***************************/
112 /* Generic model object */
113 /***************************/
114
115 /** @{ @ingroup SURF_c_bindings */
116
117 /**
118  * @brief Pop an action from the done actions set
119  *
120  * @param model The model from which the action is extracted
121  * @return An action in done state
122  */
123 XBT_PUBLIC(surf_action_t) surf_model_extract_done_action_set(surf_model_t model);
124
125 /**
126  * @brief Pop an action from the failed actions set
127  *
128  * @param model The model from which the action is extracted
129  * @return An action in failed state
130  */
131 XBT_PUBLIC(surf_action_t) surf_model_extract_failed_action_set(surf_model_t model);
132
133 /**
134  * @brief Get the size of the running action set of a model
135  *
136  * @param model The model
137  * @return The size of the running action set
138  */
139 XBT_PUBLIC(int) surf_model_running_action_set_size(surf_model_t model);
140
141 /** @brief Create a file opening action on the given host */
142 XBT_PUBLIC(surf_action_t) surf_host_open(sg_host_t host, const char* fullpath);
143
144 /** @brief Create a file closing action on the given host */
145 XBT_PUBLIC(surf_action_t) surf_host_close(sg_host_t host, surf_file_t fd);
146
147 /** @brief Create a file reading action on the given host */
148 XBT_PUBLIC(surf_action_t) surf_host_read(sg_host_t host, surf_file_t fd, sg_size_t size);
149
150 /** @brief Create a file writing action on the given host  */
151 XBT_PUBLIC(surf_action_t) surf_host_write(sg_host_t host, surf_file_t fd, sg_size_t size);
152
153 /**
154  * @brief Get the information of a file descriptor
155  * @details The returned xbt_dynar_t contains:
156  *  - the size of the file,
157  *  - the mount point,
158  *  - the storage name,
159  *  - the storage typeId,
160  *  - the storage content type
161  *
162  * @param host The surf host
163  * @param fd The file descriptor
164  * @return An xbt_dynar_t with the file information
165  */
166 XBT_PUBLIC(xbt_dynar_t) surf_host_get_info(sg_host_t host, surf_file_t fd);
167
168 /**
169  * @brief Get the available space of the storage at the mount point
170  *
171  * @param resource The surf host
172  * @param name The mount point
173  * @return The amount of available space in bytes
174  */
175 XBT_PUBLIC(sg_size_t) surf_host_get_free_size(sg_host_t resource, const char* name);
176
177 /**
178  * @brief Get the used space of the storage at the mount point
179  *
180  * @param resource The surf host
181  * @param name The mount point
182  * @return The amount of used space in bytes
183  */
184 XBT_PUBLIC(sg_size_t) surf_host_get_used_size(sg_host_t resource, const char* name);
185
186 /**
187  * @brief Unlink a file descriptor
188  *
189  * @param host The surf host
190  * @param fd The file descriptor
191  *
192  * @return 0 if failed to unlink, 1 otherwise
193  */
194 XBT_PUBLIC(int) surf_host_unlink(sg_host_t host, surf_file_t fd);
195
196 /**
197  * @brief Get the size of a file on a host
198  *
199  * @param host The surf host
200  * @param fd The file descriptor
201  *
202  * @return The size in bytes of the file
203  */
204 XBT_PUBLIC(size_t) surf_host_get_size(sg_host_t host, surf_file_t fd);
205
206 /**
207  * @brief Get the current position of the file descriptor
208  *
209  * @param host The surf host
210  * @param fd The file descriptor
211  * @return The current position of the file descriptor
212  */
213 XBT_PUBLIC(size_t) surf_host_file_tell(sg_host_t host, surf_file_t fd);
214
215 /**
216  * @brief Move a file to another location on the *same mount point*.
217  * @details [long description]
218  *
219  * @param host The surf host
220  * @param fd The file descriptor
221  * @param fullpath The new full path
222  *
223  * @return MSG_OK if successful, otherwise MSG_TASK_CANCELED
224  */
225 XBT_PUBLIC(int) surf_host_file_move(sg_host_t host, surf_file_t fd, const char* fullpath);
226
227 /**
228  * @brief Set the position indictator assiociated with the file descriptor to a new position
229  * @details [long description]
230  *
231  * @param host The surf host
232  * @param fd The file descriptor
233  * @param offset The offset from the origin
234  * @param origin Position used as a reference for the offset
235  *  - SEEK_SET: beginning of the file
236  *  - SEEK_CUR: current position indicator
237  *  - SEEK_END: end of the file
238  * @return MSG_OK if successful, otherwise MSG_TASK_CANCELED
239  */
240 XBT_PUBLIC(int) surf_host_file_seek(sg_host_t host, surf_file_t fd, sg_offset_t offset, int origin);
241
242 /**
243  * @brief Get the size in bytes of a storage
244  *
245  * @param resource The surf storage
246  * @return The size in bytes of the storage
247  */
248 XBT_PUBLIC(sg_size_t) surf_storage_get_size(surf_storage_t resource);
249
250 /**
251  * @brief Get the available size in bytes of a storage
252  *
253  * @param resource The surf storage
254  * @return The available size in bytes of the storage
255  */
256 XBT_PUBLIC(sg_size_t) surf_storage_get_free_size(surf_storage_t resource);
257
258 /**
259  * @brief Get the size in bytes of a storage
260  *
261  * @param resource The surf storage
262  * @return The used size in bytes of the storage
263  */
264 XBT_PUBLIC(sg_size_t) surf_storage_get_used_size(surf_storage_t resource);
265
266 /** @brief return the properties set associated to that storage */
267 XBT_PUBLIC(xbt_dict_t) surf_storage_get_properties(surf_storage_t resource);
268
269 /**
270  * @brief [brief description]
271  * @details [long description]
272  *
273  * @param action The surf cpu action
274  * @param bound [description]
275  */
276 XBT_PUBLIC(void) surf_cpu_action_set_bound(surf_action_t action, double bound);
277
278 /**
279  * @brief [brief description]
280  * @details [long description]
281  *
282  * @param action The surf network action
283  */
284 XBT_PUBLIC(double) surf_network_action_get_latency_limited(surf_action_t action);
285
286 /**
287  * @brief Get the file associated to a storage action
288  *
289  * @param action The surf storage action
290  * @return The file associated to a storage action
291  */
292 XBT_PUBLIC(surf_file_t) surf_storage_action_get_file(surf_action_t action);
293
294 /**
295  * @brief Get the result dictionary of an ls action
296  *
297  * @param action The surf storage action
298  * @return The dictionry listing a path
299  */
300 XBT_PUBLIC(xbt_dict_t) surf_storage_action_get_ls_dict(surf_action_t action);
301
302
303 /**
304  * @brief Get the host the storage is attached to
305  *
306  * @param resource The surf storage
307  * @return The host name
308  * may not exist.
309  */
310 XBT_PUBLIC(const char*) surf_storage_get_host(surf_storage_t resource);
311 XBT_PUBLIC(const char*) surf_storage_get_name(surf_storage_t resource);
312
313 /** @} */
314
315 /**************************************/
316 /* Implementations of model object */
317 /**************************************/
318
319 /** \ingroup SURF_models
320  *  \brief The CPU model object for the physical machine layer
321  */
322 XBT_PUBLIC_DATA(surf_cpu_model_t) surf_cpu_model_pm;
323
324 /** \ingroup SURF_models
325  *  \brief The CPU model object for the virtual machine layer
326  */
327 XBT_PUBLIC_DATA(surf_cpu_model_t) surf_cpu_model_vm;
328
329
330 /** \ingroup SURF_models
331  *  \brief Initializes the CPU model with the model Cas01
332  *
333  *  By default, this model uses the lazy optimization mechanism that relies on partial invalidation in LMM and a heap
334  *  for lazy action update.
335  *  You can change this behavior by setting the cpu/optim configuration variable to a different value.
336  *
337  *  You shouldn't have to call it by yourself.
338  */
339 XBT_PUBLIC(void) surf_cpu_model_init_Cas01();
340
341 /** \ingroup SURF_models
342  *  \brief Initializes the CPU model with trace integration [Deprecated]
343  *
344  *  You shouldn't have to call it by yourself.
345  */
346 XBT_PUBLIC(void) surf_cpu_model_init_ti();
347
348 /** \ingroup SURF_models
349  *  \brief The list of all available optimization modes (both for cpu and networks).
350  *  These optimization modes can be set using --cfg=cpu/optim:... and --cfg=network/optim:...
351  */
352 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_optimization_mode_description[];
353
354 /** \ingroup SURF_plugins
355  *  \brief The list of all available surf plugins
356  */
357 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_plugin_description[];
358
359 /** \ingroup SURF_models
360  *  \brief The list of all available cpu model models
361  */
362 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_cpu_model_description[];
363
364 /** \ingroup SURF_models
365  *  \brief The network model
366  *
367  *  When creating a new API on top on SURF, you shouldn't use the network model unless you know what you are doing.
368  *  Only the host model should be accessed because depending on the platform model, the network model can be NULL.
369  */
370 XBT_PUBLIC_DATA(surf_network_model_t) surf_network_model;
371
372 /** \ingroup SURF_models
373  *  \brief Same as network model 'LagrangeVelho', only with different correction factors.
374  *
375  * This model is proposed by Pierre-Nicolas Clauss and Martin Quinson and Stéphane Génaud based on the model 'LV08' and
376  * different correction factors depending on the communication size (< 1KiB, < 64KiB, >= 64KiB).
377  * See comments in the code for more information.
378  *
379  *  \see surf_host_model_init_SMPI()
380  */
381 XBT_PUBLIC(void) surf_network_model_init_SMPI();
382
383 /** \ingroup SURF_models
384  *  \brief Same as network model 'LagrangeVelho', only with different correction factors.
385  *
386  * This model impelments a variant of the contention model on Infinband networks based on
387  * the works of Jérôme Vienne : http://mescal.imag.fr/membres/jean-marc.vincent/index.html/PhD/Vienne.pdf
388  *
389  *  \see surf_host_model_init_IB()
390  */
391 XBT_PUBLIC(void) surf_network_model_init_IB();
392
393 /** \ingroup SURF_models
394  *  \brief Initializes the platform with the network model 'LegrandVelho'
395  *
396  * This model is proposed by Arnaud Legrand and Pedro Velho based on the results obtained with the GTNets simulator for
397  * onelink and dogbone sharing scenarios. See comments in the code for more information.
398  *
399  *  \see surf_host_model_init_LegrandVelho()
400  */
401 XBT_PUBLIC(void) surf_network_model_init_LegrandVelho();
402
403 /** \ingroup SURF_models
404  *  \brief Initializes the platform with the network model 'Constant'
405  *
406  *  In this model, the communication time between two network cards is constant, hence no need for a routing table.
407  *  This is particularly useful when simulating huge distributed algorithms where scalability is really an issue. This
408  *  function is called in conjunction with surf_host_model_init_compound.
409  *
410  *  \see surf_host_model_init_compound()
411  */
412 XBT_PUBLIC(void) surf_network_model_init_Constant();
413
414 /** \ingroup SURF_models
415  *  \brief Initializes the platform with the network model CM02
416  *
417  *  You sould call this function by yourself only if you plan using surf_host_model_init_compound.
418  *  See comments in the code for more information.
419  */
420 XBT_PUBLIC(void) surf_network_model_init_CM02();
421
422 /** \ingroup SURF_models
423  *  \brief Initializes the platform with the network model NS3
424  *
425  *  This function is called by surf_host_model_init_NS3 or by yourself only if you plan using
426  *  surf_host_model_init_compound
427  *
428  *  \see surf_host_model_init_NS3()
429  */
430 XBT_PUBLIC(void) surf_network_model_init_NS3();
431
432 /** \ingroup SURF_models
433  *  \brief Initializes the platform with the network model Reno
434  *
435  *  The problem is related to max( sum( arctan(C * Df * xi) ) ).
436  *
437  *  Reference:
438  *  [LOW03] S. H. Low. A duality model of TCP and queue management algorithms.
439  *  IEEE/ACM Transaction on Networking, 11(4):525-536, 2003.
440  *
441  *  Call this function only if you plan using surf_host_model_init_compound.
442  */
443 XBT_PUBLIC(void) surf_network_model_init_Reno();
444
445 /** \ingroup SURF_models
446  *  \brief Initializes the platform with the network model Reno2
447  *
448  *  The problem is related to max( sum( arctan(C * Df * xi) ) ).
449  *
450  *  Reference:
451  *  [LOW01] S. H. Low. A duality model of TCP and queue management algorithms.
452  *  IEEE/ACM Transaction on Networking, 11(4):525-536, 2003.
453  *
454  *  Call this function only if you plan using surf_host_model_init_compound.
455  */
456 XBT_PUBLIC(void) surf_network_model_init_Reno2();
457
458 /** \ingroup SURF_models
459  *  \brief Initializes the platform with the network model Vegas
460  *
461  *  This problem is related to max( sum( a * Df * ln(xi) ) ) which is equivalent  to the proportional fairness.
462  *
463  *  Reference:
464  *  [LOW03] S. H. Low. A duality model of TCP and queue management algorithms.
465  *  IEEE/ACM Transaction on Networking, 11(4):525-536, 2003.
466  *
467  *  Call this function only if you plan using surf_host_model_init_compound.
468  */
469 XBT_PUBLIC(void) surf_network_model_init_Vegas();
470
471 /** \ingroup SURF_models
472  *  \brief The list of all available network model models
473  */
474 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_network_model_description[];
475
476 /** \ingroup SURF_models
477  *  \brief The storage model
478  */
479 XBT_PUBLIC(void) surf_storage_model_init_default();
480
481 /** \ingroup SURF_models
482  *  \brief The list of all available storage modes.
483  *  This storage mode can be set using --cfg=storage/model:...
484  */
485 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_storage_model_description[];
486
487 XBT_PUBLIC_DATA(surf_storage_model_t) surf_storage_model;
488
489 /** \ingroup SURF_models
490  *  \brief The host model
491  *
492  *  Note that when you create an API on top of SURF, the host model should be the only one you use
493  *  because depending on the platform model, the network model and the CPU model may not exist.
494  */
495 XBT_PUBLIC_DATA(surf_host_model_t) surf_host_model;
496
497 /** \ingroup SURF_models
498  *  \brief Initializes the platform with a compound host model
499  *
500  *  This function should be called after a cpu_model and a network_model have been set up.
501  */
502 XBT_PUBLIC(void) surf_host_model_init_compound();
503
504 /** \ingroup SURF_models
505  *  \brief Initializes the platform with the current best network and cpu models at hand
506  *
507  *  This platform model separates the host model and the network model.
508  *  The host model will be initialized with the model compound, the network model with the model LV08 (with cross
509  *  traffic support) and the CPU model with the model Cas01.
510  *  Such model is subject to modification with warning in the ChangeLog so monitor it!
511  */
512 XBT_PUBLIC(void) surf_host_model_init_current_default();
513
514 /** \ingroup SURF_models
515  *  \brief Initializes the platform with the model L07
516  *
517  *  With this model, only parallel tasks can be used. Resource sharing is done by identifying bottlenecks and giving an
518  *  equal share of the model to each action.
519  */
520 XBT_PUBLIC(void) surf_host_model_init_ptask_L07();
521
522 /** \ingroup SURF_models
523  *  \brief The list of all available host model models
524  */
525 XBT_PUBLIC_DATA(s_surf_model_description_t) surf_host_model_description[];
526
527 /** \ingroup SURF_models
528  *  \brief Initializes the platform with the current best network and cpu models at hand
529  *
530  *  This platform model seperates the host model and the network model.
531  *  The host model will be initialized with the model compound, the network model with the model LV08 (with cross
532  *  traffic support) and the CPU model with the model Cas01.
533  *  Such model is subject to modification with warning in the ChangeLog so monitor it!
534  */
535 XBT_PUBLIC(void) surf_vm_model_init_HL13();
536
537 /** \ingroup SURF_simulation
538  *  \brief List of hosts for which one want to be notified if they ever restart.
539  */
540 XBT_PUBLIC_DATA(xbt_dict_t) watched_hosts_lib;
541
542 /*** SURF Globals **************************/
543
544 /** \ingroup SURF_simulation
545  *  \brief Initialize SURF
546  *  \param argc argument number
547  *  \param argv arguments
548  *
549  *  This function has to be called to initialize the common structures. Then you will have to create the environment by
550  *  calling  e.g. surf_host_model_init_CM02()
551  *
552  *  \see surf_host_model_init_CM02(), surf_host_model_init_compound(), surf_exit()
553  */
554 XBT_PUBLIC(void) surf_init(int *argc, char **argv);     /* initialize common structures */
555
556 /** \ingroup SURF_simulation
557  *  \brief Finish simulation initialization
558  *
559  *  This function must be called before the first call to surf_solve()
560  */
561 XBT_PUBLIC(void) surf_presolve();
562
563 /** \ingroup SURF_simulation
564  *  \brief Performs a part of the simulation
565  *  \param max_date Maximum date to update the simulation to, or -1
566  *  \return the elapsed time, or -1.0 if no event could be executed
567  *
568  *  This function execute all possible events, update the action states  and returns the time elapsed.
569  *  When you call execute or communicate on a model, the corresponding actions are not executed immediately but only
570  *  when you call surf_solve.
571  *  Note that the returned elapsed time can be zero.
572  */
573 XBT_PUBLIC(double) surf_solve(double max_date);
574
575 /** \ingroup SURF_simulation
576  *  \brief Return the current time
577  *
578  *  Return the current time in millisecond.
579  */
580 XBT_PUBLIC(double) surf_get_clock();
581
582 /** \ingroup SURF_simulation
583  *  \brief Exit SURF
584  *
585  *  Clean everything.
586  *
587  *  \see surf_init()
588  */
589 XBT_PUBLIC(void) surf_exit();
590
591 /* Prototypes of the functions that handle the properties */
592 XBT_PUBLIC_DATA(xbt_dict_t) current_property_set;// the prop set for the currently parsed element (also used in SIMIX)
593
594 /* surf parse file related (public because called from a test suite) */
595 XBT_PUBLIC(void) parse_platform_file(const char *file);
596
597 /* For the trace and trace:connect tag (store their content till the end of the parsing) */
598 XBT_PUBLIC_DATA(xbt_dict_t) traces_set_list;
599
600 /*
601  * Returns the initial path. On Windows the initial path is the current directory for the current process in the other
602  * case the function returns "./" that represents the current directory on Unix/Linux platforms.
603  */
604 const char *__surf_get_initial_path();
605
606 /********** Tracing **********/
607 /* from surf_instr.c */
608 void TRACE_surf_action(surf_action_t surf_action, const char *category);
609 void TRACE_surf_alloc();
610 void TRACE_surf_release();
611
612 /* instr_routing.c */
613 void instr_routing_define_callbacks ();
614 void instr_new_variable_type (const char *new_typename, const char *color);
615 void instr_new_user_variable_type  (const char *father_type, const char *new_typename, const char *color);
616 void instr_new_user_state_type (const char *father_type, const char *new_typename);
617 void instr_new_value_for_user_state_type (const char *_typename, const char *value, const char *color);
618 int instr_platform_traced ();
619 xbt_graph_t instr_routing_platform_graph ();
620 void instr_routing_platform_graph_export_graphviz (xbt_graph_t g, const char *filename);
621
622 SG_END_DECL()
623
624 #endif