Arcane  v3.16.0.0
Documentation utilisateur
Chargement...
Recherche...
Aucune correspondance
core/Runner.h
1// -*- tab-width: 2; indent-tabs-mode: nil; coding: utf-8-with-signature -*-
2//-----------------------------------------------------------------------------
3// Copyright 2000-2025 CEA (www.cea.fr) IFPEN (www.ifpenergiesnouvelles.com)
4// See the top-level COPYRIGHT file for details.
5// SPDX-License-Identifier: Apache-2.0
6//-----------------------------------------------------------------------------
7/*---------------------------------------------------------------------------*/
8/* Runner.h (C) 2000-2025 */
9/* */
10/* Gestion de l'exécution sur accélérateur. */
11/*---------------------------------------------------------------------------*/
12#ifndef ARCANE_ACCELERATOR_CORE_RUNNER_H
13#define ARCANE_ACCELERATOR_CORE_RUNNER_H
14/*---------------------------------------------------------------------------*/
15/*---------------------------------------------------------------------------*/
16
17#include "arcane/utils/Ref.h"
18#include "arcane/utils/MemoryRessource.h"
19
20#include "arcane/accelerator/core/RunQueue.h"
21
22#include <memory>
23
24/*---------------------------------------------------------------------------*/
25/*---------------------------------------------------------------------------*/
26
27namespace Arcane::Accelerator
28{
29
30/*---------------------------------------------------------------------------*/
31/*---------------------------------------------------------------------------*/
32/*!
33 * \brief Gestionnaire d'exécution pour accélérateur.
34 *
35 * Cette classe utilise une sémantique par référence
36 *
37 * Une instance de cette classe représente un back-end d'exécution. Il faut
38 * d'abord appelé initialize() avant de pouvoir utiliser les méthodes de
39 * l'instance ou alors il faut appeler l'un des constructeurs autre que le
40 * constructeur par défaut. Le back-end utilisé est choisi via l'énumération
41 * eExecutionPolicy. Les back-ends sont de deux types:
42 * - les back-ends qui s'exécutent sur l'hôte: eExecutionPolicy::Sequential
43 * et eExecutionPolicy::Thread,
44 * - les back-ends qui s'exécutent sur accélérateurs : eExecutionPolicy::CUDA,
45 * eExecutionPolicy::HIP et eExecutionPolicy::SYCL.
46 *
47 * La fonction \arcaneacc{isAcceleratorPolicy()} permet de savoir si une
48 * eExecutionPolicy est associée à un accélérateur.
49 *
50 * Si une instance de cette classe est associée à un accélérateur, celui-ci
51 * n'est pas forcément celui utilisé par défaut pour le thread courant.
52 * Pour garantir que les kernels associés à ce runner seront bien exécutés
53 * sur le bon device il est nécessaire d'appeler au moins une fois
54 * la méthode setAsCurrentDevice() et de le refaire si une autre partie du code
55 * ou si une bibliothèque externe change l'accélérateur par défaut.
56 *
57 * La classe Runner permet de créer des files d'exécutions (RunQueue)
58 * via la fonction makeQueue(). Ces files peuvent ensuite être utilisées
59 * pour lancer des commandes (RunCommand). La page \ref arcanedoc_acceleratorapi
60 * décrit le fonctionnement de l'API accélérateur.
61 *
62 * Il est possible de changer le mécanisme utilisé pour les réductions via
63 * la méthode setDeviceReducePolicy(). Par défaut on utilise un kernel
64 * utilisant des synchronisations entre blocs. Cela permet de garantir la
65 * répétabilité des résultats.
66 */
67class ARCANE_ACCELERATOR_CORE_EXPORT Runner
68{
69 friend impl::RunQueueImpl;
70 friend impl::RunCommandImpl;
71 friend RunQueue;
72 friend RunQueueEvent;
73 friend impl::RunnerImpl;
74
75 friend RunQueue makeQueue(const Runner& runner);
76 friend RunQueue makeQueue(const Runner* runner);
77 friend RunQueue makeQueue(const Runner& runner, const RunQueueBuildInfo& bi);
78 friend RunQueue makeQueue(const Runner* runner, const RunQueueBuildInfo& bi);
79 friend Ref<RunQueue> makeQueueRef(const Runner& runner);
80 friend Ref<RunQueue> makeQueueRef(Runner& runner, const RunQueueBuildInfo& bi);
81 friend Ref<RunQueue> makeQueueRef(Runner* runner);
82
83 public:
84
85 /*!
86 * \brief Créé un gestionnaire d'exécution non initialisé.
87 *
88 * Il faudra appeler initialize() avant de pouvoir utiliser l'instance
89 */
90 Runner();
91 //! Créé et initialise un gestionnaire pour l'accélérateur \a p
92 explicit Runner(eExecutionPolicy p);
93 //! Créé et initialise un gestionnaire pour l'accélérateur \a p et l'accélérateur \a device
95
96 public:
97
98 //! Politique d'exécution associée
100
101 //! Initialise l'instance. Cette méthode ne doit être appelée qu'une seule fois.
103
104 //! Initialise l'instance. Cette méthode ne doit être appelée qu'une seule fois.
105 void initialize(eExecutionPolicy v, DeviceId device);
106
107 //! Indique si l'instance a été initialisée
108 bool isInitialized() const;
109
110 /*!
111 * \brief Indique si on autorise la création de RunQueue depuis plusieurs threads.
112 *
113 * \deprecated La création de file est toujours thread-safe depuis la version
114 * 3.15 de Arcane.
115 */
116 ARCANE_DEPRECATED_REASON("Y2025: this method is a no op. Concurrent queue creation is always thread-safe")
117 void setConcurrentQueueCreation(bool v);
118
119 //! Indique si la création concurrent de plusieurs RunQueue est autorisé
120 bool isConcurrentQueueCreation() const;
121
122 /*!
123 * \brief Temps total passé dans les commandes associées à cette instance.
124 *
125 * Ce temps n'est significatif que si les RunQueue sont synchrones.
126 */
127 double cumulativeCommandTime() const;
128
129 //! Positionne la politique d'exécution des réductions
130 ARCANE_DEPRECATED_REASON("Y2025: this method is a no op. reduce policy is always eDeviceReducePolicy::Grid")
132
133 //! politique d'exécution des réductions
135
136 //! Positionne un conseil sur la gestion d'une zone mémoire
137 void setMemoryAdvice(ConstMemoryView buffer, eMemoryAdvice advice);
138
139 //! Supprime un conseil sur la gestion d'une zone mémoire
140 void unsetMemoryAdvice(ConstMemoryView buffer, eMemoryAdvice advice);
141
142 //! Device associé à cette instance.
143 DeviceId deviceId() const;
144
145 /*!
146 * \brief Positionne le device associé à cette instance comme le device par défaut du contexte.
147 *
148 * Cet appel est équivalent à cudaSetDevice() ou hipSetDevice();
149 */
150 void setAsCurrentDevice();
151
152 //! Information sur le device associé à cette instance.
153 const DeviceInfo& deviceInfo() const;
154
155 //! Information sur le device associé à cette instance.
157
158 //! Remplit \a attr avec les informations concernant la zone mémoire pointée par \a ptr
159 void fillPointerAttribute(PointerAttribute& attr, const void* ptr);
160
161 public:
162
163 /*!
164 * \brief Liste des devices pour la politique d'exécution \a policy.
165 *
166 * Si le runtime associé n'a pas encore été initialisé, cette méthode retourne \a nullptr.
167 */
168 static const IDeviceInfoList* deviceInfoList(eExecutionPolicy policy);
169
170 private:
171
172 // La création est réservée aux méthodes globales makeQueue()
173 static RunQueue _makeQueue(const Runner& runner)
174 {
175 return RunQueue(runner, true);
176 }
177 static RunQueue _makeQueue(const Runner& runner, const RunQueueBuildInfo& bi)
178 {
179 return RunQueue(runner, bi, true);
180 }
181 static Ref<RunQueue> _makeQueueRef(const Runner& runner)
182 {
183 return makeRef(new RunQueue(runner, true));
184 }
185 static Ref<RunQueue> _makeQueueRef(Runner& runner, const RunQueueBuildInfo& bi)
186 {
187 return makeRef(new RunQueue(runner, bi, true));
188 }
189
190 public:
191
192 //! API interne à Arcane
193 RunnerInternal* _internalApi();
194
195 private:
196
197 impl::IRunnerRuntime* _internalRuntime() const;
198 impl::RunnerImpl* _impl() const { return m_p.get(); }
199
200 private:
201
202 std::shared_ptr<impl::RunnerImpl> m_p;
203
204 private:
205
206 void _checkIsInit() const;
207 bool _isAutoPrefetchCommand() const;
208};
209
210/*---------------------------------------------------------------------------*/
211/*---------------------------------------------------------------------------*/
212
213/*---------------------------------------------------------------------------*/
214/*---------------------------------------------------------------------------*/
215
216/*!
217 * \brief Créé une file associée à \a runner.
218 *
219 * Cet appel est thread-safe.
220 */
221inline RunQueue
222makeQueue(const Runner& runner)
223{
224 return Runner::_makeQueue(runner);
225}
226
227/*---------------------------------------------------------------------------*/
228/*---------------------------------------------------------------------------*/
229/*!
230 * \brief Créé une file associée à \a runner.
231 *
232 * Cet appel est thread-safe.
233 */
234inline RunQueue
235makeQueue(const Runner* runner)
236{
237 ARCANE_CHECK_POINTER(runner);
238 return Runner::_makeQueue(*runner);
239}
240
241/*---------------------------------------------------------------------------*/
242/*---------------------------------------------------------------------------*/
243/*!
244 * \brief Créé une file associée à \a runner avec les propriétés \a bi.
245 *
246 * Cet appel est thread-safe.
247 */
248inline RunQueue
249makeQueue(const Runner& runner, const RunQueueBuildInfo& bi)
250{
251 return Runner::_makeQueue(runner, bi);
252}
253
254/*---------------------------------------------------------------------------*/
255/*---------------------------------------------------------------------------*/
256/*!
257 * \brief Créé une file associée à \a runner avec les propriétés \a bi.
258 *
259 * Cet appel est thread-safe.
260 */
261inline RunQueue
262makeQueue(const Runner* runner, const RunQueueBuildInfo& bi)
263{
264 ARCANE_CHECK_POINTER(runner);
265 return Runner::_makeQueue(*runner, bi);
266}
267
268/*---------------------------------------------------------------------------*/
269/*---------------------------------------------------------------------------*/
270/*!
271 * \brief Créé une référence sur file avec la politique d'exécution par défaut de \a runner.
272 *
273 * Si la file est temporaire, il est préférable d'utiliser makeQueue() à la place
274 * pour éviter une allocation inutile.
275 */
276inline Ref<RunQueue>
277makeQueueRef(const Runner& runner)
278{
279 return Runner::_makeQueueRef(runner);
280}
281
282/*---------------------------------------------------------------------------*/
283/*---------------------------------------------------------------------------*/
284/*!
285 * \brief Créé une référence sur file avec la politique d'exécution par défaut de \a runner.
286 *
287 * Si la file est temporaire, il est préférable d'utiliser makeQueue() à la place
288 * pour éviter une allocation inutile.
289 */
290inline Ref<RunQueue>
292{
293 return Runner::_makeQueueRef(runner, bi);
294}
295
296/*---------------------------------------------------------------------------*/
297/*---------------------------------------------------------------------------*/
298/*!
299 * \brief Créé une référence sur file avec la politique d'exécution par défaut de \a runner.
300 *
301 * Si la file est temporaire, il est préférable d'utiliser makeQueue() à la place
302 * pour éviter une allocation inutile.
303 */
304inline Ref<RunQueue>
306{
307 ARCANE_CHECK_POINTER(runner);
308 return Runner::_makeQueueRef(*runner);
309}
310
311/*---------------------------------------------------------------------------*/
312/*---------------------------------------------------------------------------*/
313
314} // End namespace Arcane::Accelerator
315
316/*---------------------------------------------------------------------------*/
317/*---------------------------------------------------------------------------*/
318
319#endif
#define ARCANE_CHECK_POINTER(ptr)
Macro retournant le pointeur ptr s'il est non nul ou lancant une exception s'il est nul.
Identifiant d'un composant du système.
Definition DeviceId.h:33
Information sur un device.
Definition DeviceInfo.h:32
Information mémoire d'un accélérateur.
Interface d'une liste de devices.
Informations sur une adresse mémoire.
Informations pour créer une RunQueue.
File d'exécution pour un accélérateur.
void fillPointerAttribute(PointerAttribute &attr, const void *ptr)
Remplit attr avec les informations concernant la zone mémoire pointée par ptr.
Definition Runner.cc:472
void setConcurrentQueueCreation(bool v)
Indique si on autorise la création de RunQueue depuis plusieurs threads.
Definition Runner.cc:320
static const IDeviceInfoList * deviceInfoList(eExecutionPolicy policy)
Liste des devices pour la politique d'exécution policy.
Definition Runner.cc:450
bool isInitialized() const
Indique si l'instance a été initialisée.
Definition Runner.cc:311
Runner()
Créé un gestionnaire d'exécution non initialisé.
Definition Runner.cc:260
RunnerInternal * _internalApi()
API interne à Arcane.
Definition Runner.cc:491
double cumulativeCommandTime() const
Temps total passé dans les commandes associées à cette instance.
Definition Runner.cc:385
friend Ref< RunQueue > makeQueueRef(const Runner &runner)
Créé une référence sur file avec la politique d'exécution par défaut de runner.
bool isConcurrentQueueCreation() const
Indique si la création concurrent de plusieurs RunQueue est autorisé
Definition Runner.cc:329
DeviceId deviceId() const
Device associé à cette instance.
Definition Runner.cc:424
void setDeviceReducePolicy(eDeviceReducePolicy v)
Positionne la politique d'exécution des réductions.
Definition Runner.cc:338
const DeviceInfo & deviceInfo() const
Information sur le device associé à cette instance.
Definition Runner.cc:433
DeviceMemoryInfo deviceMemoryInfo() const
Information sur le device associé à cette instance.
Definition Runner.cc:462
void initialize(eExecutionPolicy v)
Initialise l'instance. Cette méthode ne doit être appelée qu'une seule fois.
Definition Runner.cc:357
friend RunQueue makeQueue(const Runner &runner)
Créé une file associée à runner.
void setAsCurrentDevice()
Positionne le device associé à cette instance comme le device par défaut du contexte.
Definition Runner.cc:414
eDeviceReducePolicy deviceReducePolicy() const
politique d'exécution des réductions
Definition Runner.cc:348
void setMemoryAdvice(ConstMemoryView buffer, eMemoryAdvice advice)
Positionne un conseil sur la gestion d'une zone mémoire.
Definition Runner.cc:394
void unsetMemoryAdvice(ConstMemoryView buffer, eMemoryAdvice advice)
Supprime un conseil sur la gestion d'une zone mémoire.
Definition Runner.cc:404
eExecutionPolicy executionPolicy() const
Politique d'exécution associée.
Definition Runner.cc:302
Référence à une instance.
Espace de nom pour l'utilisation des accélérateurs.
Ref< RunQueue > makeQueueRef(const Runner &runner)
Créé une référence sur file avec la politique d'exécution par défaut de runner.
eDeviceReducePolicy
Politique des opératations de réduction sur les accélérateurs.
RunQueue makeQueue(const Runner &runner)
Créé une file associée à runner.
eMemoryAdvice
Conseils pour la gestion mémoire.
Definition Memory.h:36
eExecutionPolicy
Politique d'exécution pour un Runner.
auto makeRef(InstanceType *t) -> Ref< InstanceType >
Créé une référence sur un pointeur.