SimGrid  3.19.1 Versatile Simulation of Distributed Systems

## Detailed Description

This section describes the functions for managing the tasks.

A task is some working amount that can be executed in parallel on several hosts. A task may depend on other tasks, which 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, ...

## Macros

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

## Typedefs

Task opaque datatypeA task is some computing amount that can be executed in parallel on several hosts. More...

## Enumerations

SD_NOT_SCHEDULED = 0x0001, SD_SCHEDULABLE = 0x0002, SD_SCHEDULED = 0x0004, SD_RUNNABLE = 0x0008,
SD_RUNNING = 0x0010, SD_DONE = 0x0020, SD_FAILED = 0x0040
}

}

## Functions

Returns the user data of a task. More...

Sets the user data of a task. More...

Returns the state of a task. More...

Returns the name of a task. More...

Allows to change the name of a task. More...

Sets the rate of a task. More...

Removes a watch point from a task. More...

Returns the total amount of work contained in a task. More...

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

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

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

void SD_task_schedule (SD_task_t task, int host_count, const sg_host_t *host_list, const double *flops_amount, const double *bytes_amount, double rate)

Returns the start time of a task. More...

Returns the finish time of a task. More...

Returns the dynar of the parents of a task. More...

Returns the dynar of the parents of a task. More...

Returns the number of workstations involved in a task. More...

Returns the list of workstations involved in a task. More...

Dumps the task in dotty formalism into the FILE* passed as second argument. More...

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

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

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

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

autoschedule a task on a list of hosts More...

## ◆ SD_SCHED_NO_COST

 #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 (i.e., with no communication) like this:

## Typedef Documentation

Task opaque datatypeA task is some computing amount that can be executed in parallel on several hosts.

A task may depend on other tasks, which 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, ...

## Enumeration Type Documentation

Enumerator
SD_NOT_SCHEDULED

Initial state (not valid for SD_watch and SD_unwatch).

SD_SCHEDULABLE

A task becomes SD_SCHEDULABLE as soon as its dependencies are satisfied.

SD_SCHEDULED

SD_simulate will execute it when it becomes SD_RUNNABLE.

SD_RUNNABLE

A scheduled task becomes runnable is SD_simulate as soon as its dependencies are satisfied.

SD_RUNNING

An SD_RUNNABLE task becomes SD_RUNNING when it is launched.

SD_DONE

SD_FAILED

A problem occurred during the execution of the task.

Enumerator

no specified type

end to end communication

sequential computation

parallel computation (Amdahl's law)

MxN data redistribution (1D Block distribution)

## Function Documentation

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

Parameters
 name the name of the task (can be nullptr) data the user data you want to associate with the task (can be nullptr) amount amount of the task
Returns

Returns the user data of a task.

Parameters
Returns
the user data associated with this task (can be nullptr)

Sets the user data of a task.

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

Parameters

Returns the state of a task.

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

Returns the name of a task.

Parameters
Returns
the name of this task (can be nullptr)

Allows to change the name of a task.

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 (

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
Parameters
 rate the new rate you want to associate with this 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)

Removes a watch point from a task.

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

Returns the total amount of work contained in a task.

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

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 parallel 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

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

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

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

 double SD_task_get_execution_time ( SD_task_t , int host_count, const sg_host_t * host_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
 task the task to evaluate host_count number of hosts on which the task would be executed host_list the hosts on which the task would be executed flops_amount computation amount for each host(i.e., an array of host_count doubles) bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles)
SD_schedule()

 void SD_task_schedule ( SD_task_t task, int host_count, const sg_host_t * host_list, const double * flops_amount, const double * bytes_amount, double rate )

The task state must be SD_NOT_SCHEDULED. Once scheduled, a task is executed as soon as possible in

SD_simulate, i.e. when its dependencies are satisfied.
Parameters
 task the task you want to schedule host_count number of hosts on which the task will be executed host_list the hosts on which the task will be executed flops_amount computation amount for each hosts (i.e., an array of host_count doubles) bytes_amount communication amount between each pair of hosts (i.e., a matrix of host_count*host_count doubles) rate task execution speed rate

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

Returns the start time of a task.

The task state must be SD_RUNNING, SD_DONE or SD_FAILED.

Parameters
Returns
the start time of this 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 vary until the task is completed.

Parameters
Returns
the start time of this task

Returns the dynar of the parents of a task.

Parameters
Returns
a newly allocated dynar comprising the parents of this task

Returns the dynar of the parents of a task.

Parameters
Returns
a newly allocated dynar comprising the parents of this task

Returns the number of workstations involved in a task.

Parameters

Returns the list of workstations involved in a task.

Parameters

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

Parameters

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 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
 name the name of the task (can be nullptr) data the user data you want to associate with the task (can be nullptr) flops_amount amount of compute work to be done by the task
Returns

 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,

SD_task_distribute_comp_amdahl has to be called first.
Parameters
 name the name of the task (can be nullptr) data the user data you want to associate with the task (can be nullptr) flops_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

 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

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 nullptr) data the user data you want to associate with the task (can be nullptr) amount amount of data to redistribute by the task
Returns