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
 116 /** @} */
 117
 118 /************************** Workstation handling ****************************/
 119
 120 /** @defgroup SD_workstation_management Workstations
 121  *  @brief Functions for managing the workstations
 122  *
 123  *  This section describes the functions for managing the workstations.
 124  *
 125  *  A workstation is a place where a task can be executed.
 126  *  A workstation is represented as a <em>physical
 127  *  resource with computing capabilities</em> and has a <em>name</em>.
 128  *
 129  *  The workstations are created when you call the function SD_create_environment.
 130  *
 131  *  @see SD_workstation_t
 132  *  @{
 133  */
 134 XBT_PUBLIC(SD_workstation_t) SD_workstation_get_by_name(const char *name);
 135 XBT_PUBLIC(const SD_workstation_t *) SD_workstation_get_list(void);
 136 XBT_PUBLIC(int) SD_workstation_get_count(void);
 137 XBT_PUBLIC(void) SD_workstation_set_data(SD_workstation_t workstation,
 138                                          void *data);
 139 XBT_PUBLIC(void *) SD_workstation_get_data(SD_workstation_t workstation);
 140 XBT_PUBLIC(const char *) SD_workstation_get_name(SD_workstation_t
 141                                                  workstation);
 142 /*property handling functions*/
 143 XBT_PUBLIC(xbt_dict_t) SD_workstation_get_properties(SD_workstation_t
 144                                                      workstation);
 145 XBT_PUBLIC(const char *) SD_workstation_get_property_value(SD_workstation_t
 146                                                            workstation,
 147                                                            const char
 148                                                            *name);
 149 XBT_PUBLIC(void) SD_workstation_dump(SD_workstation_t ws);
 150 XBT_PUBLIC(const SD_link_t *) SD_route_get_list(SD_workstation_t src,
 151                                                 SD_workstation_t dst);
 152 XBT_PUBLIC(int) SD_route_get_size(SD_workstation_t src,
 153                                   SD_workstation_t dst);
 154 XBT_PUBLIC(double) SD_workstation_get_power(SD_workstation_t workstation);
 155 XBT_PUBLIC(double) SD_workstation_get_available_power(SD_workstation_t
 156                                                       workstation);
 157 XBT_PUBLIC(int) SD_workstation_get_cores(SD_workstation_t workstation);
 158 XBT_PUBLIC(e_SD_workstation_access_mode_t)
 159     SD_workstation_get_access_mode(SD_workstation_t workstation);
 160 XBT_PUBLIC(void) SD_workstation_set_access_mode(SD_workstation_t
 161                                                 workstation,
 162                                                 e_SD_workstation_access_mode_t
 163                                                 access_mode);
 164
 165 XBT_PUBLIC(double) SD_workstation_get_computation_time(SD_workstation_t workstation,
 166                                                        double flops_amount);
 167 XBT_PUBLIC(double) SD_route_get_latency(SD_workstation_t src,
 168                                                 SD_workstation_t dst);
 169 XBT_PUBLIC(double) SD_route_get_bandwidth(SD_workstation_t src,
 170                                                   SD_workstation_t dst);
 171 XBT_PUBLIC(double) SD_route_get_communication_time(SD_workstation_t src,
 172                                                    SD_workstation_t dst,
 173                                                    double bytes_amount);
 174
 175 XBT_PUBLIC(SD_task_t) SD_workstation_get_current_task(SD_workstation_t workstation);
 176 XBT_PUBLIC(xbt_dict_t)
 177     SD_workstation_get_mounted_storage_list(SD_workstation_t workstation);
 178 XBT_PUBLIC(xbt_dynar_t)
 179     SD_workstation_get_attached_storage_list(SD_workstation_t workstation);
 180 XBT_PUBLIC(const char*) SD_storage_get_host(SD_storage_t storage);
 181 /** @} */
 182
 183 /************************** Task handling ************************************/
 184
 185 /** @defgroup SD_task_management Tasks
 186  *  @brief Functions for managing the tasks
 187  *
 188  *  This section describes the functions for managing the tasks.
 189  *
 190  *  A task is some <em>working amount</em> that can be executed
 191  *  in parallel on several workstations. A task may depend on other
 192  *  tasks, this means that the task cannot start until the other tasks are done.
 193  *  Each task has a <em>\ref e_SD_task_state_t "state"</em> indicating whether
 194  *  the task is scheduled, running, done, etc.
 195  *
 196  *  @see SD_task_t, SD_task_dependency_management
 197  *  @{
 198  */
 199 XBT_PUBLIC(SD_task_t) SD_task_create(const char *name, void *data,
 200                                      double amount);
 201 XBT_PUBLIC(void *) SD_task_get_data(SD_task_t task);
 202 XBT_PUBLIC(void) SD_task_set_data(SD_task_t task, void *data);
 203 XBT_PUBLIC(e_SD_task_state_t) SD_task_get_state(SD_task_t task);
 204 XBT_PUBLIC(const char *) SD_task_get_name(SD_task_t task);
 205 XBT_PUBLIC(void) SD_task_set_name(SD_task_t task, const char *name);
 206 XBT_PUBLIC(void) SD_task_set_rate(SD_task_t task, double rate);
 207
 208 XBT_PUBLIC(void) SD_task_watch(SD_task_t task, e_SD_task_state_t state);
 209 XBT_PUBLIC(void) SD_task_unwatch(SD_task_t task, e_SD_task_state_t state);
 210 XBT_PUBLIC(double) SD_task_get_amount(SD_task_t task);
 211 XBT_PUBLIC(void) SD_task_set_amount(SD_task_t task, double amount);
 212 XBT_PUBLIC(double) SD_task_get_alpha(SD_task_t task);
 213 XBT_PUBLIC(double) SD_task_get_remaining_amount(SD_task_t task);
 214 XBT_PUBLIC(double) SD_task_get_execution_time(SD_task_t task,
 215                                               int workstation_nb,
 216                                               const SD_workstation_t *
 217                                               workstation_list,
 218                                               const double *flops_amount,
 219                                               const double *bytes_amount);
 220 XBT_PUBLIC(e_SD_task_kind_t) SD_task_get_kind(SD_task_t task);
 221 XBT_PUBLIC(void) SD_task_schedule(SD_task_t task, int workstation_nb,
 222                                   const SD_workstation_t *
 223                                   workstation_list,
 224                                   const double *flops_amount,
 225                                   const double *bytes_amount,
 226                                   double rate);
 227 XBT_PUBLIC(void) SD_task_unschedule(SD_task_t task);
 228 XBT_PUBLIC(double) SD_task_get_start_time(SD_task_t task);
 229 XBT_PUBLIC(double) SD_task_get_finish_time(SD_task_t task);
 230 XBT_PUBLIC(xbt_dynar_t) SD_task_get_parents(SD_task_t task);
 231 XBT_PUBLIC(xbt_dynar_t) SD_task_get_children(SD_task_t task);
 232 XBT_PUBLIC(int) SD_task_get_workstation_count(SD_task_t task);
 233 XBT_PUBLIC(SD_workstation_t *) SD_task_get_workstation_list(SD_task_t
 234                                                             task);
 235 XBT_PUBLIC(void) SD_task_destroy(SD_task_t task);
 236 XBT_PUBLIC(void) SD_task_dump(SD_task_t task);
 237 XBT_PUBLIC(void) SD_task_dotty(SD_task_t task, void *out_FILE);
 238
 239 XBT_PUBLIC(SD_task_t) SD_task_create_comp_seq(const char *name, void *data,
 240                                               double amount);
 241 XBT_PUBLIC(SD_task_t) SD_task_create_comp_par_amdahl(const char *name,
 242                                                      void *data,
 243                                                      double amount,
 244                                                      double alpha);
 245 XBT_PUBLIC(SD_task_t) SD_task_create_comm_e2e(const char *name, void *data,
 246                                               double amount);
 247 XBT_PUBLIC(SD_task_t) SD_task_create_comm_par_mxn_1d_block(const char *name,
 248                                                            void *data,
 249                                                            double amount);
 250
 251 XBT_PUBLIC(void) SD_task_distribute_comp_amdahl(SD_task_t task, int ws_count);
 252 XBT_PUBLIC(void) SD_task_schedulev(SD_task_t task, int count,
 253                                    const SD_workstation_t * list);
 254 XBT_PUBLIC(void) SD_task_schedulel(SD_task_t task, int count, ...);
 255
 256
 257 /** @brief A constant to use in SD_task_schedule to mean that there is no cost.
 258  *
 259  *  For example, create a pure computation task (no comm) like this:
 260  *
 261  *  SD_task_schedule(task, my_workstation_nb,
 262  *                   my_workstation_list,
 263  *                   my_flops_amount,
 264  *                   SD_TASK_SCHED_NO_COST,
 265  *                   my_rate);
 266  */
 267 #define SD_SCHED_NO_COST NULL
 268
 269 /** @} */
 270
 271
 272 /** @defgroup SD_task_dependency_management Tasks dependencies
 273  *  @brief Functions for managing the task dependencies
 274  *
 275  *  This section describes the functions for managing the dependencies between the tasks.
 276  *
 277  *  @see SD_task_management
 278  *  @{
 279  */
 280 XBT_PUBLIC(void) SD_task_dependency_add(const char *name, void *data,
 281                                         SD_task_t src, SD_task_t dst);
 282 XBT_PUBLIC(void) SD_task_dependency_remove(SD_task_t src, SD_task_t dst);
 283 XBT_PUBLIC(const char *) SD_task_dependency_get_name(SD_task_t src,
 284                                                      SD_task_t dst);
 285 XBT_PUBLIC(void *) SD_task_dependency_get_data(SD_task_t src,
 286                                                SD_task_t dst);
 287 XBT_PUBLIC(int) SD_task_dependency_exists(SD_task_t src, SD_task_t dst);
 288 /** @} */
 289
 290 /************************** Global *******************************************/
 291
 292 /** @defgroup SD_simulation Simulation
 293  *  @brief Functions for creating the environment and launching the simulation
 294  *
 295  *  This section describes the functions for initializing SimDag, launching
 296  *  the simulation and exiting SimDag.
 297  *
 298  *  @{
 299  */
 300 XBT_PUBLIC(void) SD_init(int *argc, char **argv);
 301 XBT_PUBLIC(void) SD_config(const char *key, const char *value);
 302 XBT_PUBLIC(void) SD_application_reinit(void);
 303 XBT_PUBLIC(void) SD_create_environment(const char *platform_file);
 304 XBT_PUBLIC(xbt_dynar_t) SD_simulate(double how_long);
 305 XBT_PUBLIC(double) SD_get_clock(void);
 306 XBT_PUBLIC(void) SD_exit(void);
 307 XBT_PUBLIC(xbt_dynar_t) SD_daxload(const char *filename);
 308 XBT_PUBLIC(xbt_dynar_t) SD_dotload(const char *filename);
 309 XBT_PUBLIC(xbt_dynar_t) SD_PTG_dotload(const char *filename);
 310 XBT_PUBLIC(xbt_dynar_t) SD_dotload_with_sched(const char *filename);
 311 XBT_PUBLIC(void) uniq_transfer_task_name(SD_task_t task);
 312
 313 /** @} */
 314
 315 SG_END_DECL()
 316
 317 #include "simgrid/instr.h"
 318
 319 #endif