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