openmp_runtime_support.doxy 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980
  1. /* StarPU --- Runtime system for heterogeneous multicore architectures.
  2. *
  3. * Copyright (C) 2014 Inria
  4. *
  5. * StarPU is free software; you can redistribute it and/or modify
  6. * it under the terms of the GNU Lesser General Public License as published by
  7. * the Free Software Foundation; either version 2.1 of the License, or (at
  8. * your option) any later version.
  9. *
  10. * StarPU is distributed in the hope that it will be useful, but
  11. * WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13. *
  14. * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  15. */
  16. /*! \defgroup API_OpenMP_Runtime_Support OpenMP Runtime Support
  17. \brief This section describes the interface provided for implementing OpenMP runtimes on top of StarPU.
  18. \struct starpu_omp_lock_t
  19. \ingroup API_OpenMP_Runtime_Support
  20. Opaque Simple Lock object (\ref SimpleLock) for inter-task synchronization operations.
  21. \sa starpu_omp_init_lock()
  22. \sa starpu_omp_destroy_lock()
  23. \sa starpu_omp_set_lock()
  24. \sa starpu_omp_unset_lock()
  25. \sa starpu_omp_test_lock()
  26. \var starpu_omp_lock_t::internal
  27. Is an opaque pointer for internal use.
  28. \struct starpu_omp_nest_lock_t
  29. \ingroup API_OpenMP_Runtime_Support
  30. Opaque Nestable Lock object (\ref NestableLock) for inter-task synchronization operations.
  31. \sa starpu_omp_init_nest_lock()
  32. \sa starpu_omp_destroy_nest_lock()
  33. \sa starpu_omp_set_nest_lock()
  34. \sa starpu_omp_unset_nest_lock()
  35. \sa starpu_omp_test_nest_lock()
  36. \var starpu_omp_nest_lock_t::internal
  37. Is an opaque pointer for internal use.
  38. \enum starpu_omp_sched_value
  39. \ingroup API_OpenMP_Runtime_Support
  40. Set of constants for selecting the for loop iteration scheduling algorithm
  41. (\ref OMPFor) as defined by the OpenMP specification.
  42. \var starpu_omp_sched_value::starpu_omp_sched_undefined
  43. \ingroup API_OpenMP_Runtime_Support
  44. Undefined iteration scheduling algorithm.
  45. \var starpu_omp_sched_value::starpu_omp_sched_static
  46. \ingroup API_OpenMP_Runtime_Support
  47. \b Static iteration scheduling algorithm.
  48. \var starpu_omp_sched_value::starpu_omp_sched_dynamic
  49. \ingroup API_OpenMP_Runtime_Support
  50. \b Dynamic iteration scheduling algorithm.
  51. \var starpu_omp_sched_value::starpu_omp_sched_guided
  52. \ingroup API_OpenMP_Runtime_Support
  53. \b Guided iteration scheduling algorithm.
  54. \var starpu_omp_sched_value::starpu_omp_sched_auto
  55. \ingroup API_OpenMP_Runtime_Support
  56. \b Automatically choosen iteration scheduling algorithm.
  57. \var starpu_omp_sched_value::starpu_omp_sched_runtime
  58. \ingroup API_OpenMP_Runtime_Support
  59. Choice of iteration scheduling algorithm deferred at \b runtime.
  60. \sa starpu_omp_for()
  61. \sa starpu_omp_for_inline_first()
  62. \sa starpu_omp_for_inline_next()
  63. \sa starpu_omp_for_alt()
  64. \sa starpu_omp_for_inline_first_alt()
  65. \sa starpu_omp_for_inline_next_alt()
  66. \enum starpu_omp_proc_bind_value
  67. \ingroup API_OpenMP_Runtime_Support
  68. Set of constants for selecting the processor binding method, as defined in the
  69. OpenMP specification.
  70. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_undefined
  71. \ingroup API_OpenMP_Runtime_Support
  72. Undefined processor binding method.
  73. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_false
  74. \ingroup API_OpenMP_Runtime_Support
  75. Team threads may be moved between places at any time.
  76. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_true
  77. \ingroup API_OpenMP_Runtime_Support
  78. Team threads may not be moved between places.
  79. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_master
  80. \ingroup API_OpenMP_Runtime_Support
  81. Assign every thread in the team to the same place as the \b master thread.
  82. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_close
  83. \ingroup API_OpenMP_Runtime_Support
  84. Assign every thread in the team to a place \b close to the parent thread.
  85. \var starpu_omp_proc_bind_value::starpu_omp_proc_bind_spread
  86. \ingroup API_OpenMP_Runtime_Support
  87. Assign team threads as a sparse distribution over the selected places.
  88. \sa starpu_omp_get_proc_bind()
  89. \struct starpu_omp_parallel_region_attr
  90. \ingroup API_OpenMP_Runtime_Support
  91. Set of attributes used for creating a new parallel region.
  92. \sa starpu_omp_parallel_region()
  93. \var struct starpu_codelet starpu_omp_parallel_region_attr::cl
  94. Is a ::starpu_codelet (\ref API_Codelet_And_Tasks) to use for the parallel region
  95. implicit tasks. The codelet must provide a CPU implementation function.
  96. \var starpu_data_handle_t *starpu_omp_parallel_region_attr::handles
  97. Is an array of zero or more ::starpu_data_handle_t data handle to be passed to
  98. the parallel region implicit tasks.
  99. \var void *starpu_omp_parallel_region_attr::cl_arg
  100. Is an optional pointer to an inline argument to be passed to the region implicit tasks.
  101. \var size_t starpu_omp_parallel_region_attr::cl_arg_size
  102. Is the size of the optional inline argument to be passed to the region implicit tasks, or 0 if unused.
  103. \var unsigned starpu_omp_parallel_region_attr::cl_arg_free
  104. Is a boolean indicating whether the optional inline argument should be automatically freed (true), or not (false).
  105. \var int starpu_omp_parallel_region_attr::if_clause
  106. Is a boolean indicating whether the \b if clause of the corresponding <c>pragma
  107. omp parallel</c> is true or false.
  108. \var int starpu_omp_parallel_region_attr::num_threads
  109. Is an integer indicating the requested number of threads in the team of the
  110. newly created parallel region, or 0 to let the runtime choose the number of
  111. threads alone. This attribute may be ignored by the runtime system if the
  112. requested number of threads is higher than the number of threads that the
  113. runtime can create.
  114. \struct starpu_omp_task_region_attr
  115. \ingroup API_OpenMP_Runtime_Support
  116. Set of attributes used for creating a new task region.
  117. \sa starpu_omp_task_region()
  118. \var struct starpu_codelet starpu_omp_task_region_attr::cl
  119. Is a ::starpu_codelet (\ref API_Codelet_And_Tasks) to use for the task region
  120. explicit task. The codelet must provide a CPU implementation function or an
  121. accelerator implementation for offloaded target regions.
  122. \var starpu_data_handle_t *starpu_omp_task_region_attr::handles
  123. Is an array of zero or more ::starpu_data_handle_t data handle to be passed to
  124. the task region explicit tasks.
  125. \var void *starpu_omp_task_region_attr::cl_arg
  126. Is an optional pointer to an inline argument to be passed to the region implicit tasks.
  127. \var size_t starpu_omp_task_region_attr::cl_arg_size
  128. Is the size of the optional inline argument to be passed to the region implicit
  129. tasks, or 0 if unused.
  130. \var unsigned starpu_omp_task_region_attr::cl_arg_free
  131. Is a boolean indicating whether the optional inline argument should be
  132. automatically freed (true), or not (false).
  133. \var int starpu_omp_task_region_attr::if_clause
  134. Is a boolean indicating whether the \b if clause of the corresponding <c>pragma
  135. omp task</c> is true or false.
  136. \var int starpu_omp_task_region_attr::final_clause
  137. Is a boolean indicating whether the \b final clause of the corresponding <c>pragma
  138. omp task</c> is true or false.
  139. \var int starpu_omp_task_region_attr::untied_clause
  140. Is a boolean indicating whether the \b untied clause of the corresponding <c>pragma
  141. omp task</c> is true or false.
  142. \var int starpu_omp_task_region_attr::mergeable_clause
  143. Is a boolean indicating whether the \b mergeable clause of the corresponding <c>pragma
  144. omp task</c> is true or false.
  145. @name Initialisation
  146. \ingroup API_OpenMP_Runtime_Support
  147. \def STARPU_OPENMP
  148. \ingroup API_OpenMP_Runtime_Support
  149. This macro is defined when StarPU has been installed with OpenMP Runtime
  150. support. It should be used in your code to detect the availability of
  151. the runtime support for OpenMP.
  152. \fn int starpu_omp_init(void)
  153. \ingroup API_OpenMP_Runtime_Support
  154. Initializes StarPU and its OpenMP Runtime support.
  155. \fn void starpu_omp_shutdown(void)
  156. \ingroup API_OpenMP_Runtime_Support
  157. Shutdown StarPU and its OpenMP Runtime support.
  158. @name Parallel
  159. \anchor ORS_Parallel
  160. \ingroup API_OpenMP_Runtime_Support
  161. \fn void starpu_omp_parallel_region(const struct starpu_omp_parallel_region_attr *attr)
  162. \ingroup API_OpenMP_Runtime_Support
  163. Generates and launch an OpenMP parallel region and return after its
  164. completion. \p attr specifies the attributes for the generated parallel region.
  165. If this function is called from inside another, generating, parallel region, the
  166. generated parallel region is nested within the generating parallel region.
  167. This function can be used to implement <c>\#pragma omp parallel</c>.
  168. \fn void starpu_omp_master(void (*f)(void *arg), void *arg)
  169. \ingroup API_OpenMP_Runtime_Support
  170. Executes a function only on the master thread of the OpenMP
  171. parallel region it is called from. When called from a thread that is not the
  172. master of the parallel region it is called from, this function does nothing. \p
  173. f is the function to be called. \p arg is an argument passed to function \p f.
  174. This function can be used to implement <c>\#pragma omp master</c>.
  175. \fn int starpu_omp_master_inline(void)
  176. \ingroup API_OpenMP_Runtime_Support
  177. Determines whether the calling thread is the master of the OpenMP parallel region
  178. it is called from or not.
  179. This function can be used to implement <c>\#pragma omp master</c> without code
  180. outlining.
  181. \return <c>!0</c> if called by the region's master thread.
  182. \return <c>0</c> if not called by the region's master thread.
  183. @name Synchronization
  184. \anchor ORS_Synchronization
  185. \ingroup API_OpenMP_Runtime_Support
  186. \fn void starpu_omp_barrier(void)
  187. \ingroup API_OpenMP_Runtime_Support
  188. Waits until each participating thread of the innermost OpenMP parallel region
  189. has reached the barrier and each explicit OpenMP task bound to this region has
  190. completed its execution.
  191. This function can be used to implement <c>\#pragma omp barrier</c>.
  192. \fn void starpu_omp_critical(void (*f)(void *arg), void *arg, const char *name)
  193. \ingroup API_OpenMP_Runtime_Support
  194. Waits until no other thread is executing within the context of the selected
  195. critical section, then proceeds to the exclusive execution of a function within
  196. the critical section. \p f is the function to be executed in the critical
  197. section. \p arg is an argument passed to function \p f. \p name is the name of
  198. the selected critical section. If <c>name == NULL</c>, the selected critical
  199. section is the unique anonymous critical section.
  200. This function can be used to implement <c>\#pragma omp critical</c>.
  201. \fn void starpu_omp_critical_inline_begin(const char *name)
  202. \ingroup API_OpenMP_Runtime_Support
  203. Waits until execution can proceed exclusively within the context of the
  204. selected critical section. \p name is the name of the selected critical
  205. section. If <c>name == NULL</c>, the selected critical section is the unique
  206. anonymous critical section.
  207. This function together with #starpu_omp_critical_inline_end can be used to
  208. implement <c>\#pragma omp critical</c> without code outlining.
  209. \fn void starpu_omp_critical_inline_end(const char *name)
  210. \ingroup API_OpenMP_Runtime_Support
  211. Ends the exclusive execution within the context of the selected critical
  212. section. \p name is the name of the selected critical section. If
  213. <c>name==NULL</c>, the selected critical section is the unique anonymous
  214. critical section.
  215. This function together with #starpu_omp_critical_inline_begin can be used to
  216. implement <c>\#pragma omp critical</c> without code outlining.
  217. @name Worksharing
  218. \anchor ORS_Worksharing
  219. \ingroup API_OpenMP_Runtime_Support
  220. \fn void starpu_omp_single(void (*f)(void *arg), void *arg, int nowait)
  221. \ingroup API_OpenMP_Runtime_Support
  222. Ensures that a single participating thread of the innermost OpenMP parallel
  223. region executes a function. \p f is the function to be executed by a single
  224. thread. \p arg is an argument passed to function \p f. \p nowait is a flag
  225. indicating whether an implicit barrier is requested after the single section
  226. (<c>nowait==0</c>) or not (<c>nowait==!0</c>).
  227. This function can be used to implement <c>\#pragma omp single</c>.
  228. \fn int starpu_omp_single_inline(void)
  229. \ingroup API_OpenMP_Runtime_Support
  230. Decides whether the current thread is elected to run the following single
  231. section among the participating threads of the innermost OpenMP parallel
  232. region.
  233. This function can be used to implement <c>\#pragma omp single</c> without code
  234. outlining.
  235. \return <c>!0</c> if the calling thread has won the election.
  236. \return <c>0</c> if the calling thread has lost the election.
  237. \fn void starpu_omp_single_copyprivate(void (*f)(void *arg, void *data, unsigned long long data_size), void *arg, void *data, unsigned long long data_size)
  238. \ingroup API_OpenMP_Runtime_Support
  239. This function executes \p f on a single task of the current parallel region
  240. task, and then broadcast the contents of the memory block pointed by the
  241. copyprivate pointer \p data and of size \p data_size to the corresponding \p
  242. data pointed memory blocks of all the other participating region tasks. This
  243. function can be used to implement <c>\#pragma omp single</c> with a copyprivate
  244. clause.
  245. \sa starpu_omp_single_copyprivate_inline
  246. \sa starpu_omp_single_copyprivate_inline_begin
  247. \sa starpu_omp_single_copyprivate_inline_end
  248. \fn void *starpu_omp_single_copyprivate_inline_begin(void *data)
  249. \ingroup API_OpenMP_Runtime_Support
  250. This function elects one task among the tasks of the current parallel region
  251. task to execute the following single section, and then broadcast the
  252. copyprivate pointer \p data to all the other participating region tasks. This
  253. function can be used to implement <c>\#pragma omp single</c> with a copyprivate
  254. clause without code outlining.
  255. \sa starpu_omp_single_copyprivate_inline
  256. \sa starpu_omp_single_copyprivate_inline_end
  257. \fn void starpu_omp_single_copyprivate_inline_end(void)
  258. \ingroup API_OpenMP_Runtime_Support
  259. This function completes the execution of a single section and returns the
  260. broadcasted copyprivate pointer for tasks that lost the election and <c>NULL</c> for
  261. the task that won the election. This function can be used to implement
  262. <c>\#pragma omp single</c> with a copyprivate clause without code outlining.
  263. \return the copyprivate pointer for tasks that lost the election and therefore did not execute the code of the single section.
  264. \return <c>NULL</c> for the task that won the election and executed the code of the single section.
  265. \sa starpu_omp_single_copyprivate_inline
  266. \sa starpu_omp_single_copyprivate_inline_begin
  267. \fn void starpu_omp_for(void (*f)(unsigned long long _first_i, unsigned long long _nb_i, void *arg), void *arg, unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, int nowait)
  268. \ingroup API_OpenMP_Runtime_Support
  269. Executes a parallel loop together with the other threads participating to the
  270. innermost parallel region. \p f is the function to be executed iteratively. \p
  271. arg is an argument passed to function \p f. \p nb_iterations is the number of
  272. iterations to be performed by the parallel loop. \p chunk is the number of
  273. consecutive iterations that should be affected to the same thread when
  274. scheduling the loop workshares, it follows the semantics of the \c modifier
  275. argument in OpenMP <c>\#pragma omp for</c> specification. \p schedule is the
  276. scheduling mode according to the OpenMP specification. \p ordered is a flag
  277. indicating whether the loop region may contain an ordered section
  278. (<c>ordered==!0</c>) or not (<c>ordered==0</c>). \p nowait is a flag
  279. indicating whether an implicit barrier is requested after the for section
  280. (<c>nowait==0</c>) or not (<c>nowait==!0</c>).
  281. The function \p f will be called with arguments \p _first_i, the first iteration
  282. to perform, \p _nb_i, the number of consecutive iterations to perform before
  283. returning, \p arg, the free \p arg argument.
  284. This function can be used to implement <c>\#pragma omp for</c>.
  285. \fn int starpu_omp_for_inline_first(unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, unsigned long long *_first_i, unsigned long long *_nb_i)
  286. \ingroup API_OpenMP_Runtime_Support
  287. Decides whether the current thread should start to execute a parallel loop
  288. section. See #starpu_omp_for for the argument description.
  289. This function together with #starpu_omp_for_inline_next can be used to
  290. implement <c>\#pragma omp for</c> without code outlining.
  291. \return <c>!0</c> if the calling thread participates to the loop region and
  292. should execute a first chunk of iterations. In that case, \p *_first_i will be
  293. set to the first iteration of the chunk to perform and \p *_nb_i will be set to
  294. the number of iterations of the chunk to perform.
  295. \return <c>0</c> if the calling thread does not participate to the loop region
  296. because all the available iterations have been affected to the other threads of
  297. the parallel region.
  298. \sa starpu_omp_for
  299. \fn int starpu_omp_for_inline_next(unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, unsigned long long *_first_i, unsigned long long *_nb_i)
  300. \ingroup API_OpenMP_Runtime_Support
  301. Decides whether the current thread should continue to execute a parallel loop
  302. section. See #starpu_omp_for for the argument description.
  303. This function together with #starpu_omp_for_inline_first can be used to
  304. implement <c>\#pragma omp for</c> without code outlining.
  305. \return <c>!0</c> if the calling thread should execute a next chunk of
  306. iterations. In that case, \p *_first_i will be set to the first iteration of the
  307. chunk to perform and \p *_nb_i will be set to the number of iterations of the
  308. chunk to perform.
  309. \return <c>0</c> if the calling thread does not participate anymore to the loop
  310. region because all the available iterations have been affected to the other
  311. threads of the parallel region.
  312. \sa starpu_omp_for
  313. \fn void starpu_omp_for_alt(void (*f)(unsigned long long _begin_i, unsigned long long _end_i, void *arg), void *arg, unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, int nowait)
  314. \ingroup API_OpenMP_Runtime_Support
  315. Alternative implementation of a parallel loop. This function differs from
  316. #starpu_omp_for in the expected arguments of the loop function \c f.
  317. The function \p f will be called with arguments \p _begin_i, the first iteration
  318. to perform, \p _end_i, the first iteration not to perform before
  319. returning, \p arg, the free \p arg argument.
  320. This function can be used to implement <c>\#pragma omp for</c>.
  321. \sa starpu_omp_for
  322. \fn int starpu_omp_for_inline_first_alt(unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, unsigned long long *_begin_i, unsigned long long *_end_i)
  323. \ingroup API_OpenMP_Runtime_Support
  324. Inline version of the alternative implementation of a parallel loop.
  325. This function together with #starpu_omp_for_inline_next_alt can be used to
  326. implement <c>\#pragma omp for</c> without code outlining.
  327. \sa starpu_omp_for
  328. \sa starpu_omp_for_alt
  329. \sa starpu_omp_for_inline_first
  330. \fn int starpu_omp_for_inline_next_alt(unsigned long long nb_iterations, unsigned long long chunk, int schedule, int ordered, unsigned long long *_begin_i, unsigned long long *_end_i)
  331. \ingroup API_OpenMP_Runtime_Support
  332. Inline version of the alternative implementation of a parallel loop.
  333. This function together with #starpu_omp_for_inline_first_alt can be used to
  334. implement <c>\#pragma omp for</c> without code outlining.
  335. \sa starpu_omp_for
  336. \sa starpu_omp_for_alt
  337. \sa starpu_omp_for_inline_next
  338. \fn void starpu_omp_ordered(void (*f)(void *arg), void *arg)
  339. \ingroup API_OpenMP_Runtime_Support
  340. Ensures that a function is sequentially executed once for each iteration in
  341. order within a parallel loop, by the thread that own the iteration. \p f is the
  342. function to be executed by the thread that own the current iteration. \p arg is
  343. an argument passed to function \p f.
  344. This function can be used to implement <c>\#pragma omp ordered</c>.
  345. \fn void starpu_omp_ordered_inline_begin(void)
  346. \ingroup API_OpenMP_Runtime_Support
  347. Waits until all the iterations of a parallel loop below the iteration owned by
  348. the current thread have been executed.
  349. This function together with #starpu_omp_ordered_inline_end can be used to
  350. implement <c>\#pragma omp ordered</c> without code code outlining.
  351. \fn void starpu_omp_ordered_inline_end(void)
  352. \ingroup API_OpenMP_Runtime_Support
  353. Notifies that the ordered section for the current iteration has been completed.
  354. This function together with #starpu_omp_ordered_inline_begin can be used to
  355. implement <c>\#pragma omp ordered</c> without code code outlining.
  356. \fn void starpu_omp_sections(unsigned long long nb_sections, void (**section_f)(void *arg), void **section_arg, int nowait)
  357. \ingroup API_OpenMP_Runtime_Support
  358. Ensures that each function of a given array of functions is executed by one and
  359. only one thread. \p nb_sections is the number of functions in the array \p
  360. section_f. \p section_f is the array of functions to be executed as sections. \p
  361. section_arg is an array of arguments to be passed to the corresponding function.
  362. \p nowait is a flag indicating whether an implicit barrier is requested after
  363. the execution of all the sections (<c>nowait==0</c>) or not (<c>nowait==!0</c>).
  364. This function can be used to implement <c>\#pragma omp sections</c> and <c>\#pragma omp section</c>.
  365. \fn void starpu_omp_sections_combined(unsigned long long nb_sections, void (*section_f)(unsigned long long section_num, void *arg), void *section_arg, int nowait)
  366. \ingroup API_OpenMP_Runtime_Support
  367. Alternative implementation of sections. This function differs from
  368. #starpu_omp_sections in that all the sections are combined within a single
  369. function in this version. \p section_f is the function implementing the combined
  370. sections.
  371. The function \p section_f will be called with arguments \p section_num, the
  372. section number to be executed, \p arg, the entry of \p section_arg corresponding
  373. to this section.
  374. This function can be used to implement <c>\#pragma omp sections</c> and <c>\#pragma omp section</c>.
  375. \sa starpu_omp_sections
  376. @name Task
  377. \anchor ORS_Task
  378. \ingroup API_OpenMP_Runtime_Support
  379. \fn void starpu_omp_task_region(const struct starpu_omp_task_region_attr *attr)
  380. \ingroup API_OpenMP_Runtime_Support
  381. Generates an explicit child task. The execution of the generated task is
  382. asynchronous with respect to the calling code unless specified otherwise.
  383. \p attr specifies the attributes for the generated task region.
  384. This function can be used to implement <c>\#pragma omp task</c>.
  385. \fn void starpu_omp_taskwait(void)
  386. \ingroup API_OpenMP_Runtime_Support
  387. Waits for the completion of the tasks generated by the current task. This
  388. function does not wait for the descendants of the tasks generated by the current
  389. task.
  390. This function can be used to implement <c>\#pragma omp taskwait</c>.
  391. \fn void starpu_omp_taskgroup(void (*f)(void *arg), void *arg)
  392. \ingroup API_OpenMP_Runtime_Support
  393. Launches a function and wait for the completion of every descendant task
  394. generated during the execution of the function.
  395. This function can be used to implement <c>\#pragma omp taskgroup</c>.
  396. \sa starpu_omp_taskgroup_inline_begin
  397. \sa starpu_omp_taskgroup_inline_end
  398. \fn void starpu_omp_taskgroup_inline_begin(void)
  399. \ingroup API_OpenMP_Runtime_Support
  400. Launches a function and gets ready to wait for the completion of every descendant task
  401. generated during the dynamic scope of the taskgroup.
  402. This function can be used to implement <c>\#pragma omp taskgroup</c> without code outlining.
  403. \sa starpu_omp_taskgroup
  404. \sa starpu_omp_taskgroup_inline_end
  405. \fn void starpu_omp_taskgroup_inline_end(void)
  406. \ingroup API_OpenMP_Runtime_Support
  407. Waits for the completion of every descendant task
  408. generated during the dynamic scope of the taskgroup.
  409. This function can be used to implement <c>\#pragma omp taskgroup</c> without code outlining.
  410. \sa starpu_omp_taskgroup
  411. \sa starpu_omp_taskgroup_inline_begin
  412. @name API
  413. \anchor ORS_API
  414. \ingroup API_OpenMP_Runtime_Support
  415. \fn void starpu_omp_set_num_threads(int threads)
  416. \ingroup API_OpenMP_Runtime_Support
  417. This function sets ICVS nthreads_var for the parallel regions to be created
  418. with the current region.
  419. Note: The StarPU OpenMP runtime support currently ignores
  420. this setting for nested parallel regions.
  421. \sa starpu_omp_get_num_threads
  422. \sa starpu_omp_get_thread_num
  423. \sa starpu_omp_get_max_threads
  424. \sa starpu_omp_get_num_procs
  425. \fn int starpu_omp_get_num_threads()
  426. \ingroup API_OpenMP_Runtime_Support
  427. This function returns the number of threads of the current region.
  428. \return the number of threads of the current region.
  429. \sa starpu_omp_set_num_threads
  430. \sa starpu_omp_get_thread_num
  431. \sa starpu_omp_get_max_threads
  432. \sa starpu_omp_get_num_procs
  433. \fn int starpu_omp_get_thread_num()
  434. \ingroup API_OpenMP_Runtime_Support
  435. This function returns the rank of the current thread among the threads
  436. of the current region.
  437. \return the rank of the current thread in the current region.
  438. \sa starpu_omp_set_num_threads
  439. \sa starpu_omp_get_num_threads
  440. \sa starpu_omp_get_max_threads
  441. \sa starpu_omp_get_num_procs
  442. \fn int starpu_omp_get_max_threads()
  443. \ingroup API_OpenMP_Runtime_Support
  444. This function returns the maximum number of threads that can be used to
  445. create a region from the current region.
  446. \return the maximum number of threads that can be used to create a region from the current region.
  447. \sa starpu_omp_set_num_threads
  448. \sa starpu_omp_get_num_threads
  449. \sa starpu_omp_get_thread_num
  450. \sa starpu_omp_get_num_procs
  451. \fn int starpu_omp_get_num_procs(void)
  452. \ingroup API_OpenMP_Runtime_Support
  453. This function returns the number of StarPU CPU workers.
  454. \return the number of StarPU CPU workers.
  455. \sa starpu_omp_set_num_threads
  456. \sa starpu_omp_get_num_threads
  457. \sa starpu_omp_get_thread_num
  458. \sa starpu_omp_get_max_threads
  459. \fn int starpu_omp_in_parallel(void)
  460. \ingroup API_OpenMP_Runtime_Support
  461. This function returns whether it is called from the scope of a parallel region or not.
  462. \return <c>!0</c> if called from a parallel region scope.
  463. \return <c>0</c> otherwise.
  464. \fn void starpu_omp_set_dynamic(int dynamic_threads)
  465. \ingroup API_OpenMP_Runtime_Support
  466. This function enables (1) or disables (0) dynamically adjusting the number of parallel threads.
  467. Note: The StarPU OpenMP runtime support currently ignores the argument of this function.
  468. \sa starpu_omp_get_dynamic
  469. \fn int starpu_omp_get_dynamic(void)
  470. \ingroup API_OpenMP_Runtime_Support
  471. This function returns the state of dynamic thread number adjustment.
  472. \return <c>!0</c> if dynamic thread number adjustment is enabled.
  473. \return <c>0</c> otherwise.
  474. \sa starpu_omp_set_dynamic
  475. \fn void starpu_omp_set_nested(int nested)
  476. \ingroup API_OpenMP_Runtime_Support
  477. This function enables (1) or disables (0) nested parallel regions.
  478. Note: The StarPU OpenMP runtime support currently ignores the argument of this function.
  479. \sa starpu_omp_get_nested
  480. \sa starpu_omp_get_max_active_levels
  481. \sa starpu_omp_set_max_active_levels
  482. \sa starpu_omp_get_level
  483. \sa starpu_omp_get_active_level
  484. \fn int starpu_omp_get_nested(void)
  485. \ingroup API_OpenMP_Runtime_Support
  486. This function returns whether nested parallel sections are enabled or not.
  487. \return <c>!0</c> if nested parallel sections are enabled.
  488. \return <c>0</c> otherwise.
  489. \sa starpu_omp_set_nested
  490. \sa starpu_omp_get_max_active_levels
  491. \sa starpu_omp_set_max_active_levels
  492. \sa starpu_omp_get_level
  493. \sa starpu_omp_get_active_level
  494. \fn int starpu_omp_get_cancellation(void)
  495. \ingroup API_OpenMP_Runtime_Support
  496. This function returns the state of the cancel ICVS var.
  497. \fn void starpu_omp_set_schedule(enum starpu_omp_sched_value kind, int modifier)
  498. \ingroup API_OpenMP_Runtime_Support
  499. This function sets the default scheduling kind for upcoming loops within the
  500. current parallel section. \p kind is the scheduler kind, \p modifier
  501. complements the scheduler kind with informations such as the chunk size,
  502. in accordance with the OpenMP specification.
  503. \sa starpu_omp_get_schedule
  504. \fn void starpu_omp_get_schedule(enum starpu_omp_sched_value *kind, int *modifier)
  505. \ingroup API_OpenMP_Runtime_Support
  506. This function returns the current selected default loop scheduler.
  507. \return the kind and the modifier of the current default loop scheduler.
  508. \sa starpu_omp_set_schedule
  509. \fn int starpu_omp_get_thread_limit(void)
  510. \ingroup API_OpenMP_Runtime_Support
  511. This function returns the number of StarPU CPU workers.
  512. \return the number of StarPU CPU workers.
  513. \fn void starpu_omp_set_max_active_levels(int max_levels)
  514. \ingroup API_OpenMP_Runtime_Support
  515. This function sets the maximum number of allowed active parallel section levels.
  516. Note: The StarPU OpenMP runtime support currently ignores the argument of this function and assume \p max_levels equals <c>1</c> instead.
  517. \sa starpu_omp_set_nested
  518. \sa starpu_omp_get_nested
  519. \sa starpu_omp_get_max_active_levels
  520. \sa starpu_omp_get_level
  521. \sa starpu_omp_get_active_level
  522. \fn int starpu_omp_get_max_active_levels(void)
  523. \ingroup API_OpenMP_Runtime_Support
  524. This function returns the current maximum number of allowed active parallel section levels
  525. \return the current maximum number of allowed active parallel section levels.
  526. \sa starpu_omp_set_nested
  527. \sa starpu_omp_get_nested
  528. \sa starpu_omp_set_max_active_levels
  529. \sa starpu_omp_get_level
  530. \sa starpu_omp_get_active_level
  531. \fn int starpu_omp_get_level(void)
  532. \ingroup API_OpenMP_Runtime_Support
  533. This function returns the nesting level of the current parallel section.
  534. \return the nesting level of the current parallel section.
  535. \sa starpu_omp_set_nested
  536. \sa starpu_omp_get_nested
  537. \sa starpu_omp_get_max_active_levels
  538. \sa starpu_omp_set_max_active_levels
  539. \sa starpu_omp_get_active_level
  540. \fn int starpu_omp_get_ancestor_thread_num(int level)
  541. \ingroup API_OpenMP_Runtime_Support
  542. This function returns the number of the ancestor of the current parallel section.
  543. \return the number of the ancestor of the current parallel section.
  544. \fn int starpu_omp_get_team_size(int level)
  545. \ingroup API_OpenMP_Runtime_Support
  546. This function returns the size of the team of the current parallel section.
  547. \return the size of the team of the current parallel section.
  548. \fn int starpu_omp_get_active_level(void)
  549. \ingroup API_OpenMP_Runtime_Support
  550. This function returns the nestinglevel of the current innermost active parallel section.
  551. \return the nestinglevel of the current innermost active parallel section.
  552. \sa starpu_omp_set_nested
  553. \sa starpu_omp_get_nested
  554. \sa starpu_omp_get_max_active_levels
  555. \sa starpu_omp_set_max_active_levels
  556. \sa starpu_omp_get_level
  557. \fn int starpu_omp_in_final(void)
  558. \ingroup API_OpenMP_Runtime_Support
  559. This function checks whether the current task is final or not.
  560. \return <c>!0</c> if called from a final task.
  561. \return <c>0</c> otherwise.
  562. \fn enum starpu_omp_proc_bind_value starpu_omp_get_proc_bind(void)
  563. \ingroup API_OpenMP_Runtime_Support
  564. This function returns the proc_bind setting of the current parallel region.
  565. \return the proc_bind setting of the current parallel region.
  566. \fn void starpu_omp_set_default_device(int device_num)
  567. \ingroup API_OpenMP_Runtime_Support
  568. This function sets the number of the device to use as default.
  569. Note: The StarPU OpenMP runtime support currently ignores the argument of this function.
  570. \sa starpu_omp_get_default_device
  571. \sa starpu_omp_is_initial_device
  572. \fn int starpu_omp_get_default_device(void)
  573. \ingroup API_OpenMP_Runtime_Support
  574. This function returns the number of the device used as default.
  575. \return the number of the device used as default.
  576. \sa starpu_omp_set_default_device
  577. \sa starpu_omp_is_initial_device
  578. \fn int starpu_omp_get_num_devices(void)
  579. \ingroup API_OpenMP_Runtime_Support
  580. This function returns the number of the devices.
  581. \return the number of the devices.
  582. \fn int starpu_omp_get_num_teams(void)
  583. \ingroup API_OpenMP_Runtime_Support
  584. This function returns the number of teams in the current teams region.
  585. \return the number of teams in the current teams region.
  586. \sa starpu_omp_get_num_teams
  587. \fn int starpu_omp_get_team_num(void)
  588. \ingroup API_OpenMP_Runtime_Support
  589. This function returns the team number of the calling thread.
  590. \return the team number of the calling thread.
  591. \sa starpu_omp_get_num_teams
  592. \fn int starpu_omp_is_initial_device(void)
  593. \ingroup API_OpenMP_Runtime_Support
  594. This function checks whether the current device is the initial device or not.
  595. \fn int starpu_omp_get_max_task_priority
  596. \ingroup API_OpenMP_Runtime_Support
  597. The omp_get_max_task_priority routine returns the maximum value that can be
  598. specified in the priority clause.
  599. \return <c>!0</c> if called from the host device.
  600. \return <c>0</c> otherwise.
  601. \sa starpu_omp_set_default_device
  602. \sa starpu_omp_get_default_device
  603. \fn void starpu_omp_init_lock(starpu_omp_lock_t *lock)
  604. \ingroup API_OpenMP_Runtime_Support
  605. This function initializes an opaque lock object.
  606. \sa starpu_omp_destroy_lock
  607. \sa starpu_omp_set_lock
  608. \sa starpu_omp_unset_lock
  609. \sa starpu_omp_test_lock
  610. \fn void starpu_omp_destroy_lock(starpu_omp_lock_t *lock)
  611. \ingroup API_OpenMP_Runtime_Support
  612. This function destroys an opaque lock object.
  613. \sa starpu_omp_init_lock
  614. \sa starpu_omp_set_lock
  615. \sa starpu_omp_unset_lock
  616. \sa starpu_omp_test_lock
  617. \fn void starpu_omp_set_lock(starpu_omp_lock_t *lock)
  618. \ingroup API_OpenMP_Runtime_Support
  619. This function locks an opaque lock object. If the lock is already locked, the
  620. function will block until it succeeds in exclusively acquiring the lock.
  621. \sa starpu_omp_init_lock
  622. \sa starpu_omp_destroy_lock
  623. \sa starpu_omp_unset_lock
  624. \sa starpu_omp_test_lock
  625. \fn void starpu_omp_unset_lock(starpu_omp_lock_t *lock)
  626. \ingroup API_OpenMP_Runtime_Support
  627. This function unlocks a previously locked lock object. The behaviour of this
  628. function is unspecified if it is called on an unlocked lock object.
  629. \sa starpu_omp_init_lock
  630. \sa starpu_omp_destroy_lock
  631. \sa starpu_omp_set_lock
  632. \sa starpu_omp_test_lock
  633. \fn int starpu_omp_test_lock(starpu_omp_lock_t *lock)
  634. \ingroup API_OpenMP_Runtime_Support
  635. This function unblockingly attempts to lock a lock object and returns whether
  636. it succeeded or not.
  637. \return <c>!0</c> if the function succeeded in acquiring the lock.
  638. \return <c>0</c> if the lock was already locked.
  639. \sa starpu_omp_init_lock
  640. \sa starpu_omp_destroy_lock
  641. \sa starpu_omp_set_lock
  642. \sa starpu_omp_unset_lock
  643. \fn void starpu_omp_init_nest_lock(starpu_omp_nest_lock_t *lock)
  644. \ingroup API_OpenMP_Runtime_Support
  645. This function initializes an opaque lock object supporting nested locking operations.
  646. \sa starpu_omp_destroy_nest_lock
  647. \sa starpu_omp_set_nest_lock
  648. \sa starpu_omp_unset_nest_lock
  649. \sa starpu_omp_test_nest_lock
  650. \fn void starpu_omp_destroy_nest_lock(starpu_omp_nest_lock_t *lock)
  651. \ingroup API_OpenMP_Runtime_Support
  652. This function destroys an opaque lock object supporting nested locking operations.
  653. \sa starpu_omp_init_nest_lock
  654. \sa starpu_omp_set_nest_lock
  655. \sa starpu_omp_unset_nest_lock
  656. \sa starpu_omp_test_nest_lock
  657. \fn void starpu_omp_set_nest_lock(starpu_omp_nest_lock_t *lock)
  658. \ingroup API_OpenMP_Runtime_Support
  659. This function locks an opaque lock object supporting nested locking operations.
  660. If the lock is already locked by another task, the function will block until
  661. it succeeds in exclusively acquiring the lock. If the lock is already taken by
  662. the current task, the function will increase the nested locking level of the
  663. lock object.
  664. \sa starpu_omp_init_nest_lock
  665. \sa starpu_omp_destroy_nest_lock
  666. \sa starpu_omp_unset_nest_lock
  667. \sa starpu_omp_test_nest_lock
  668. \fn void starpu_omp_unset_nest_lock(starpu_omp_nest_lock_t *lock)
  669. \ingroup API_OpenMP_Runtime_Support
  670. This function unlocks a previously locked lock object supporting nested locking
  671. operations. If the lock has been locked multiple times in nested fashion, the
  672. nested locking level is decreased and the lock remains locked. Otherwise, if
  673. the lock has only been locked once, it becomes unlocked. The behaviour of this
  674. function is unspecified if it is called on an unlocked lock object. The
  675. behaviour of this function is unspecified if it is called from a different task
  676. than the one that locked the lock object.
  677. \sa starpu_omp_init_nest_lock
  678. \sa starpu_omp_destroy_nest_lock
  679. \sa starpu_omp_set_nest_lock
  680. \sa starpu_omp_test_nest_lock
  681. \fn int starpu_omp_test_nest_lock(starpu_omp_nest_lock_t *lock)
  682. \ingroup API_OpenMP_Runtime_Support
  683. This function unblocking attempts to lock an opaque lock object supporting
  684. nested locking operations and returns whether it succeeded or not. If the lock
  685. is already locked by another task, the function will return without having
  686. acquired the lock. If the lock is already taken by the current task, the
  687. function will increase the nested locking level of the lock object.
  688. \return <c>!0</c> if the function succeeded in acquiring the lock.
  689. \return <c>0</c> if the lock was already locked.
  690. \sa starpu_omp_init_nest_lock
  691. \sa starpu_omp_destroy_nest_lock
  692. \sa starpu_omp_set_nest_lock
  693. \sa starpu_omp_unset_nest_lock
  694. \fn void starpu_omp_atomic_fallback_inline_begin(void)
  695. \ingroup API_OpenMP_Runtime_Support
  696. This function implements the entry point of a fallback global atomic region. It
  697. blocks until it succeeds in acquiring exclusive access to the global atomic
  698. region.
  699. \sa starpu_omp_atomic_fallback_inline_end
  700. \fn void starpu_omp_atomic_fallback_inline_end(void)
  701. \ingroup API_OpenMP_Runtime_Support
  702. This function implements the exit point of a fallback global atomic region. It
  703. release the exclusive access to the global atomic region.
  704. \sa starpu_omp_atomic_fallback_inline_begin
  705. \fn double starpu_omp_get_wtime(void)
  706. \ingroup API_OpenMP_Runtime_Support
  707. This function returns the elapsed wallclock time in seconds.
  708. \return the elapsed wallclock time in seconds.
  709. \sa starpu_omp_get_wtick
  710. \fn double starpu_omp_get_wtick(void)
  711. \ingroup API_OpenMP_Runtime_Support
  712. This function returns the precision of the time used by \p starpu_omp_get_wtime.
  713. \return the precision of the time used by \p starpu_omp_get_wtime.
  714. \sa starpu_omp_get_wtime
  715. \fn void starpu_omp_vector_annotate(starpu_data_handle_t handle, uint32_t slice_base)
  716. \ingroup API_OpenMP_Runtime_Support
  717. This function enables setting additional vector metadata needed by the OpenMP Runtime Support.
  718. \p handle is vector data handle.
  719. \p slice_base is the base of an array slice, expressed in number of vector elements from the array base.
  720. \sa STARPU_VECTOR_GET_SLICE_BASE
  721. */