StarPU Handbook

Typedefs | Functions
Explicit Dependencies

## Typedefs
typedef uint64_t | starpu_tag_t

## Functions
void | starpu_task_declare_deps_array (struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
void | starpu_task_declare_deps (struct starpu_task *task, unsigned ndeps,...)
void | starpu_task_declare_end_deps_array (struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
void | starpu_task_declare_end_deps (struct starpu_task *task, unsigned ndeps,...)
int | starpu_task_get_task_succs (struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
int | starpu_task_get_task_scheduled_succs (struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
void | starpu_task_end_dep_add (struct starpu_task *t, int nb_deps)
void | starpu_task_end_dep_release (struct starpu_task *t)
void | starpu_tag_declare_deps (starpu_tag_t id, unsigned ndeps,...)
void | starpu_tag_declare_deps_array (starpu_tag_t id, unsigned ndeps, starpu_tag_t *array)
int | starpu_tag_wait (starpu_tag_t id)
int | starpu_tag_wait_array (unsigned ntags, starpu_tag_t *id)
void | starpu_tag_restart (starpu_tag_t id)
void | starpu_tag_remove (starpu_tag_t id)
void | starpu_tag_notify_from_apps (starpu_tag_t id)
void | starpu_tag_notify_restart_from_apps (starpu_tag_t id)
struct starpu_task * | starpu_tag_get_task (starpu_tag_t id)

## Detailed Description

## Typedef Documentation

## ◆ starpu_tag_t

typedef uint64_t starpu_tag_t

Define a task logical identifer. It is possible to associate a task with a unique tag chosen by the application, and to express dependencies between tasks by the means of those tags. To do so, fill the field starpu_task::tag_id with a tag number (can be arbitrary) and set the field starpu_task::use_tag to 1. If starpu_tag_declare_deps() is called with this tag number, the task will not be started until the tasks which holds the declared dependency tags are completed.

## Function Documentation

## ◆ starpu_task_declare_deps_array()

void starpu_task_declare_deps_array | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  | struct starpu_task * | task_array[]
| ) |  |

Declare task dependencies between a `task` and an array of tasks of length `ndeps`. This function must be called prior to the submission of the task, but it may called after the submission or the execution of the tasks in the array, provided the tasks are still valid (i.e. they were not automatically destroyed). Calling this function on a task that was already submitted or with an entry of `task_array` that is no longer a valid task results in an undefined behaviour. If `ndeps` is 0, no dependency is added. It is possible to call starpu_task_declare_deps_array() several times on the same task, in this case, the dependencies are added. It is possible to have redundancy in the task dependencies.

## ◆ starpu_task_declare_deps()

void starpu_task_declare_deps | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  |  | ...
| ) |  |

Declare task dependencies between a `task` and an series of `ndeps` tasks, similarly to starpu_task_declare_deps_array(), but the tasks are passed after `ndeps`, which indicates how many tasks `task` shall be made to depend on. If `ndeps` is 0, no dependency is added.

## ◆ starpu_task_declare_end_deps_array()

void starpu_task_declare_end_deps_array | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  | struct starpu_task * | task_array[]
| ) |  |

Declare task end dependencies between a `task` and an array of tasks of length `ndeps`. `task` will appear as terminated not only when `task` is termination, but also when the tasks of `task_array` have terminated. This function must be called prior to the termination of the task, but it may called after the submission or the execution of the tasks in the array, provided the tasks are still valid (i.e. they were not automatically destroyed). Calling this function on a task that was already terminated or with an entry of `task_array` that is no longer a valid task results in an undefined behaviour. If `ndeps` is 0, no dependency is added. It is possible to call starpu_task_declare_end_deps_array() several times on the same task, in this case, the dependencies are added. It is currently not implemented to have redundancy in the task dependencies.

## ◆ starpu_task_declare_end_deps()

void starpu_task_declare_end_deps | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  |  | ...
| ) |  |

Declare task end dependencies between a `task` and an series of `ndeps` tasks, similarly to starpu_task_declare_end_deps_array(), but the tasks are passed after `ndeps`, which indicates how many tasks `task` 's termination shall be made to depend on. If `ndeps` is 0, no dependency is added.

## ◆ starpu_task_get_task_succs()

int starpu_task_get_task_succs | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  | struct starpu_task * | task_array[]
| ) |  |

Fill `task_array` with the list of tasks which are direct children of `task`. `ndeps` is the size of `task_array`. This function returns the number of direct children. `task_array` can be set to `NULL` if `ndeps` is 0, which allows to compute the number of children before allocating an array to store them. This function can only be called if `task` has not completed yet, otherwise the results are undefined. The result may also be outdated if some additional dependency has been added in the meanwhile.

## ◆ starpu_task_get_task_scheduled_succs()

int starpu_task_get_task_scheduled_succs | ( | struct starpu_task * | task,
|  | unsigned | ndeps,
|  | struct starpu_task * | task_array[]
| ) |  |

Behave like starpu_task_get_task_succs(), except that it only reports tasks which will go through the scheduler, thus avoiding tasks with not codelet, or with explicit placement.

## ◆ starpu_task_end_dep_add()

void starpu_task_end_dep_add | ( | struct starpu_task * | t,
|  | int | nb_deps
| ) |  |

Add `nb_deps` end dependencies to the task `t`. This means the task will not terminate until the required number of calls to the function starpu_task_end_dep_release() has been made.

## ◆ starpu_task_end_dep_release()

void starpu_task_end_dep_release | ( | struct starpu_task * | t | ) |

Unlock 1 end dependency to the task `t`. This function must be called after starpu_task_end_dep_add().

## ◆ starpu_tag_declare_deps()

void starpu_tag_declare_deps | ( | starpu_tag_t | id,
|  | unsigned | ndeps,
|  |  | ...
| ) |  |

Specify the dependencies of the task identified by tag `id`. The first argument specifies the tag which is configured, the second argument gives the number of tag(s) on which `id` depends. The following arguments are the tags which have to be terminated to unlock the task. This function must be called before the associated task is submitted to StarPU with starpu_task_submit().

WARNING! Use with caution. Because of the variable arity of starpu_tag_declare_deps(), note that the last arguments must be of type starpu_tag_t : constant values typically need to be explicitly casted. Otherwise, due to integer sizes and argument passing on the stack, the C compiler might consider the tag `0x200000003` instead of `0x2` and `0x3` when calling `starpu_tag_declare_deps(0x1, 2, 0x2, 0x3)`. Using the starpu_tag_declare_deps_array() function avoids this hazard.

// Tag 0x1 depends on tags 0x32 and 0x52
starpu_tag_declare_deps((starpu_tag_t)0x1, 2, (starpu_tag_t)0x32, (starpu_tag_t)0x52);
starpu_tag_declare_deps
void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps,...)
starpu_tag_t
uint64_t starpu_tag_t
Definition: starpu_task_dep.h:127

## ◆ starpu_tag_declare_deps_array()

void starpu_tag_declare_deps_array | ( | starpu_tag_t | id,
|  | unsigned | ndeps,
|  | starpu_tag_t * | array
| ) |  |

Similar to starpu_tag_declare_deps(), except that its does not take a variable number of arguments but an `array` of tags of size `ndeps`.

// Tag 0x1 depends on tags 0x32 and 0x52
starpu_tag_t tag_array[2] = {0x32, 0x52};
starpu_tag_declare_deps_array((starpu_tag_t)0x1, 2, tag_array);
starpu_tag_declare_deps_array
void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array)

## ◆ starpu_tag_wait()

int starpu_tag_wait | ( | starpu_tag_t | id | ) |

Block until the task associated to tag `id` has been executed. This is a blocking call which must therefore not be called within tasks or callbacks, but only from the application directly. It is possible to synchronize with the same tag multiple times, as long as the starpu_tag_remove() function is not called. Note that it is still possible to synchronize with a tag associated to a task for which the strucuture starpu_task was freed (e.g. if the field starpu_task::destroy was enabled).

## ◆ starpu_tag_wait_array()

int starpu_tag_wait_array | ( | unsigned | ntags,
|  | starpu_tag_t * | id
| ) |  |

Similar to starpu_tag_wait() except that it blocks until all the `ntags` tags contained in the array `id` are terminated.

## ◆ starpu_tag_restart()

void starpu_tag_restart | ( | starpu_tag_t | id | ) |

Clear the already notified status of a tag which is not associated with a task. Before that, calling starpu_tag_notify_from_apps() again will not notify the successors. After that, the next call to starpu_tag_notify_from_apps() will notify the successors.

## ◆ starpu_tag_remove()

void starpu_tag_remove | ( | starpu_tag_t | id | ) |

Release the resources associated to tag `id`. It can be called once the corresponding task has been executed and when there is no other tag that depend on this tag anymore.

## ◆ starpu_tag_notify_from_apps()

void starpu_tag_notify_from_apps | ( | starpu_tag_t | id | ) |

Explicitly unlock tag `id`. It may be useful in the case of applications which execute part of their computation outside StarPU tasks (e.g. third-party libraries). It is also provided as a convenient tool for the programmer, for instance to entirely construct the task DAG before actually giving StarPU the opportunity to execute the tasks. When called several times on the same tag, notification will be done only on first call, thus implementing "OR" dependencies, until the tag is restarted using starpu_tag_restart().

## ◆ starpu_tag_notify_restart_from_apps()

void starpu_tag_notify_restart_from_apps | ( | starpu_tag_t | id | ) |

Atomically call starpu_tag_notify_from_apps() and starpu_tag_restart() on tag `id`. This is useful with cyclic graphs, when we want to safely trigger its startup.