commit 2ef023abc1e2ed9263751f255f3dae97089d8b03
parent c0af245d3385cb882d07ee8cdade7b319d9db74b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 17 Jul 2026 17:28:31 +0200
Ajoute la section sur les allocations dynamiques
Diffstat:
| M | doc/fr/star-c.7 | | | 148 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 148 insertions(+), 0 deletions(-)
diff --git a/doc/fr/star-c.7 b/doc/fr/star-c.7
@@ -1462,6 +1462,154 @@ error:
.Ed
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LES ALLOCATIONS DYNAMIQUES
+Préférer l'interface d'allocation proposée par la
+bibliothèque
+.Ql RSys
+via son fichier d'en-tête
+.In rsys/mem_allocator.h .
+Elle enrichit la gestion de la mémoire dynamique proposée par la
+bibliothèque C standard, notamment en enregistrant la quantité de
+mémoire allouée.
+.Pp
+Utiliser dès lors les fonctions
+.Fn mem_alloc ,
+.Fn mem_calloc
+et
+.Fn mem_realloc
+pour allouer dynamiquement de la mémoire.
+Leur profil est celui des fonctions équivalentes proposées par la
+bibliothèque C, à savoir ces mêmes fonctions mais sans le prefixe
+.Ql mem_ .
+.Pp
+Privilégier la fonction
+.Fn mem_calloc
+à
+.Fn mem_alloc
+de sorte à initialiser la mémoire allouée à zéro, et d'éviter ainsi
+d'utiliser des données non initialisées.
+.Pp
+Ne pas convertir le pointeur retourné par les fonctions d'allocation.
+La conversion d'un pointeur vide vers n'importe quel autre type de
+pointeur est déjà assuré par le langage C.
+.Pp
+Définir la taille du bloc mémoire à allouer via le type pointé par la
+variable destination :
+.Bd -literal -offset Ds
+p = mem_calloc(42, sizeof(*p));
+.Ed
+.Pp
+L'alternative qui consiste à épeller le type pointé en argument de
+.Ql sizeof
+non seulement nuit à la lisibilité des sources, mais laisse en plus
+l'opportunité d'introduire un bogue dès lors que le type de pointeur
+est mis à jour mais pas le nom du type renseigné à
+.Ql sizeof .
+.Pp
+Utiliser la fonction
+.Fn mem_alloc_aligned
+pour allouer un bloc mémoire dont l'adresse doit être alignée sur un
+nombre d'octets spécifique.
+Utiliser la fonction
+.Xr memset 3 ,
+de la bibliothèque C standard, pour forcer la mise à zéro du bloc ainsi
+alloué sinon rempli d'octets
+aléatoires :
+.Bd -literal -offset Ds
+foo = mem_alloc_aligned(sizeof(*foo), 128/* Alignement */);
+memset(foo, 0, sizeof(*foo));
+.Ed
+.Pp
+Vérifier chaque allocation en testant que l'adresse retournée n'est pas
+.Ql NULL .
+Traiter ce cas comme une erreur et non un bogue
+.Pq section Sx LA GESTION DES ERREURS Ns
+ :
+.Bd -literal -offset Ds
+ foo = mem_calloc(1, sizeof(*foo);
+ if (!foo) {
+ res = RES_MEM_ERR;
+ goto error;
+ }
+.Ed
+.Pp
+Libérer la mémoire allouée via
+.Ql RSys
+avec la fonction
+.Fn mem_rm
+dont le profil est le même que celui de la fonction
+.Xr free 3 Ns
+ :
+.Bd -literal -offset Ds
+mem_rm(foo);
+.Ed
+.Pp
+Détecter la présence de fuites mémoires via la fonction
+.Fn mem_allocated_size
+qui retourne la quantité de mémoire qui reste allouée par la
+bibliothèque :
+.Bd -literal -offset Ds
+int
+main(void)
+{
+ size_t sz = 0;
+ int err = 0;
+
+ ...
+
+ if ((sz = mem_alloc_aligned()) != 0) {
+ fprintf(stderr, "Fuites mémoires : %lu octets\en", sz);
+ if (err == 0) err = 1;
+ }
+ return err;
+}
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Ss Les allocateurs mémoire
+Dans son fichier d'en-tête
+.In rsys/mem_allocator.h ,
+la bibliothèque
+.Ql RSys
+définit en plus une interface d'allocateur mémoire.
+Au contraire de son interface d'allocation qui enregistre la mémoire
+alloué globalement par la bibliothèque,
+chaque allocateur enregistre ses seules allocations.
+.Pp
+Plusieurs types d'allocateurs sont proposés par la bibliothèque
+.Ql RSys ,
+chacun mettant en oeuvre une politique d'allocation qui lui est propre.
+Si bien qu'en fonction du contexte, un type d'allocateur particulier
+peut s'avérer plus approprié, par exemple pour réduire les coûts
+d'allocations/désallocations.
+Décrire les différents types d'allocateurs définis dans la bibliothèque
+.Ql RSys
+sort du cadre de cette documentation.
+Le lecteur est invité à se référer à son fichier d'en-tête
+.In rsys/mem_allocator.h
+pour plus d'informations.
+.Pp
+Les convention listées précédemment quant aux allocation dynamiques
+s'appliquent à l'identique à l'utilisation des allocateurs.
+.Pp
+Utiliser un allocateur consiste à appeler des macros, dont le nom est
+une version en majuscule des fonctions de l'interface d'allocation.
+Avec en plus en premier argument l'addresse de l'allocateur concerné :
+.Bd -literal -offset Ds
+foo = MEM_CALLOC(&mem_default_allocator, 1, sizeof(*foo));
+
+\&...
+
+MEM_RM(&mem_default_allocator, foo);
+
+if (MEM_ALLOCATED_SIZE(&mem_default_allocator)) {
+ fprintf(stderr, "Fuites mémoires\en");
+}
+.Ed
+.Pp
+avec
+.Va mem_default_allocator
+l'allocateur par défaut définit par la bibliothèque
+.Ql RSys .
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LA GESTION DES ERREURS
.Sh LES PROGRAMME EN LIGNE DE COMMANDE
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
