starpu_data.h 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644
  1. /* StarPU --- Runtime system for heterogeneous multicore architectures.
  2. *
  3. * Copyright (C) 2009-2021 Université de Bordeaux, CNRS (LaBRI UMR 5800), Inria
  4. * Copyright (C) 2021 Federal University of Rio Grande do Sul (UFRGS)
  5. *
  6. * StarPU is free software; you can redistribute it and/or modify
  7. * it under the terms of the GNU Lesser General Public License as published by
  8. * the Free Software Foundation; either version 2.1 of the License, or (at
  9. * your option) any later version.
  10. *
  11. * StarPU is distributed in the hope that it will be useful, but
  12. * WITHOUT ANY WARRANTY; without even the implied warranty of
  13. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  14. *
  15. * See the GNU Lesser General Public License in COPYING.LGPL for more details.
  16. */
  17. #ifndef __STARPU_DATA_H__
  18. #define __STARPU_DATA_H__
  19. #include <starpu.h>
  20. #ifdef __cplusplus
  21. extern "C"
  22. {
  23. #endif
  24. /**
  25. @defgroup API_Data_Management Data Management
  26. @brief Data management facilities provided by StarPU. We show how
  27. to use existing data interfaces in \ref API_Data_Interfaces, but
  28. developers can design their own data interfaces if required.
  29. @{
  30. */
  31. struct _starpu_data_state;
  32. /**
  33. StarPU uses ::starpu_data_handle_t as an opaque handle to manage a
  34. piece of data. Once a piece of data has been registered to StarPU,
  35. it is associated to a ::starpu_data_handle_t which keeps track of
  36. the state of the piece of data over the entire machine, so that we
  37. can maintain data consistency and locate data replicates for
  38. instance.
  39. */
  40. typedef struct _starpu_data_state* starpu_data_handle_t;
  41. /**
  42. Describe a StarPU data access mode
  43. Note: when adding a flag here, update
  44. _starpu_detect_implicit_data_deps_with_handle
  45. Note: other STARPU_* values in include/starpu_task_util.h
  46. */
  47. enum starpu_data_access_mode
  48. {
  49. STARPU_NONE=0, /**< todo */
  50. STARPU_R=(1<<0), /**< read-only mode */
  51. STARPU_W=(1<<1), /**< write-only mode */
  52. STARPU_RW=(STARPU_R|STARPU_W), /**< read-write mode. Equivalent to ::STARPU_R|::STARPU_W */
  53. STARPU_SCRATCH=(1<<2), /**< A temporary buffer is allocated
  54. for the task, but StarPU does not
  55. enforce data consistency---i.e. each
  56. device has its own buffer,
  57. independently from each other (even
  58. for CPUs), and no data transfer is
  59. ever performed. This is useful for
  60. temporary variables to avoid
  61. allocating/freeing buffers inside
  62. each task. Currently, no behavior is
  63. defined concerning the relation with
  64. the ::STARPU_R and ::STARPU_W modes
  65. and the value provided at
  66. registration --- i.e., the value of
  67. the scratch buffer is undefined at
  68. entry of the codelet function. It
  69. is being considered for future
  70. extensions at least to define the
  71. initial value. For now, data to be
  72. used in ::STARPU_SCRATCH mode should
  73. be registered with node -1 and a
  74. <c>NULL</c> pointer, since the value
  75. of the provided buffer is simply
  76. ignored for now.
  77. */
  78. STARPU_REDUX=(1<<3), /**< todo */
  79. STARPU_COMMUTE=(1<<4), /**< ::STARPU_COMMUTE can be passed
  80. along ::STARPU_W or ::STARPU_RW to
  81. express that StarPU can let tasks
  82. commute, which is useful e.g. when
  83. bringing a contribution into some
  84. data, which can be done in any order
  85. (but still require sequential
  86. consistency against reads or
  87. non-commutative writes).
  88. */
  89. STARPU_SSEND=(1<<5), /**< used in starpu_mpi_insert_task() to
  90. specify the data has to be sent using
  91. a synchronous and non-blocking mode
  92. (see starpu_mpi_issend())
  93. */
  94. STARPU_LOCALITY=(1<<6), /**< used to tell the scheduler which
  95. data is the most important for the
  96. task, and should thus be used to
  97. try to group tasks on the same core
  98. or cache, etc. For now only the ws
  99. and lws schedulers take this flag
  100. into account, and only when rebuild
  101. with \c USE_LOCALITY flag defined in
  102. the
  103. src/sched_policies/work_stealing_policy.c
  104. source code.
  105. */
  106. STARPU_MPI_REDUX=(1<<7), /**< Inter-node reduction only. Codelets
  107. contributing to these reductions should
  108. be registered with ::STARPU_RW | ::STARPU_COMMUTE
  109. access modes.
  110. When inserting these tasks through the
  111. MPI layer however, the access mode needs
  112. to be ::STARPU_MPI_REDUX. */
  113. STARPU_NOPLAN=(1<<8), /**< Disable automatic submission of asynchronous
  114. partitioning/unpartitioning */
  115. STARPU_ACCESS_MODE_MAX=(1<<9) /**< The purpose of ::STARPU_ACCESS_MODE_MAX is to
  116. be the maximum of this enum. */
  117. };
  118. struct starpu_data_interface_ops;
  119. /**
  120. Set the name of the data, to be shown in various profiling tools.
  121. */
  122. void starpu_data_set_name(starpu_data_handle_t handle, const char *name);
  123. /**
  124. Set the coordinates of the data, to be shown in various profiling
  125. tools. \p dimensions is the size of the \p dims array. This can be
  126. for instance the tile coordinates within a big matrix.
  127. */
  128. void starpu_data_set_coordinates_array(starpu_data_handle_t handle, unsigned dimensions, int dims[]);
  129. /**
  130. Set the coordinates of the data, to be shown in various profiling
  131. tools. \p dimensions is the number of subsequent \c int parameters.
  132. This can be for instance the tile coordinates within a big matrix.
  133. */
  134. void starpu_data_set_coordinates(starpu_data_handle_t handle, unsigned dimensions, ...);
  135. /**
  136. Get the coordinates of the data, as set by a previous call to
  137. starpu_data_set_coordinates_array() or starpu_data_set_coordinates()
  138. \p dimensions is the size of the \p dims array.
  139. This returns the actual number of returned coordinates.
  140. */
  141. unsigned starpu_data_get_coordinates_array(starpu_data_handle_t handle, unsigned dimensions, int dims[]);
  142. /**
  143. Unregister a data \p handle from StarPU. If the data was
  144. automatically allocated by StarPU because the home node was -1, all
  145. automatically allocated buffers are freed. Otherwise, a valid copy
  146. of the data is put back into the home node in the buffer that was
  147. initially registered. Using a data handle that has been
  148. unregistered from StarPU results in an undefined behaviour. In case
  149. we do not need to update the value of the data in the home node, we
  150. can use the function starpu_data_unregister_no_coherency() instead.
  151. */
  152. void starpu_data_unregister(starpu_data_handle_t handle);
  153. /**
  154. Similar to starpu_data_unregister(), except that StarPU does not
  155. put back a valid copy into the home node, in the buffer that was
  156. initially registered.
  157. */
  158. void starpu_data_unregister_no_coherency(starpu_data_handle_t handle);
  159. /**
  160. Destroy the data \p handle once it is no longer needed by any
  161. submitted task. No coherency is provided.
  162. This is not safe to call starpu_data_unregister_submit() on a handle that
  163. comes from the registration of a non-NULL application home buffer, since the
  164. moment when the unregistration will happen is unknown to the
  165. application. Only calling starpu_shutdown() allows to be sure that the data
  166. was really unregistered.
  167. */
  168. void starpu_data_unregister_submit(starpu_data_handle_t handle);
  169. /**
  170. Destroy all replicates of the data \p handle immediately. After
  171. data invalidation, the first access to \p handle must be performed
  172. in ::STARPU_W mode. Accessing an invalidated data in ::STARPU_R
  173. mode results in undefined behaviour.
  174. */
  175. void starpu_data_invalidate(starpu_data_handle_t handle);
  176. /**
  177. Submit invalidation of the data \p handle after completion of
  178. previously submitted tasks.
  179. */
  180. void starpu_data_invalidate_submit(starpu_data_handle_t handle);
  181. /**
  182. Specify that the data \p handle can be discarded without impacting
  183. the application.
  184. */
  185. void starpu_data_advise_as_important(starpu_data_handle_t handle, unsigned is_important);
  186. /**
  187. @name Access registered data from the application
  188. @{
  189. */
  190. /**
  191. This macro can be used to acquire data, but not require it to be
  192. available on a given node, only enforce R/W dependencies. This can
  193. for instance be used to wait for tasks which produce the data, but
  194. without requesting a fetch to the main memory.
  195. */
  196. #define STARPU_ACQUIRE_NO_NODE -1
  197. /**
  198. Similar to ::STARPU_ACQUIRE_NO_NODE, but will lock the data on all
  199. nodes, preventing them from being evicted for instance. This is
  200. mostly useful inside StarPU only.
  201. */
  202. #define STARPU_ACQUIRE_NO_NODE_LOCK_ALL -2
  203. /**
  204. The application must call this function prior to accessing
  205. registered data from main memory outside tasks. StarPU ensures that
  206. the application will get an up-to-date copy of \p handle in main
  207. memory located where the data was originally registered, and that
  208. all concurrent accesses (e.g. from tasks) will be consistent with
  209. the access mode specified with \p mode. starpu_data_release() must
  210. be called once the application no longer needs to access the piece
  211. of data. Note that implicit data dependencies are also enforced by
  212. starpu_data_acquire(), i.e. starpu_data_acquire() will wait for all
  213. tasks scheduled to work on the data, unless they have been disabled
  214. explictly by calling
  215. starpu_data_set_default_sequential_consistency_flag() or
  216. starpu_data_set_sequential_consistency_flag().
  217. starpu_data_acquire() is a blocking call, so that it cannot be
  218. called from tasks or from their callbacks (in that case,
  219. starpu_data_acquire() returns <c>-EDEADLK</c>). Upon successful
  220. completion, this function returns 0.
  221. */
  222. int starpu_data_acquire(starpu_data_handle_t handle, enum starpu_data_access_mode mode);
  223. /**
  224. Similar to starpu_data_acquire(), except that the data will be
  225. available on the given memory node instead of main memory.
  226. ::STARPU_ACQUIRE_NO_NODE and ::STARPU_ACQUIRE_NO_NODE_LOCK_ALL can
  227. be used instead of an explicit node number.
  228. */
  229. int starpu_data_acquire_on_node(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode);
  230. /**
  231. Asynchronous equivalent of starpu_data_acquire(). When the data
  232. specified in \p handle is available in the access \p mode, the \p
  233. callback function is executed. The application may access
  234. the requested data during the execution of \p callback. The \p callback
  235. function must call starpu_data_release() once the application no longer
  236. needs to access the piece of data. Note that implicit data
  237. dependencies are also enforced by starpu_data_acquire_cb() in case they
  238. are not disabled. Contrary to starpu_data_acquire(), this function is
  239. non-blocking and may be called from task callbacks. Upon successful
  240. completion, this function returns 0.
  241. */
  242. int starpu_data_acquire_cb(starpu_data_handle_t handle, enum starpu_data_access_mode mode, void (*callback)(void *), void *arg);
  243. /**
  244. Similar to starpu_data_acquire_cb(), except that the
  245. data will be available on the given memory node instead of main
  246. memory.
  247. ::STARPU_ACQUIRE_NO_NODE and ::STARPU_ACQUIRE_NO_NODE_LOCK_ALL can be
  248. used instead of an explicit node number.
  249. */
  250. int starpu_data_acquire_on_node_cb(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode, void (*callback)(void *), void *arg);
  251. /**
  252. Similar to starpu_data_acquire_cb() with the possibility of
  253. enabling or disabling data dependencies.
  254. When the data specified in \p handle is available in the access
  255. \p mode, the \p callback function is executed. The application may access
  256. the requested data during the execution of this \p callback. The \p callback
  257. function must call starpu_data_release() once the application no longer
  258. needs to access the piece of data. Note that implicit data
  259. dependencies are also enforced by starpu_data_acquire_cb_sequential_consistency() in case they
  260. are not disabled specifically for the given \p handle or by the parameter \p sequential_consistency.
  261. Similarly to starpu_data_acquire_cb(), this function is
  262. non-blocking and may be called from task callbacks. Upon successful
  263. completion, this function returns 0.
  264. */
  265. int starpu_data_acquire_cb_sequential_consistency(starpu_data_handle_t handle, enum starpu_data_access_mode mode, void (*callback)(void *), void *arg, int sequential_consistency);
  266. /**
  267. Similar to starpu_data_acquire_cb_sequential_consistency(), except that the
  268. data will be available on the given memory node instead of main
  269. memory.
  270. ::STARPU_ACQUIRE_NO_NODE and ::STARPU_ACQUIRE_NO_NODE_LOCK_ALL can be used instead of an
  271. explicit node number.
  272. */
  273. int starpu_data_acquire_on_node_cb_sequential_consistency(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode, void (*callback)(void *), void *arg, int sequential_consistency);
  274. int starpu_data_acquire_on_node_cb_sequential_consistency_quick(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode, void (*callback)(void *), void *arg, int sequential_consistency, int quick);
  275. /**
  276. Similar to starpu_data_acquire_on_node_cb_sequential_consistency(),
  277. except that the \e pre_sync_jobid and \e post_sync_jobid parameters can be used
  278. to retrieve the jobid of the synchronization tasks. \e pre_sync_jobid happens
  279. just before the acquisition, and \e post_sync_jobid happens just after the
  280. release.
  281. callback_acquired is called when the data is acquired in terms of semantic,
  282. but the data is not fetched yet. It is given a pointer to the node, which it
  283. can modify if it wishes so.
  284. This is a very internal interface, subject to changes, do not use this.
  285. */
  286. int starpu_data_acquire_on_node_cb_sequential_consistency_sync_jobids(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode, void (*callback_acquired)(void *arg, int *node, enum starpu_data_access_mode mode), void (*callback)(void *arg), void *arg, int sequential_consistency, int quick, long *pre_sync_jobid, long *post_sync_jobid, int prio);
  287. /**
  288. The application can call this function instead of starpu_data_acquire() so as to
  289. acquire the data like starpu_data_acquire(), but only if all
  290. previously-submitted tasks have completed, in which case starpu_data_acquire_try()
  291. returns 0. StarPU will have ensured that the application will get an up-to-date
  292. copy of \p handle in main memory located where the data was originally
  293. registered. starpu_data_release() must be called once the application no longer
  294. needs to access the piece of data.
  295. */
  296. int starpu_data_acquire_try(starpu_data_handle_t handle, enum starpu_data_access_mode mode);
  297. /**
  298. Similar to starpu_data_acquire_try(), except that the
  299. data will be available on the given memory node instead of main
  300. memory.
  301. ::STARPU_ACQUIRE_NO_NODE and ::STARPU_ACQUIRE_NO_NODE_LOCK_ALL can be used instead of an
  302. explicit node number.
  303. */
  304. int starpu_data_acquire_on_node_try(starpu_data_handle_t handle, int node, enum starpu_data_access_mode mode);
  305. #ifdef __GCC__
  306. /**
  307. STARPU_DATA_ACQUIRE_CB() is the same as starpu_data_acquire_cb(),
  308. except that the code to be executed in a callback is directly provided
  309. as a macro parameter, and the data \p handle is automatically released
  310. after it. This permits to easily execute code which depends on the
  311. value of some registered data. This is non-blocking too and may be
  312. called from task callbacks.
  313. */
  314. # define STARPU_DATA_ACQUIRE_CB(handle, mode, code) do \
  315. { \ \
  316. void callback(void *arg) \
  317. { \
  318. code; \
  319. starpu_data_release(handle); \
  320. } \
  321. starpu_data_acquire_cb(handle, mode, callback, NULL); \
  322. } \
  323. while(0)
  324. #endif
  325. /**
  326. Release the piece of data acquired by the
  327. application either by starpu_data_acquire() or by
  328. starpu_data_acquire_cb().
  329. */
  330. void starpu_data_release(starpu_data_handle_t handle);
  331. /**
  332. Similar to starpu_data_release(), except that the data
  333. was made available on the given memory \p node instead of main memory.
  334. The \p node parameter must be exactly the same as the corresponding \c
  335. starpu_data_acquire_on_node* call.
  336. */
  337. void starpu_data_release_on_node(starpu_data_handle_t handle, int node);
  338. /**
  339. Partly release the piece of data acquired by the application either by
  340. starpu_data_acquire() or by starpu_data_acquire_cb(), switching the
  341. acquisition down to \p down_to_mode. For now, only releasing from STARPU_RW
  342. or STARPU_W acquisition down to STARPU_R is supported, or down to the same
  343. acquisition. STARPU_NONE can also be passed as \p down_to_mode, in which
  344. case this is equivalent to calling starpu_data_release().
  345. */
  346. void starpu_data_release_to(starpu_data_handle_t handle, enum starpu_data_access_mode down_to_mode);
  347. /**
  348. Similar to starpu_data_release_to(), except that the data
  349. was made available on the given memory \p node instead of main memory.
  350. The \p node parameter must be exactly the same as the corresponding \c
  351. starpu_data_acquire_on_node* call.
  352. */
  353. void starpu_data_release_to_on_node(starpu_data_handle_t handle, enum starpu_data_access_mode down_to_mode, int node);
  354. /** @} */
  355. /**
  356. This is an arbiter, which implements an advanced but centralized
  357. management of concurrent data accesses, see \ref
  358. ConcurrentDataAccess for the details.
  359. */
  360. typedef struct starpu_arbiter *starpu_arbiter_t;
  361. /**
  362. Create a data access arbiter, see \ref ConcurrentDataAccess for the
  363. details
  364. */
  365. starpu_arbiter_t starpu_arbiter_create(void) STARPU_ATTRIBUTE_MALLOC;
  366. /**
  367. Make access to \p handle managed by \p arbiter
  368. */
  369. void starpu_data_assign_arbiter(starpu_data_handle_t handle, starpu_arbiter_t arbiter);
  370. /**
  371. Destroy the \p arbiter . This must only be called after all data
  372. assigned to it have been unregistered.
  373. */
  374. void starpu_arbiter_destroy(starpu_arbiter_t arbiter);
  375. /**
  376. Explicitly ask StarPU to allocate room for a piece of data on
  377. the specified memory \p node.
  378. */
  379. int starpu_data_request_allocation(starpu_data_handle_t handle, unsigned node);
  380. /**
  381. Prefetch levels
  382. Data requests are ordered by priorities, but also by prefetching level,
  383. between data that a task wants now, and data that we will probably want
  384. "soon".
  385. */
  386. enum starpu_is_prefetch
  387. {
  388. /** A task really needs it now! */
  389. STARPU_FETCH = 0,
  390. /** A task will need it soon */
  391. STARPU_TASK_PREFETCH = 1,
  392. /** It is a good idea to have it asap */
  393. STARPU_PREFETCH = 2,
  394. /** Get this here when you have time to */
  395. STARPU_IDLEFETCH = 3,
  396. STARPU_NFETCH
  397. };
  398. /**
  399. Issue a fetch request for the data \p handle to \p node, i.e.
  400. requests that the data be replicated to the given node as soon as possible, so that it is
  401. available there for tasks. If \p async is 0, the call will
  402. block until the transfer is achieved, else the call will return immediately,
  403. after having just queued the request. In the latter case, the request will
  404. asynchronously wait for the completion of any task writing on the
  405. data.
  406. */
  407. int starpu_data_fetch_on_node(starpu_data_handle_t handle, unsigned node, unsigned async);
  408. /**
  409. Issue a prefetch request for the data \p handle to \p node, i.e.
  410. requests that the data be replicated to \p node when there is room for it, so that it is
  411. available there for tasks. If \p async is 0, the call will
  412. block until the transfer is achieved, else the call will return immediately,
  413. after having just queued the request. In the latter case, the request will
  414. asynchronously wait for the completion of any task writing on the
  415. data.
  416. */
  417. int starpu_data_prefetch_on_node(starpu_data_handle_t handle, unsigned node, unsigned async);
  418. int starpu_data_prefetch_on_node_prio(starpu_data_handle_t handle, unsigned node, unsigned async, int prio);
  419. /**
  420. Issue an idle prefetch request for the data \p handle to \p node, i.e.
  421. requests that the data be replicated to \p node, so that it is
  422. available there for tasks, but only when the bus is really idle. If \p async is 0, the call will
  423. block until the transfer is achieved, else the call will return immediately,
  424. after having just queued the request. In the latter case, the request will
  425. asynchronously wait for the completion of any task writing on the data.
  426. */
  427. int starpu_data_idle_prefetch_on_node(starpu_data_handle_t handle, unsigned node, unsigned async);
  428. int starpu_data_idle_prefetch_on_node_prio(starpu_data_handle_t handle, unsigned node, unsigned async, int prio);
  429. /**
  430. Check whether a valid copy of \p handle is currently available on
  431. memory node \p node (or a transfer request for getting so is ongoing).
  432. */
  433. unsigned starpu_data_is_on_node(starpu_data_handle_t handle, unsigned node);
  434. /**
  435. Advise StarPU that \p handle will not be used in the close future, and is
  436. thus a good candidate for eviction from GPUs. StarPU will thus write its value
  437. back to its home node when the bus is idle, and select this data in priority
  438. for eviction when memory gets low.
  439. */
  440. void starpu_data_wont_use(starpu_data_handle_t handle);
  441. /**
  442. Advise StarPU to evict \p handle from the memory node \p node
  443. StarPU will thus write its value back to its home node, before evicting it.
  444. This may however fail if e.g. some task is still working on it.
  445. If the eviction was successful, 0 is returned ; -1 is returned otherwise.
  446. */
  447. int starpu_data_evict_from_node(starpu_data_handle_t handle, unsigned node);
  448. /**
  449. Set the write-through mask of the data \p handle (and
  450. its children), i.e. a bitmask of nodes where the data should be always
  451. replicated after modification. It also prevents the data from being
  452. evicted from these nodes when memory gets scarse. When the data is
  453. modified, it is automatically transfered into those memory nodes. For
  454. instance a <c>1<<0</c> write-through mask means that the CUDA workers
  455. will commit their changes in main memory (node 0).
  456. */
  457. void starpu_data_set_wt_mask(starpu_data_handle_t handle, uint32_t wt_mask);
  458. /**
  459. @name Implicit Data Dependencies
  460. In this section, we describe how StarPU makes it possible to
  461. insert implicit task dependencies in order to enforce sequential data
  462. consistency. When this data consistency is enabled on a specific data
  463. handle, any data access will appear as sequentially consistent from
  464. the application. For instance, if the application submits two tasks
  465. that access the same piece of data in read-only mode, and then a third
  466. task that access it in write mode, dependencies will be added between
  467. the two first tasks and the third one. Implicit data dependencies are
  468. also inserted in the case of data accesses from the application.
  469. @{
  470. */
  471. /**
  472. Set the data consistency mode associated to a data handle. The
  473. consistency mode set using this function has the priority over the
  474. default mode which can be set with
  475. starpu_data_set_default_sequential_consistency_flag().
  476. */
  477. void starpu_data_set_sequential_consistency_flag(starpu_data_handle_t handle, unsigned flag);
  478. /**
  479. Get the data consistency mode associated to the data handle \p handle
  480. */
  481. unsigned starpu_data_get_sequential_consistency_flag(starpu_data_handle_t handle);
  482. /**
  483. Return the default sequential consistency flag
  484. */
  485. unsigned starpu_data_get_default_sequential_consistency_flag(void);
  486. /**
  487. Set the default sequential consistency flag. If a non-zero
  488. value is passed, a sequential data consistency will be enforced for
  489. all handles registered after this function call, otherwise it is
  490. disabled. By default, StarPU enables sequential data consistency. It
  491. is also possible to select the data consistency mode of a specific
  492. data handle with the function
  493. starpu_data_set_sequential_consistency_flag().
  494. */
  495. void starpu_data_set_default_sequential_consistency_flag(unsigned flag);
  496. /** @} */
  497. /**
  498. Set whether this data should be elligible to be evicted to disk
  499. storage (1) or not (0). The default is 1.
  500. */
  501. void starpu_data_set_ooc_flag(starpu_data_handle_t handle, unsigned flag);
  502. /**
  503. Get whether this data was set to be elligible to be evicted to disk
  504. storage (1) or not (0).
  505. */
  506. unsigned starpu_data_get_ooc_flag(starpu_data_handle_t handle);
  507. /**
  508. Query the status of \p handle on the specified \p memory_node.
  509. \p is_allocated tells whether memory was allocated there for the data.
  510. \p is_valid tells whether the actual value is available there.
  511. \p is_loading tells whether the actual value is getting loaded there.
  512. \p is_requested tells whether the actual value is requested to be loaded
  513. there by some fetch/prefetch/idlefetch request.
  514. */
  515. void starpu_data_query_status2(starpu_data_handle_t handle, int memory_node, int *is_allocated, int *is_valid, int *is_loading, int *is_requested);
  516. /**
  517. Same as starpu_data_query_status2(), but without the is_loading parameter.
  518. */
  519. void starpu_data_query_status(starpu_data_handle_t handle, int memory_node, int *is_allocated, int *is_valid, int *is_requested);
  520. struct starpu_codelet;
  521. /**
  522. Set the codelets to be used for \p handle when it is accessed in the
  523. mode ::STARPU_REDUX. Per-worker buffers will be initialized with
  524. the codelet \p init_cl (which has to take one handle with STARPU_W), and
  525. reduction between per-worker buffers will be done with the codelet \p
  526. redux_cl (which has to take a first accumulation handle with
  527. STARPU_RW|STARPU_COMMUTE, and a second contribution handle with STARPU_R).
  528. */
  529. void starpu_data_set_reduction_methods(starpu_data_handle_t handle, struct starpu_codelet *redux_cl, struct starpu_codelet *init_cl);
  530. struct starpu_data_interface_ops* starpu_data_get_interface_ops(starpu_data_handle_t handle);
  531. unsigned starpu_data_test_if_allocated_on_node(starpu_data_handle_t handle, unsigned memory_node);
  532. void starpu_memchunk_tidy(unsigned memory_node);
  533. /**
  534. Set the field \c user_data for the \p handle to \p user_data . It can
  535. then be retrieved with starpu_data_get_user_data(). \p user_data can be any
  536. application-defined value, for instance a pointer to an object-oriented
  537. container for the data.
  538. */
  539. void starpu_data_set_user_data(starpu_data_handle_t handle, void* user_data);
  540. /**
  541. Retrieve the field \c user_data previously set for the \p handle.
  542. */
  543. void *starpu_data_get_user_data(starpu_data_handle_t handle);
  544. /**
  545. Set the field \c sched_data for the \p handle to \p sched_data . It can
  546. then be retrieved with starpu_data_get_sched_data(). \p sched_data can be any
  547. scheduler-defined value.
  548. */
  549. void starpu_data_set_sched_data(starpu_data_handle_t handle, void* sched_data);
  550. /**
  551. Retrieve the field \c sched_data previously set for the \p handle.
  552. */
  553. void *starpu_data_get_sched_data(starpu_data_handle_t handle);
  554. /**
  555. Check whether data \p handle can be evicted now from node \p node
  556. */
  557. int starpu_data_can_evict(starpu_data_handle_t handle, unsigned node, enum starpu_is_prefetch is_prefetch);
  558. /** @} */
  559. #ifdef __cplusplus
  560. }
  561. #endif
  562. #endif /* __STARPU_DATA_H__ */