explicit_dependencies.doxy 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164
  1. /* StarPU --- Runtime system for heterogeneous multicore architectures.
  2. *
  3. * Copyright (C) 2010-2013,2015,2017,2018 CNRS
  4. * Copyright (C) 2009-2011,2014-2016, 2018 Université de Bordeaux
  5. * Copyright (C) 2011-2012 Inria
  6. *
  7. * StarPU is free software; you can redistribute it and/or modify
  8. * it under the terms of the GNU Lesser General Public License as published by
  9. * the Free Software Foundation; either version 2.1 of the License, or (at
  10. * your option) any later version.
  11. *
  12. * StarPU is distributed in the hope that it will be useful, but
  13. * WITHOUT ANY WARRANTY; without even the implied warranty of
  14. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  15. *
  16. * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  17. */
  18. /*! \defgroup API_Explicit_Dependencies Explicit Dependencies
  19. \fn void starpu_task_declare_deps_array(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
  20. \ingroup API_Explicit_Dependencies
  21. Declare task dependencies between a \p task and an array of
  22. tasks of length \p ndeps. This function must be called prior to the
  23. submission of the task, but it may called after the submission or the
  24. execution of the tasks in the array, provided the tasks are still
  25. valid (i.e. they were not automatically destroyed). Calling this
  26. function on a task that was already submitted or with an entry of
  27. \p task_array that is no longer a valid task results in an undefined
  28. behaviour. If \p ndeps is 0, no dependency is added. It is possible to
  29. call starpu_task_declare_deps_array() several times on the same task,
  30. in this case, the dependencies are added. It is possible to have
  31. redundancy in the task dependencies.
  32. \fn void starpu_task_declare_deps(starpu_task *task, unsigned ndeps, ...)
  33. \ingroup API_Explicit_Dependencies
  34. Declare task dependencies between a \p task and an series of \p ndeps tasks,
  35. similarly to starpu_task_declare_deps_array(), but the tasks are passed after \p
  36. ndeps, which indicates how many tasks \p task shall be made to depend on.
  37. If \p ndeps is 0, no dependency is added.
  38. Specify the dependencies of the task identified by tag \p id.
  39. The first argument specifies the tag which is configured, the second
  40. argument gives the number of tag(s) on which \p id depends. The
  41. following arguments are the tags which have to be terminated to unlock
  42. the task. This function must be called before the associated task is
  43. submitted to StarPU with starpu_task_submit().
  44. \fn int starpu_task_get_task_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
  45. \ingroup API_Explicit_Dependencies
  46. Fill \p task_array with the list of tasks which are direct children of \p task.
  47. \p ndeps is the size of \p task_array. This function returns the number of
  48. direct children. \p task_array can be set to <c>NULL</c> if \p ndeps is 0, which allows
  49. to compute the number of children before allocating an array to store them.
  50. This function can only be called if \p task has not completed yet, otherwise
  51. the results are undefined. The result may also be outdated if some additional
  52. dependency has been added in the meanwhile.
  53. \fn int starpu_task_get_task_scheduled_succs(struct starpu_task *task, unsigned ndeps, struct starpu_task *task_array[])
  54. \ingroup API_Explicit_Dependencies
  55. Behave like starpu_task_get_task_succs(), except that it only reports
  56. tasks which will go through the scheduler, thus avoiding tasks with not codelet,
  57. or with explicit placement.
  58. \typedef starpu_tag_t
  59. \ingroup API_Explicit_Dependencies
  60. Define a task logical identifer. It is possible to
  61. associate a task with a unique <em>tag</em> chosen by the application,
  62. and to express dependencies between tasks by the means of those tags.
  63. To do so, fill the field starpu_task::tag_id with a tag number (can be
  64. arbitrary) and set the field starpu_task::use_tag to 1. If
  65. starpu_tag_declare_deps() is called with this tag number, the task
  66. will not be started until the tasks which holds the declared
  67. dependency tags are completed.
  68. \fn void starpu_tag_declare_deps(starpu_tag_t id, unsigned ndeps, ...)
  69. \ingroup API_Explicit_Dependencies
  70. Specify the dependencies of the task identified by tag \p id.
  71. The first argument specifies the tag which is configured, the second
  72. argument gives the number of tag(s) on which \p id depends. The
  73. following arguments are the tags which have to be terminated to unlock
  74. the task. This function must be called before the associated task is
  75. submitted to StarPU with starpu_task_submit().
  76. <b>WARNING! Use with caution</b>. Because of the variable arity of
  77. starpu_tag_declare_deps(), note that the last arguments must be of
  78. type ::starpu_tag_t : constant values typically need to be explicitly
  79. casted. Otherwise, due to integer sizes and argument passing on the
  80. stack, the C compiler might consider the tag <c>0x200000003</c>
  81. instead of <c>0x2</c> and <c>0x3</c> when calling
  82. <c>starpu_tag_declare_deps(0x1, 2, 0x2, 0x3)</c>. Using the
  83. starpu_tag_declare_deps_array() function avoids this hazard.
  84. \code{.c}
  85. /* Tag 0x1 depends on tags 0x32 and 0x52 */
  86. starpu_tag_declare_deps((starpu_tag_t)0x1, 2, (starpu_tag_t)0x32, (starpu_tag_t)0x52);
  87. \endcode
  88. \fn void starpu_tag_declare_deps_array(starpu_tag_t id, unsigned ndeps, starpu_tag_t *array)
  89. \ingroup API_Explicit_Dependencies
  90. Similar to starpu_tag_declare_deps(), except
  91. that its does not take a variable number of arguments but an \p array of
  92. tags of size \p ndeps.
  93. \code{.c}
  94. /* Tag 0x1 depends on tags 0x32 and 0x52 */
  95. starpu_tag_t tag_array[2] = {0x32, 0x52};
  96. starpu_tag_declare_deps_array((starpu_tag_t)0x1, 2, tag_array);
  97. \endcode
  98. \fn int starpu_tag_wait(starpu_tag_t id)
  99. \ingroup API_Explicit_Dependencies
  100. Block until the task associated to tag \p id has
  101. been executed. This is a blocking call which must therefore not be
  102. called within tasks or callbacks, but only from the application
  103. directly. It is possible to synchronize with the same tag multiple
  104. times, as long as the starpu_tag_remove() function is not called. Note
  105. that it is still possible to synchronize with a tag associated to a
  106. task for which the strucuture starpu_task was freed (e.g. if the field
  107. starpu_task::destroy was enabled).
  108. \fn int starpu_tag_wait_array(unsigned ntags, starpu_tag_t *id)
  109. \ingroup API_Explicit_Dependencies
  110. Similar to starpu_tag_wait() except that it
  111. blocks until all the \p ntags tags contained in the array \p id are
  112. terminated.
  113. \fn void starpu_tag_restart(starpu_tag_t id)
  114. \ingroup API_Explicit_Dependencies
  115. Clear the <em>already notified</em> status of a tag which is not associated with a task.
  116. Before that, calling starpu_tag_notify_from_apps() again will not
  117. notify the successors. After that, the next call to
  118. starpu_tag_notify_from_apps() will notify the successors.
  119. \fn void starpu_tag_remove(starpu_tag_t id)
  120. \ingroup API_Explicit_Dependencies
  121. Release the resources associated to tag \p id.
  122. It can be called once the corresponding task has been executed and
  123. when there is no other tag that depend on this tag anymore.
  124. \fn void starpu_tag_notify_from_apps(starpu_tag_t id)
  125. \ingroup API_Explicit_Dependencies
  126. Explicitly unlock tag \p id. It may be useful in
  127. the case of applications which execute part of their computation
  128. outside StarPU tasks (e.g. third-party libraries). It is also provided
  129. as a convenient tool for the programmer, for instance to entirely
  130. construct the task DAG before actually giving StarPU the opportunity
  131. to execute the tasks. When called several times on the same tag,
  132. notification will be done only on first call, thus implementing "OR"
  133. dependencies, until the tag is restarted using starpu_tag_restart().
  134. \fn void starpu_task_end_dep_add(struct starpu_task *t, int nb_deps)
  135. \ingroup API_Explicit_Dependencies
  136. Add \p nb_deps end dependencies to the task \p t. This means the task
  137. will not terminate until the required number of calls to the function
  138. starpu_task_end_dep_release() has been made.
  139. \fn void starpu_task_end_dep_release(struct starpu_task *t)
  140. \ingroup API_Explicit_Dependencies
  141. Unlock 1 end dependency to the task \p t. This function must be called
  142. after starpu_task_end_dep_add().
  143. */