Merge pull request #1776 from arcaneframework/dev/gg-add-doc-for-memory-pool

Add documentation for accelerator memory pool

Author: grospelliergilles

arcane/doc/doc_user/chap_acceleratorapi/0_acceleratorapi.md

@@ -14,6 +14,8 @@ Sommaire de ce chapitre :
 2. \subpage arcanedoc_acceleratorapi_reduction <br>
   Présente les mécanismes disponibles pour effectuer des réductions.
 
+3. \subpage arcanedoc_acceleratorapi_memorypool <br>
+  Présente le mécanisme de pool de mémoire.
 ____
 
 <div class="section_buttons">

arcane/doc/doc_user/chap_acceleratorapi/5_reduce.md

@@ -72,6 +72,9 @@ ____
 
 <div class="section_buttons">
 <span class="back_section_button">
-\ref arcanedoc_acceleratorapi
+\ref arcanedoc_parallel_accelerator
+</span>
+<span class="next_section_button">
+\ref arcanedoc_acceleratorapi_memorypool
 </span>
 </div>

arcane/doc/doc_user/chap_acceleratorapi/6_memorypool.md

@@ -0,0 +1,79 @@
+# Pool de mémoire {#arcanedoc_acceleratorapi_memorypool}
+
+[TOC]
+
+%Arcane dispose depuis la version 3.14.10 (novembre 2024) d'un
+mécanisme de pool mémoire permettant de conserver une partie de la
+mémoire allouée pour les accélérateurs et ainsi éviter des appels
+couteux aux fonctions d'allocations ou de désallocation.
+
+\note Ce mécanisme est pour l'instant expérimental et ne fonctionne
+que pour CUDA.
+
+\warning L'utilisation du pool mémoire peut changer le comportement du
+code en supprimant des synchronisations implicites effectuées sur les
+streams associées aux allocations et au désallocation. Notamment, les
+appels tels que `cudaMalloc()` ou `cudaFree()`. La page
+[CUDA implicit synchronization behavior and conditions in detail]
+(https://forums.developer.nvidia.com/t/cuda-implicit-synchronization-behavior-and-conditions-in-detail/251729)
+explique ce comportement pour CUDA.
+
+Le gestionnaire de pool mémoire est désactivé par défaut. Il est
+possible de l'activer et de modifier son comportement en positionnant
+des variables d'environnements.
+
+<table>
+<tr><th>Variable d'environnement</th><th>Description</th></tr>
+
+<tr>
+<td>ARCANE_ACCELERATOR_MEMORY_POOL</td>
+<td>
+Indique le type de mémoire pour lesquelles on souhaite activer le
+pool. Les valeeurs sont spécifiées par une combinaison de bit:
+- 1 pour la mémoire managée (\arcane{eMemoryRessource::UnifiedMemory})
+- 2 pour la mémoire sur l'accélérateur (\arcane{eMemoryRessource::Device})
+- 4 pour la mémoire punaisée sur l'hôte
+  (\arcane{eMemoryRessource::HostPinned})
+
+Si la valeur de la variable d'environnement vaut `7` par exemple,
+alors le pool mémoire est actif pour ces 3 types de ressource mémoire.
+</td>
+</tr>
+
+<tr>
+<td>ARCANE_ACCELERATOR_MEMORY_POOL_MAX_BLOCK_SIZE</td>
+<td>
+Indique la taille maximale (en octet) des blocs qui sont conservés
+dans le pool mémoire. Une valeur élevée permet de faire moins
+d'allocations et de désallocation mais en contre-partie conserve plus
+de mémorie ce qui réduit la quantité disponible pour les allocations
+qui ne passent pas par le pool de mémoire. La valeur par défaut est de
+1Mo (1024*1024).
+</td>
+</tr>
+
+<tr>
+<td>ARCANE_ACCELERATOR_MEMORY_PRINT_LEVEL</td>
+<td>
+Indique si on affiche des informations sur l'utilisation de la
+mémoire. Ces informations sont utiles pour le débug uniquement. Les
+valeurs possibles sont:
+- 0 n'affiche aucune information
+- 1 affiche des statistiques d'utilisation en fin de calcul
+- 2 idem 1 et affiche des informations lors des réallocations
+- 3 idem 2 et affiche la pile d'appel pour une réallocation pour les
+  tableaux sans nom.
+- 4 idem 3 mais affiche la pile d'appel lors de la réallocation pour
+  tous les tableaux.
+</td>
+</tr>
+
+</table>
+
+____
+
+<div class="section_buttons">
+<span class="back_section_button">
+\ref arcanedoc_acceleratorapi_reduction
+</span>
+</div>

arcane/doc/userdoc.doxyfile

@@ -2431,6 +2431,7 @@ PREDEFINED             = DOXYGEN_DOC=1 \
                          ARCANE_UTILS_EXPORT= \
                          ARCANE_IMPL_EXPORT= \
                          ARCANE_GEOMETRY_EXPORT= \
+                         ARCCORE_MESSAGEPASSING_EXPORT= \
                          "ARCCORE_HOST_DEVICE=__host__ __device__" \
                          ARCCORE_DEPRECATED_2019(a)=[[deprecated(a)]] \
                          ARCCORE_DEPRECATED_2020(a)=[[deprecated(a)]] \