SimGrid  3.12
Versatile Simulation of Distributed Systems
Tasks

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. More...
 

Functions

SD_task_t SD_task_create (const char *name, void *data, double amount)
 Creates a new task. More...
 
void * SD_task_get_data (SD_task_t task)
 Returns the user data of a task. More...
 
void SD_task_set_data (SD_task_t task, void *data)
 Sets the user data of a task. More...
 
e_SD_task_state_t SD_task_get_state (SD_task_t task)
 Returns the state of a task. More...
 
const char * SD_task_get_name (SD_task_t task)
 Returns the name of a task. More...
 
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. More...
 
void SD_task_watch (SD_task_t task, e_SD_task_state_t state)
 Adds a watch point to a task. More...
 
void SD_task_unwatch (SD_task_t task, e_SD_task_state_t state)
 Removes a watch point from a task. More...
 
double SD_task_get_amount (SD_task_t task)
 Returns the total amount of work contained in a task. More...
 
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 flops_amount and bytes_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. More...
 
double SD_task_get_alpha (SD_task_t task)
 Returns the alpha parameter of a SD_TASK_COMP_PAR_AMDAHL task. More...
 
double SD_task_get_remaining_amount (SD_task_t task)
 Returns the remaining amount work to do till the completion of a task. More...
 
double SD_task_get_execution_time (SD_task_t task, int workstation_nb, const SD_workstation_t *workstation_list, const double *flops_amount, const double *bytes_amount)
 Returns an approximative estimation of the execution time of a task. More...
 
void SD_task_schedule (SD_task_t task, int workstation_nb, const SD_workstation_t *workstation_list, const double *flops_amount, const double *bytes_amount, double rate)
 Schedules a task. More...
 
void SD_task_unschedule (SD_task_t task)
 Unschedules a task. More...
 
double SD_task_get_start_time (SD_task_t task)
 Returns the start time of a task. More...
 
double SD_task_get_finish_time (SD_task_t task)
 Returns the finish time of a task. More...
 
xbt_dynar_t SD_task_get_parents (SD_task_t task)
 Returns the dynar of the parents of a task. More...
 
xbt_dynar_t SD_task_get_children (SD_task_t task)
 Returns the dynar of the parents of a task. More...
 
int SD_task_get_workstation_count (SD_task_t task)
 Returns the amount of workstations involved in a task. More...
 
SD_workstation_tSD_task_get_workstation_list (SD_task_t task)
 Returns the list of workstations involved in a task. More...
 
void SD_task_destroy (SD_task_t task)
 Destroys a task. More...
 
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 More...
 
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 More...
 
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 More...
 
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 More...
 
void SD_task_distribute_comp_amdahl (SD_task_t task, int ws_count)
 Blah. More...
 
void SD_task_schedulev (SD_task_t task, int count, const SD_workstation_t *list)
 Auto-schedules a task. More...
 
void SD_task_schedulel (SD_task_t task, int count,...)
 autoschedule a task on a list of workstations More...
 

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_flops_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
namethe name of the task (can be NULL)
datathe user data you want to associate with the task (can be NULL)
amountamount 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
taska 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
taska task
datathe 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
taska 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
taska 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 cannot be dynamically changed. Once the task has started, this call is ineffective. 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
taska
See also
SD_TASK_COMM_E2E task (end-to-end communication)
Parameters
ratethe 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
taska task
statethe 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
taska task
statethe 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
taska 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 flops_amount and bytes_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
taska task
amountthe 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
taska 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
taska 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 *  flops_amount,
const double *  bytes_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
taskthe task to evaluate
workstation_nbnumber of workstations on which the task would be executed
workstation_listthe workstations on which the task would be executed
flops_amountcomputation amount for each workstation
bytes_amountcommunication 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 *  flops_amount,
const double *  bytes_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
taskthe task you want to schedule
workstation_countnumber of workstations on which the task will be executed
workstation_listthe workstations on which the task will be executed
flops_amountcomputation amount for each workstation
bytes_amountcommunication amount between each pair of workstations
ratetask 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
taskthe 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
taska 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
taska 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
taska 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
taska 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
taska 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
taska task
void SD_task_destroy ( SD_task_t  task)

Destroys a task.

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

Parameters
taskthe task you want to destroy
See also
SD_task_create()
SD_task_t SD_task_create_comp_seq ( const char *  name,
void *  data,
double  flops_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
namethe name of the task (can be NULL)
datathe user data you want to associate with the task (can be NULL)
flops_amountamount 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  flops_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
namethe name of the task (can be NULL)
datathe user data you want to associate with the task (can be NULL)
flops_amountamount of compute work to be done by the task
alphapurely 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
namethe name of the task (can be NULL)
datathe user data you want to associate with the task (can be NULL)
amountamount 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()