SimGrid: Tasks

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Functions
Tasks
SimDag

Functions for managing the tasks. More...

## Macros
#define | SD_SCHED_NO_COST NULL
| A constant to use in SD_task_schedule to mean that there is no cost.

## Functions
SD_task_t | SD_task_create (const char *name, void *data, double amount)
| Creates a new task.
void * | SD_task_get_data (SD_task_t task)
| Returns the user data of a task.
void | SD_task_set_data (SD_task_t task, void *data)
| Sets the user data of a task.
e_SD_task_state_t | SD_task_get_state (SD_task_t task)
| Returns the state of a task.
const char * | SD_task_get_name (SD_task_t task)
| Returns the name of a task.
void | SD_task_set_name (SD_task_t task, const char *name)
| Allows to change the name of a task.
void | SD_task_set_rate (SD_task_t task, double rate)
| Sets the rate of a task.
void | SD_task_watch (SD_task_t task, e_SD_task_state_t state)
| Adds a watch point to a task.
void | SD_task_unwatch (SD_task_t task, e_SD_task_state_t state)
| Removes a watch point from a task.
double | SD_task_get_amount (SD_task_t task)
| Returns the total amount of work contained in a task.
void | SD_task_set_amount (SD_task_t task, double amount)
| Sets the total amount of work of a task For sequential typed tasks (COMP_SEQ and COMM_E2E), it also sets the appropriate values in the computation_amount and communication_amount arrays respectively. Nothing more than modifying task->amount is done for paralle typed tasks (COMP_PAR_AMDAHL and COMM_PAR_MXN_1D_BLOCK) as the distribution of the amount of work is done at scheduling time.
double | SD_task_get_alpha (SD_task_t task)
| Returns the alpha parameter of a SD_TASK_COMP_PAR_AMDAHL task.
double | SD_task_get_remaining_amount (SD_task_t task)
| Returns the remaining amount work to do till the completion of a task.
double | SD_task_get_execution_time (SD_task_t task, int workstation_nb, const SD_workstation_t *workstation_list, const double *computation_amount, const double *communication_amount)
| Returns an approximative estimation of the execution time of a task.
void | SD_task_schedule (SD_task_t task, int workstation_nb, const SD_workstation_t *workstation_list, const double *computation_amount, const double *communication_amount, double rate)
| Schedules a task.
void | SD_task_unschedule (SD_task_t task)
| Unschedules a task.
double | SD_task_get_start_time (SD_task_t task)
| Returns the start time of a task.
double | SD_task_get_finish_time (SD_task_t task)
| Returns the finish time of a task.
xbt_dynar_t | SD_task_get_parents (SD_task_t task)
| Returns the dynar of the parents of a task.
xbt_dynar_t | SD_task_get_children (SD_task_t task)
| Returns the dynar of the parents of a task.
int | SD_task_get_workstation_count (SD_task_t task)
| Returns the amount of workstations involved in a task.
SD_workstation_t * | SD_task_get_workstation_list (SD_task_t task)
| Returns the list of workstations involved in a task.
void | SD_task_destroy (SD_task_t task)
| Destroys a task.
void | SD_task_dump (SD_task_t task)
| Displays debugging informations about a task.
void | SD_task_dotty (SD_task_t task, void *out_FILE)
| Dumps the task in dotty formalism into the FILE* passed as second argument.
SD_task_t | SD_task_create_comp_seq (const char *name, void *data, double amount)
| create a sequential computation task that can then be auto-scheduled
SD_task_t | SD_task_create_comp_par_amdahl (const char *name, void *data, double amount, double alpha)
| create a parallel computation task that can then be auto-scheduled
SD_task_t | SD_task_create_comm_e2e (const char *name, void *data, double amount)
| create a end-to-end communication task that can then be auto-scheduled
SD_task_t | SD_task_create_comm_par_mxn_1d_block (const char *name, void *data, double amount)
| create a complex data redistribution task that can then be auto-scheduled
void | SD_task_distribute_comp_amdahl (SD_task_t task, int ws_count)
| Blah.
void | SD_task_schedulev (SD_task_t task, int count, const SD_workstation_t *list)
| Auto-schedules a task.
void | SD_task_schedulel (SD_task_t task, int count,...)
| autoschedule a task on a list of workstations

## Detailed Description

Functions for managing the tasks.

This section describes the functions for managing the tasks.

A task is some working amount that can be executed in parallel on several workstations. A task may depend on other tasks, this means that the task cannot start until the other tasks are done. Each task has a state indicating whether the task is scheduled, running, done, etc.

See Also
  SD_task_t, Tasks dependencies

## Macro Definition Documentation

#define SD_SCHED_NO_COST NULL

A constant to use in SD_task_schedule to mean that there is no cost.

For example, create a pure computation task (no comm) like this:

SD_task_schedule(task, my_workstation_nb, my_workstation_list, my_computation_amount, SD_TASK_SCHED_NO_COST, my_rate);

## Function Documentation

SD_task_t SD_task_create | ( | const char * | name,
|  | void * | data,
|  | double | amount
| ) |  |

Creates a new task.

Parameters

  name | the name of the task (can be `NULL`)
  data | the user data you want to associate with the task (can be `NULL`)
  amount | amount of the task

Returns
  the new task

See Also
  SD_task_destroy()

void* SD_task_get_data | ( | SD_task_t | task | ) |

Returns the user data of a task.

Parameters

  task | a task

Returns
  the user data associated with this task (can be `NULL`)

See Also
  SD_task_set_data()

void SD_task_set_data | ( | SD_task_t | task,
|  | void * | data
| ) |  |

Sets the user data of a task.

The new data can be `NULL`. The old data should have been freed first if it was not `NULL`.

Parameters

  task | a task
  data | the new data you want to associate with this task

See Also
  SD_task_get_data()

e_SD_task_state_t SD_task_get_state | ( | SD_task_t | task | ) |

Returns the state of a task.

Parameters

  task | a task

Returns
  the current state of this task: SD_NOT_SCHEDULED, SD_SCHEDULED, SD_RUNNABLE, SD_RUNNING, SD_DONE or SD_FAILED

See Also
  e_SD_task_state_t

const char* SD_task_get_name | ( | SD_task_t | task | ) |

Returns the name of a task.

Parameters

  task | a task

Returns
  the name of this task (can be `NULL`)

void SD_task_set_rate | ( | SD_task_t | task,
|  | double | rate
| ) |  |

Sets the rate of a task.

This will change the network bandwidth a task can use. This rate depends on both the nominal bandwidth on the route onto which the task is scheduled (

See Also
  SD_task_get_current_bandwidth) and the amount of data to transfer.

To divide the nominal bandwidth by 2, the rate then has to be : rate = bandwidth/(2*amount)

Parameters

  task | a

See Also
  SD_TASK_COMM_E2E task (end-to-end communication)

Parameters

  rate | the new rate you want to associate with this task.

void SD_task_watch | ( | SD_task_t | task,
|  | e_SD_task_state_t | state
| ) |  |

Adds a watch point to a task.

SD_simulate() will stop as soon as the state of this task becomes the one given in argument. The watch point is then automatically removed.

Parameters

  task | a task
  state | the state you want to watch (cannot be SD_NOT_SCHEDULED)

See Also
  SD_task_unwatch()

void SD_task_unwatch | ( | SD_task_t | task,
|  | e_SD_task_state_t | state
| ) |  |

Removes a watch point from a task.

Parameters

  task | a task
  state | the state you no longer want to watch

See Also
  SD_task_watch()

double SD_task_get_amount | ( | SD_task_t | task | ) |

Returns the total amount of work contained in a task.

Parameters

  task | a task

Returns
  the total amount of work (computation or data transfer) for this task

See Also
  SD_task_get_remaining_amount()

void SD_task_set_amount | ( | SD_task_t | task,
|  | double | amount
| ) |  |

Sets the total amount of work of a task For sequential typed tasks (COMP_SEQ and COMM_E2E), it also sets the appropriate values in the computation_amount and communication_amount arrays respectively. Nothing more than modifying task->amount is done for paralle typed tasks (COMP_PAR_AMDAHL and COMM_PAR_MXN_1D_BLOCK) as the distribution of the amount of work is done at scheduling time.

Parameters

  task | a task
  amount | the new amount of work to execute

double SD_task_get_alpha | ( | SD_task_t | task | ) |

Returns the alpha parameter of a SD_TASK_COMP_PAR_AMDAHL task.

Parameters

  task | a parallel task assuming Amdahl's law as speedup model

Returns
  the alpha parameter (serial part of a task in percent) for this task

double SD_task_get_remaining_amount | ( | SD_task_t | task | ) |

Returns the remaining amount work to do till the completion of a task.

Parameters

  task | a task

Returns
  the remaining amount of work (computation or data transfer) of this task

See Also
  SD_task_get_amount()

double SD_task_get_execution_time | ( | SD_task_t | task,
|  | int | workstation_nb,
|  | const SD_workstation_t * | workstation_list,
|  | const double * | computation_amount,
|  | const double * | communication_amount
| ) |  |

Returns an approximative estimation of the execution time of a task.

The estimation is very approximative because the value returned is the time the task would take if it was executed now and if it was the only task.

Parameters

  task | the task to evaluate
  workstation_nb | number of workstations on which the task would be executed
  workstation_list | the workstations on which the task would be executed
  computation_amount | computation amount for each workstation
  communication_amount | communication amount between each pair of workstations

See Also
  SD_schedule()

void SD_task_schedule | ( | SD_task_t | task,
|  | int | workstation_count,
|  | const SD_workstation_t * | workstation_list,
|  | const double * | computation_amount,
|  | const double * | communication_amount,
|  | double | rate
| ) |  |

Schedules a task.

The task state must be SD_NOT_SCHEDULED. Once scheduled, a task will be executed as soon as possible in SD_simulate(), i.e. when its dependencies are satisfied.

Parameters

  task | the task you want to schedule
  workstation_count | number of workstations on which the task will be executed
  workstation_list | the workstations on which the task will be executed
  computation_amount | computation amount for each workstation
  communication_amount | communication amount between each pair of workstations
  rate | task execution speed rate

See Also
  SD_task_unschedule()

void SD_task_unschedule | ( | SD_task_t | task | ) |

Unschedules a task.

The task state must be SD_SCHEDULED, SD_RUNNABLE, SD_RUNNING or SD_FAILED. If you call this function, the task state becomes SD_NOT_SCHEDULED. Call SD_task_schedule() to schedule it again.

Parameters

  task | the task you want to unschedule

See Also
  SD_task_schedule()

double SD_task_get_start_time | ( | SD_task_t | task | ) |

Returns the start time of a task.

The task state must be SD_RUNNING, SD_DONE or SD_FAILED.

Parameters

  task,: | a task

Returns
  the start time of this task

double SD_task_get_finish_time | ( | SD_task_t | task | ) |

Returns the finish time of a task.

The task state must be SD_RUNNING, SD_DONE or SD_FAILED. If the state is not completed yet, the returned value is an estimation of the task finish time. This value can fluctuate until the task is completed.

Parameters

  task,: | a task

Returns
  the start time of this task

xbt_dynar_t SD_task_get_parents | ( | SD_task_t | task | ) |

Returns the dynar of the parents of a task.

Parameters

  task | a task

Returns
  a newly allocated dynar comprising the parents of this task

xbt_dynar_t SD_task_get_children | ( | SD_task_t | task | ) |

Returns the dynar of the parents of a task.

Parameters

  task | a task

Returns
  a newly allocated dynar comprising the parents of this task

int SD_task_get_workstation_count | ( | SD_task_t | task | ) |

Returns the amount of workstations involved in a task.

Only call this on already scheduled tasks!

Parameters

  task | a task

SD_workstation_t* SD_task_get_workstation_list | ( | SD_task_t | task | ) |

Returns the list of workstations involved in a task.

Only call this on already scheduled tasks!

Parameters

  task | a task

void SD_task_destroy | ( | SD_task_t | task | ) |

Destroys a task.

The user data (if any) should have been destroyed first.

Parameters

  task | the task you want to destroy

See Also
  SD_task_create()

SD_task_t SD_task_create_comp_seq | ( | const char * | name,
|  | void * | data,
|  | double | amount
| ) |  |

create a sequential computation task that can then be auto-scheduled

Auto-scheduling mean that the task can be used with SD_task_schedulev(). This allows to specify the task costs at creation, and decouple them from the scheduling process where you just specify which resource should deliver the mandatory power.

A sequential computation must be scheduled on 1 host, and the amount specified at creation to be run on hosts[0].

Parameters

  name | the name of the task (can be `NULL`)
  data | the user data you want to associate with the task (can be `NULL`)
  amount | amount of compute work to be done by the task

Returns
  the new SD_TASK_COMP_SEQ typed task

SD_task_t SD_task_create_comp_par_amdahl | ( | const char * | name,
|  | void * | data,
|  | double | amount,
|  | double | alpha
| ) |  |

create a parallel computation task that can then be auto-scheduled

Auto-scheduling mean that the task can be used with SD_task_schedulev(). This allows to specify the task costs at creation, and decouple them from the scheduling process where you just specify which resource should deliver the mandatory power.

A parallel computation can be scheduled on any number of host. The underlying speedup model is Amdahl's law. To be auto-scheduled,

See Also
  SD_task_distribute_comp_amdahl has to be called first.

Parameters

  name | the name of the task (can be `NULL`)
  data | the user data you want to associate with the task (can be `NULL`)
  amount | amount of compute work to be done by the task
  alpha | purely serial fraction of the work to be done (in [0.;1.[)

Returns
  the new task

SD_task_t SD_task_create_comm_e2e | ( | const char * | name,
|  | void * | data,
|  | double | amount
| ) |  |

create a end-to-end communication task that can then be auto-scheduled

Auto-scheduling mean that the task can be used with SD_task_schedulev(). This allows to specify the task costs at creation, and decouple them from the scheduling process where you just specify which resource should deliver the mandatory power.

A end-to-end communication must be scheduled on 2 hosts, and the amount specified at creation is sent from hosts[0] to hosts[1].

SD_task_t SD_task_create_comm_par_mxn_1d_block | ( | const char * | name,
|  | void * | data,
|  | double | amount
| ) |  |

create a complex data redistribution task that can then be auto-scheduled

Auto-scheduling mean that the task can be used with SD_task_schedulev(). This allows to specify the task costs at creation, and decouple them from the scheduling process where you just specify which resource should communicate.

A data redistribution can be scheduled on any number of host. The assumed distribution is a 1D block distribution. Each host owns the same share of the

See Also
  amount. To be auto-scheduled,
  SD_task_distribute_comm_mxn_1d_block has to be called first.

Parameters

  name | the name of the task (can be `NULL`)
  data | the user data you want to associate with the task (can be `NULL`)
  amount | amount of data to redistribute by the task

Returns
  the new task

void SD_task_distribute_comp_amdahl | ( | SD_task_t | task,
|  | int | ws_count
| ) |  |

Blah.

void SD_task_schedulev | ( | SD_task_t | task,
|  | int | count,
|  | const SD_workstation_t * | list
| ) |  |

Auto-schedules a task.

Auto-scheduling mean that the task can be used with SD_task_schedulev(). This allows to specify the task costs at creation, and decouple them from the scheduling process where you just specify which resource should deliver the mandatory power.

To be auto-schedulable, a task must be created with SD_task_create_comm_e2e() or SD_task_create_comp_seq(). Check their definitions for the exact semantic of each of them.

void SD_task_schedulel | ( | SD_task_t | task,
|  | int | count,
|  |  | ...
| ) |  |

autoschedule a task on a list of workstations

This function is very similar to SD_task_schedulev(), but takes the list of workstations to schedule onto as separate parameters. It builds a proper vector of workstations and then call SD_task_schedulev()