include/simgrid/simdag.h

   1 /* Copyright (c) 2006-2010, 2012-2015. 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 sg_host_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 /************************** Link handling ***********************************/
 102 /** @defgroup SD_link_management Links
 103  *  @brief Functions for managing the network links
 104  *
 105  *  This section describes the functions for managing the network links.
 106  *
 107  *  A link is a network node represented as a <em>name</em>, a <em>current
 108  *  bandwidth</em> and a <em>current latency</em>. The links are created
 109  *  when you call the function SD_create_environment.
 110  *
 111  *  @see SD_link_t
 112  *  @{
 113  */
 114 XBT_PUBLIC(const SD_link_t *) SD_link_get_list(void);
 115 /** @brief Returns the number of links in the whole platform */
 116 static inline int SD_link_get_number(void) {
 117   return sg_link_amount();
 118 }
 119
 120 /** @brief Returns the user data of a link */
 121 static inline void *SD_link_get_data(SD_link_t link) {
 122   return sg_link_data(link);
 123 }
 124
 125 /** @brief Sets the user data of a link
 126  *
 127  * The new data can be \c NULL. The old data should have been freed first
 128  * if it was not \c NULL.
 129  */
 130 static inline void SD_link_set_data(SD_link_t link, void *data) {
 131         sg_link_data_set(link, data);
 132 }
 133 /** @brief Returns the name of a link  */
 134 static inline const char *SD_link_get_name(SD_link_t link) {
 135   return sg_link_name(link);
 136 }
 137 /** @brief Returns the current bandwidth of a link (in bytes per second) */
 138 static inline double SD_link_get_current_bandwidth(SD_link_t link) {
 139   return sg_link_bandwidth(link);
 140 }
 141 /** @brief Returns the current latency of a link (in seconds) */
 142 static inline double SD_link_get_current_latency(SD_link_t link){
 143   return sg_link_latency(link);
 144 }
 145 /** @brief Returns the sharing policy of this workstation.
 146  *  @return true if the link is shared, and false if it's a fatpipe
 147  */
 148 static inline int SD_link_is_shared(SD_link_t link) {
 149   return sg_link_is_shared(link);
 150 }
 151 /** @} */
 152
 153 /************************** Workstation handling ****************************/
 154
 155 /** @defgroup SD_workstation_management Workstations
 156  *  @brief Functions for managing the workstations
 157  *
 158  *  This section describes the functions for managing the workstations.
 159  *
 160  *  A workstation is a place where a task can be executed.
 161  *  A workstation is represented as a <em>physical
 162  *  resource with computing capabilities</em> and has a <em>name</em>.
 163  *
 164  *  The workstations are created when you call the function SD_create_environment.
 165  *
 166  *  @see SD_workstation_t
 167  *  @{
 168  */
 169 XBT_PUBLIC(SD_workstation_t) SD_workstation_get_by_name(const char *name);
 170 XBT_PUBLIC(const SD_workstation_t *) SD_workstation_get_list(void);
 171 XBT_PUBLIC(int) SD_workstation_get_number(void);
 172 XBT_PUBLIC(void) SD_workstation_set_data(SD_workstation_t workstation,
 173                                          void *data);
 174 XBT_PUBLIC(void *) SD_workstation_get_data(SD_workstation_t workstation);
 175 XBT_PUBLIC(const char *) SD_workstation_get_name(SD_workstation_t
 176                                                  workstation);
 177 /*property handling functions*/
 178 XBT_PUBLIC(xbt_dict_t) SD_workstation_get_properties(SD_workstation_t
 179                                                      workstation);
 180 XBT_PUBLIC(const char *) SD_workstation_get_property_value(SD_workstation_t
 181                                                            workstation,
 182                                                            const char
 183                                                            *name);
 184 XBT_PUBLIC(void) SD_workstation_dump(SD_workstation_t ws);
 185 XBT_PUBLIC(const SD_link_t *) SD_route_get_list(SD_workstation_t src,
 186                                                 SD_workstation_t dst);
 187 XBT_PUBLIC(int) SD_route_get_size(SD_workstation_t src,
 188                                   SD_workstation_t dst);
 189 XBT_PUBLIC(double) SD_workstation_get_power(SD_workstation_t workstation);
 190 XBT_PUBLIC(double) SD_workstation_get_available_power(SD_workstation_t
 191                                                       workstation);
 192 XBT_PUBLIC(int) SD_workstation_get_cores(SD_workstation_t workstation);
 193 XBT_PUBLIC(e_SD_workstation_access_mode_t)
 194     SD_workstation_get_access_mode(SD_workstation_t workstation);
 195 XBT_PUBLIC(void) SD_workstation_set_access_mode(SD_workstation_t
 196                                                 workstation,
 197                                                 e_SD_workstation_access_mode_t
 198                                                 access_mode);
 199
 200 XBT_PUBLIC(double) SD_workstation_get_computation_time(SD_workstation_t workstation,
 201                                                        double flops_amount);
 202 XBT_PUBLIC(double) SD_route_get_current_latency(SD_workstation_t src,
 203                                                 SD_workstation_t dst);
 204 XBT_PUBLIC(double) SD_route_get_current_bandwidth(SD_workstation_t src,
 205                                                   SD_workstation_t dst);
 206 XBT_PUBLIC(double) SD_route_get_communication_time(SD_workstation_t src,
 207                                                    SD_workstation_t dst,
 208                                                    double bytes_amount);
 209
 210 XBT_PUBLIC(SD_task_t) SD_workstation_get_current_task(SD_workstation_t workstation);
 211 XBT_PUBLIC(xbt_dict_t)
 212     SD_workstation_get_mounted_storage_list(SD_workstation_t workstation);
 213 XBT_PUBLIC(xbt_dynar_t)
 214     SD_workstation_get_attached_storage_list(SD_workstation_t workstation);
 215 XBT_PUBLIC(const char*) SD_storage_get_host(SD_storage_t storage);
 216 /** @} */
 217
 218 /************************** Task handling ************************************/
 219
 220 /** @defgroup SD_task_management Tasks
 221  *  @brief Functions for managing the tasks
 222  *
 223  *  This section describes the functions for managing the tasks.
 224  *
 225  *  A task is some <em>working amount</em> that can be executed
 226  *  in parallel on several workstations. A task may depend on other
 227  *  tasks, this means that the task cannot start until the other tasks are done.
 228  *  Each task has a <em>\ref e_SD_task_state_t "state"</em> indicating whether
 229  *  the task is scheduled, running, done, etc.
 230  *
 231  *  @see SD_task_t, SD_task_dependency_management
 232  *  @{
 233  */
 234 XBT_PUBLIC(SD_task_t) SD_task_create(const char *name, void *data,
 235                                      double amount);
 236 XBT_PUBLIC(void *) SD_task_get_data(SD_task_t task);
 237 XBT_PUBLIC(void) SD_task_set_data(SD_task_t task, void *data);
 238 XBT_PUBLIC(e_SD_task_state_t) SD_task_get_state(SD_task_t task);
 239 XBT_PUBLIC(const char *) SD_task_get_name(SD_task_t task);
 240 XBT_PUBLIC(void) SD_task_set_name(SD_task_t task, const char *name);
 241 XBT_PUBLIC(void) SD_task_set_rate(SD_task_t task, double rate);
 242
 243 XBT_PUBLIC(void) SD_task_watch(SD_task_t task, e_SD_task_state_t state);
 244 XBT_PUBLIC(void) SD_task_unwatch(SD_task_t task, e_SD_task_state_t state);
 245 XBT_PUBLIC(double) SD_task_get_amount(SD_task_t task);
 246 XBT_PUBLIC(void) SD_task_set_amount(SD_task_t task, double amount);
 247 XBT_PUBLIC(double) SD_task_get_alpha(SD_task_t task);
 248 XBT_PUBLIC(double) SD_task_get_remaining_amount(SD_task_t task);
 249 XBT_PUBLIC(double) SD_task_get_execution_time(SD_task_t task,
 250                                               int workstation_nb,
 251                                               const SD_workstation_t *
 252                                               workstation_list,
 253                                               const double *flops_amount,
 254                                               const double *bytes_amount);
 255 XBT_PUBLIC(e_SD_task_kind_t) SD_task_get_kind(SD_task_t task);
 256 XBT_PUBLIC(void) SD_task_schedule(SD_task_t task, int workstation_nb,
 257                                   const SD_workstation_t *
 258                                   workstation_list,
 259                                   const double *flops_amount,
 260                                   const double *bytes_amount,
 261                                   double rate);
 262 XBT_PUBLIC(void) SD_task_unschedule(SD_task_t task);
 263 XBT_PUBLIC(double) SD_task_get_start_time(SD_task_t task);
 264 XBT_PUBLIC(double) SD_task_get_finish_time(SD_task_t task);
 265 XBT_PUBLIC(xbt_dynar_t) SD_task_get_parents(SD_task_t task);
 266 XBT_PUBLIC(xbt_dynar_t) SD_task_get_children(SD_task_t task);
 267 XBT_PUBLIC(int) SD_task_get_workstation_count(SD_task_t task);
 268 XBT_PUBLIC(SD_workstation_t *) SD_task_get_workstation_list(SD_task_t
 269                                                             task);
 270 XBT_PUBLIC(void) SD_task_destroy(SD_task_t task);
 271 XBT_PUBLIC(void) SD_task_dump(SD_task_t task);
 272 XBT_PUBLIC(void) SD_task_dotty(SD_task_t task, void *out_FILE);
 273
 274 XBT_PUBLIC(SD_task_t) SD_task_create_comp_seq(const char *name, void *data,
 275                                               double amount);
 276 XBT_PUBLIC(SD_task_t) SD_task_create_comp_par_amdahl(const char *name,
 277                                                      void *data,
 278                                                      double amount,
 279                                                      double alpha);
 280 XBT_PUBLIC(SD_task_t) SD_task_create_comm_e2e(const char *name, void *data,
 281                                               double amount);
 282 XBT_PUBLIC(SD_task_t) SD_task_create_comm_par_mxn_1d_block(const char *name,
 283                                                            void *data,
 284                                                            double amount);
 285
 286 XBT_PUBLIC(void) SD_task_distribute_comp_amdahl(SD_task_t task, int ws_count);
 287 XBT_PUBLIC(void) SD_task_schedulev(SD_task_t task, int count,
 288                                    const SD_workstation_t * list);
 289 XBT_PUBLIC(void) SD_task_schedulel(SD_task_t task, int count, ...);
 290
 291
 292 /** @brief A constant to use in SD_task_schedule to mean that there is no cost.
 293  *
 294  *  For example, create a pure computation task (no comm) like this:
 295  *
 296  *  SD_task_schedule(task, my_workstation_nb,
 297  *                   my_workstation_list,
 298  *                   my_flops_amount,
 299  *                   SD_TASK_SCHED_NO_COST,
 300  *                   my_rate);
 301  */
 302 #define SD_SCHED_NO_COST NULL
 303
 304 /** @} */
 305
 306
 307 /** @defgroup SD_task_dependency_management Tasks dependencies
 308  *  @brief Functions for managing the task dependencies
 309  *
 310  *  This section describes the functions for managing the dependencies between the tasks.
 311  *
 312  *  @see SD_task_management
 313  *  @{
 314  */
 315 XBT_PUBLIC(void) SD_task_dependency_add(const char *name, void *data,
 316                                         SD_task_t src, SD_task_t dst);
 317 XBT_PUBLIC(void) SD_task_dependency_remove(SD_task_t src, SD_task_t dst);
 318 XBT_PUBLIC(const char *) SD_task_dependency_get_name(SD_task_t src,
 319                                                      SD_task_t dst);
 320 XBT_PUBLIC(void *) SD_task_dependency_get_data(SD_task_t src,
 321                                                SD_task_t dst);
 322 XBT_PUBLIC(int) SD_task_dependency_exists(SD_task_t src, SD_task_t dst);
 323 /** @} */
 324
 325 /************************** Global *******************************************/
 326
 327 /** @defgroup SD_simulation Simulation
 328  *  @brief Functions for creating the environment and launching the simulation
 329  *
 330  *  This section describes the functions for initializing SimDag, launching
 331  *  the simulation and exiting SimDag.
 332  *
 333  *  @{
 334  */
 335 XBT_PUBLIC(void) SD_init(int *argc, char **argv);
 336 XBT_PUBLIC(void) SD_config(const char *key, const char *value);
 337 XBT_PUBLIC(void) SD_application_reinit(void);
 338 XBT_PUBLIC(void) SD_create_environment(const char *platform_file);
 339 XBT_PUBLIC(xbt_dynar_t) SD_simulate(double how_long);
 340 XBT_PUBLIC(double) SD_get_clock(void);
 341 XBT_PUBLIC(void) SD_exit(void);
 342 XBT_PUBLIC(xbt_dynar_t) SD_daxload(const char *filename);
 343 XBT_PUBLIC(xbt_dynar_t) SD_dotload(const char *filename);
 344 XBT_PUBLIC(xbt_dynar_t) SD_PTG_dotload(const char *filename);
 345 XBT_PUBLIC(xbt_dynar_t) SD_dotload_with_sched(const char *filename);
 346 XBT_PUBLIC(void) uniq_transfer_task_name(SD_task_t task);
 347
 348 /** @} */
 349
 350 SG_END_DECL()
 351
 352 #include "simgrid/instr.h"
 353
 354 #endif