Le guide du Routard du modèle "Dispose"

Remerciements
C’est quoi ?
Introduction du traducteur
A qui s’adresse cet article ?
Dispose, Finalisation et gestion des ressources 
Aperçu
Le nettoyage implicite
Le nettoyage explicite
Le modèle Dispose
Exemples d’implémentation 
Le problème du versionnage 
Dispose
Conception de classes disposablesTravailler avec des objets IDisposable
Le block using en C# et VB, la sémantique C++
Finalisation
Les finaliseurs C#
Exemples d’utilisation du modèle Dispose
SafeHandler
HandleCollector et stress mémoire
HandleCollector
Add/Remove MemoryPressure

Remerciements

L'article d'origine a été rédigé par Joe Duffy  qui fait partie de l'équipe qui développe la BCL chez Microsoft. Je le remercie de m’avoir autorisé à réaliser cette traduction provenant d’un article publié dans son blog :

http://www.bluebytesoftware.com/blog/PermaLink.aspx?guid=88e62cdf-5919-4ac7-bc33-20c06ae539ae

Ce texte est en partie collectif, vous y trouverez donc les interventions de gens comme Jeffrey Richter, Herb Sutter, Brian Grunkemeyer,Chris Brumme, Brad Abrams, Krzysztof Cwalina, Clemens Szyperski.

Vu leur pédigrée on est dans de bonnes mains.

Introduction du traducteur

Je n’aime pas parler le Van Dame surtout si son usage relève d’une sorte de pédanterie pseudo-moderniste. Être dans le vent est une ambition que je laisse volontiers aux feuilles mortes. Mais l’exercice délicat de la traduction est difficile et appelle d’autant plus au compromis que ce n’est pas mon métier.

Par exemple si je ne cherche pas à traduire handle par poignée comme on le rencontre parfois, un design pattern est pour moi clairement un modèle de conception voire un modèle de développement. Je parle de ressources gérées et non pas managées et le verbe anglais dispose se traduit par détruire, ce qui dans ce papier est très précisément son sens d’ailleurs.

Je n’ai pas toutefois de problème à inventer des néologismes tels finaliseur et sa petite famille, du moment que cela s’écrive sans "z" !

J’espère ne pas avoir fait de trop graves contresens, mais n’hésitez pas à me les signaler. Pour reprendre la formule consacrée, je suis le seul responsable des erreurs contenues dans ce texte.

J'ai particulièrement été intéressé par ce document car il s'agit d'un article de fond. Le sujet est certes moins "sexy" que les classes génériques, mais il correspond à ce genre de bagages qui me fascine toujours chez les véritables gourous: la connaissance intime des petits détails.

De temps à autres j’ai ajouté au texte d’origine une « Note du traducteur ». Il s’agira toujours d’une référence bibliographique où l’on peut trouver des définitions et des clarifications sur tel concept dont parle le texte où apparaît la note. Je ne me suis en aucune manière permis d'altérer le texte d'origine.

A qui s’adresse cet article ?

Je pense qu’un développeur débutant ne pourra pas suivre longtemps. Il est indispensable d’avoir un minimum de bagage en .NET ou dans un autre langage géré tel Java ou éventuellement en C++.

Par ailleurs le document n’est pas un cours, mais plutôt une capture de savoir-faire. En particulier il fait de nombreuses références croisées. Il est donc absolument normal qu’une première lecture vous laisse parfois perplexe. C’est le genre de document que l’on doit lire au moins deux fois pour espérer comprendre.

De plus il présuppose un minimum de connaissance sur le sujet et en particulier le fonctionnement du ramasse-miettes. Vous trouverez une bonne introduction dans l’article de Thomas Gil (Tom) sur DNG : http://www.dotnetguru.org/articles/GC/GC.html

Ce guide de développement ne se confine pas à .NET 1.1, mais s’intéresse largement à la version 2.0 pour laquelle les nouveautés sont nombreuses.

Afin de pouvoir héberger la CLR dans SQL Server 2005 sans lui faire perdre son niveau de fiabilité cinq neuf, Microsoft a du en effet développer de nouveaux concepts : SafeHandle, finaliseur critique, zone d’exécution limitée (CER), contrat de fiabilité…

Un bon article d’introduction peut être lu ici:

http://www.microsoft.com/france/msdn/securite/Reliability_default.mspx

Mais aussi dans le chapitre 4 du livre best-seller de Patrick Smacchia :

http://www.dotnetguru.org/modules.php?op=modload&name=News&file=article&sid=687&mode=thread&order=0&thold=0

D’autres informations utiles peuvent être trouvées (en anglais) un peu partout.

Je vais juste citer ce papier de Chris Brumme au sujet de la finalisation :

http://blogs.msdn.com/cbrumme/archive/2004/02/20/77460.aspx

Et un document récapitulatif sur la gestion des ressources trouvé sur le site GotDotNet :

http://www.gotdotnet.com/team/libraries/whitepapers/resourcemanagement/resourcemanagement.aspx

Maintenant place aux experts !

Dispose, Finalisation et gestion des ressources

Le ramasse-miettes réalise un travail extraordinaire dans la gestion des allocations mémoire des objets .NET, mais il n’a jamais été conçu pour prendre en charge la mémoire ou les ressources systèmes non gérées.

Il existe une différence considérable entre ces deux mondes au point de nécessiter un pont logiciel dont l’écriture est largement de la responsabilité des développeurs des API.

Le but principal lorsque l’on traite de telles ressource est très simplement de rendre le plus efficace possible leur utilisation. Plus particulièrement lorsque ces ressources sont limitées en quantité. Vous devez vous efforcer de fournir à vos utilisateurs les moyens d’acquérir et libérer les ressources dont ils ont besoin et mettre en place un filet de sécurité capable d’éviter tout risque de fuite de ces ressources.

Heureusement, .NET fournit une couche d’abstraction capable de masquer aux yeux des développeurs les détails relatifs aux ressources non gérées (handle Windows ou GDI, connexion à une base de données, SafeHandle…). Toutefois leur grande variété possible peut nous amener à prendre en charge nous même leur gestion.

Ce document récapitule les meilleures pratiques pour implémenter les mécanismes explicites ou implicites de nettoyage des ressources. On parle souvent de modèle de conception Dispose ou IDisposable car il implique normalement l’interface IDisposable et sa méthode Dispose pour le nettoyage explicite et éventuellement une méthode Finalize pour le nettoyage implicite.

Suivre correctement ce modèle est important si l’on souhaite garantir un nettoyage propre, opportun et standardisé des ressources allouées.

Aperçu

Les types gérés peuvent à l’occasion envelopper des ressources qui non gérées. Dans de tels cas il est préférable d’utiliser la plus petite classe possible qui encadre de telles ressources. Idéalement on ne devrait n’y trouver que le code d’allocation, d’accès primaire et de libération. Il devient alors possible d’écrire une autre classe entièrement gérée afin de fournir un accès plus naturel. Le modèle de conception Dispose permet de limiter les risques et les difficultés qui seront examinés dans les chapitres qui suivent.

On doit toujours fournir une méthode explicite Dispose afin de libérer de façon déterministe les ressources appartenant à l’instance de la classe. Le nettoyage implicite par l’intermédiaire d’une méthode Finalize est également nécessaire lorsque la classe possède de telle ressource. Toutefois, souvent, la classe enveloppante (par exemple SafeHandle) s’en chargera pour vous. Reste alors au développeur la seule tâche d’implémenter le mécanisme de nettoyage explicite.

 Le nettoyage implicite

On devrait toujours fournir un nettoyage implicite pour protéger des ressources avec un SafeHandle. En fait, implémenter des finaliseurs à la main est rarement nécessaire depuis l’introduction du type SafeHandler dans l’environnement .NET 2.0.

Si une sémantique de finalisation supplémentaire est nécessaire, il est possible d’implémenter la méthode surchargée Finalize en utilisant la syntaxe spéciale mise à disposition par chaque langage (~T() en C# ou !T() en C++). L’environnement va alors pouvoir invoquer le finaliseur de façon non déterministe comme étape dans le processus de finalisation du ramasse-miettes afin de donner une dernière chance au système de libérer les ressources qu’il détient.

Non déterministe signifie simplement que la méthode sera invoquée par le ramasse-miettes à un moment indéterminé dans le temps, une fois qu’il n’existera plus de référence active à l’instance d’objet.

L’implémentation correcte d’un finaliseur est suffisamment difficile, nous verrons pourquoi plus loin, pour que vous deviez en étudier la nécessité.

  Le nettoyage explicite

Chaque fois qu’un type possède des ressources (ou des types qui eux même possèdent des ressources, vous devrez fournir à l’utilisateur un moyen de les libérer explicitement. Les développeurs disposent alors de l’option d’initier la libération des ressources lorsque l’objet n’est plus utilisé.

Vous allégez ainsi la tâche du ramasse-miettes ce qui ne peut qu’améliorer les performances et fournit en plus à l’utilisateur un moyen de réclamer les ressources allouées de façon déterministe.

De plus, si la ressource externe est rare ou coûteuse, comme par exemple les handles alloués par l’OS, les performances peuvent s’améliorer et éviter un épuisement de ces ressources.

Un contrôle explicite doit absolument se faire à l’aide de la méthode standard Dispose exposée depuis l’interface IDisposable - en C++, écrivez simplement un destructeur, ~T(), pour le type T, le compilateur génèrera la plomberie Dispose pour vous -.

Tout ceci implique en fait beaucoup plus de choses qu’écrire une méthode Dispose lorsque l’on créé une classe non scellée.

En général, on considère qu’une bonne conception de la part d’un consommateur d’un objet qui implémente IDisposable est d’appeler Dispose lorsqu’il n’a plus besoin de l’objet. C’est facile dans un langage tel C# qui offre une syntaxe spécifique avec le block using. C++ qui automatise complètement l’utilisation du bock using.

Le modèle Dispose

Si votre classe n’est pas scellée et doit effectuer un nettoyage des ressources, il est indispensable de suivre précisément le modèle de conception qui suit.

Pour le classes scellées, ce modèle n’a pas besoin d’être suivit, c’est à dire que vous pouvez vous contenter d’implémenter Dispose et Finalize avec la méthode dite simple.

Même dans ce dernier cas, votre code doit toujours adhérer au guide de codage concernant l’implémentation de la logique interne de Dispose ou Finalize.

Ce modèle a été conçu pour garantir un nettoyage fiable et prévisible, empêcher les fuites temporaires de ressources (comme par exemple un appel à Dispose oublié) et, plus important, fournit un modèle standard, non ambiguë, pour les développeurs et les compilateurs. La description qui suit démontre une ligne de conduite sur quand et pourquoi implémenter un finaliseur et pourquoi certains types IDisposable n’en utilise pas. Enfin, nous discuterons des problèmes de versionnage des classes qui nécessitent un nettoyage, en particulier lorsque l’on introduit un nouveau type dans la hiérarchie.

En C++, écrivez simplement le destructeur avec la syntaxe ~T() et le compilateur génèrera automatiquement toute la plomberie nécessaire que nous allons décrire plus loin dans ce chapitre. Dans les cas rares où vous souhaitez écrire vous-même un finaliseur avec !T(), le moyen recommandé est de mettre autant de code que possible dans le finaliseur (c’est à dire de code que le finaliseur peut effectivement prendre en charge - par exemple vous ne pouvez, de façon certaine, atteindre d’autres objets dans un finaliseur), placez le reste dans le destructeur et faites en sorte que celui-ci appelle explicitement le finaliseur.

·        Implémentez toujours le modèle Dispose sur un type non scellé qui contient des ressources qui doivent être ou peuvent être explicitement libérées. (par exemple les handles Windows, les ressources non gérées…). Ce modèle produit un moyen standardisé à la disposition des développeurs pour détruire de façon déterministe les ressources possédées par l’objet. Il aide également les sous-classes à libérer les ressources de sa classe de base.

·        Implémentez toujours complètement le modèle Dispose si les sous-classes sont IDisposable quand bien même la classe de base ne possède aucune ressource IDisposable. Cela permettra aux utilisateurs de la classe de base de coder un modèle Dispose dans de bonnes conditions. Un exemple intéressant est la classe System.IO.Stream. Bien qu’il s’agit d’une classe abstraite et ne possède pas à ce titre de ressources, la plupart de ses sous-classes oui. C’est pourquoi elle implémente le modèle Dispose.

Implémentez toujours IDisposable uniquement sur une classe dont l’une des classes de sa hiérarchie parente ne l’a pas déjà fait. La méthode publique Dispose() doit être non virtuelle et consister seulement en deux lignes : un appel à Dispose(true) suivit d’un appel à GC.SuppressFinalize(this).
L’appel à SuppressFinalize ne doit intervenir que si celui à Dispose a réussi, par conséquent on ne doit pas placer cet appel dans un block finally.
Les types qui héritent d’une autre classe qui suivent déjà ce modèle peuvent et doivent réutiliser l’implémentation existante de Dispose().
 

·        Toujours créer ou surcharger la méthode protégée Dispose(bool) pour prendre en charge toute la logique de nettoyage. Le nettoyage doit entièrement être effectué dans cette méthode – en tenant compte si nécessaire de l’argument de la méthode. Cet argument sera égal à false si la méthode est invoquée depuis le finaliseur.

·        Toujours appeler Dispose(bool) de la classe de base (si elle existe) comme la dernière opération faite dans le code de votre implémentation de Dispose(bool). Il est important de ne pas modifier la valeur de l’argument booléen au cours de votre logique de nettoyage. Vous vous assurez ainsi que la méthode de la classe de base effectuera son nettoyage et que celui ci n’interviendra pas avant que la sous-classe a terminé son travail au cas où elle a besoin des ressources de la méthode de base.

·        Toujours implémenter un finaliseur si votre objet est responsable du contrôle de la durée de vie d’au moins une ressource qui ne dispose pas de son propre finaliseur. Un type comme SafeHandle par exemple dispose de son propre finaliseur.
Dans les autres cas, les développeurs vont souvent négliger l’écriture d’un code garantissant l’exécution d’une logique de nettoyage explicite.
Si votre classe de base a déjà surchargée Finalize conformément à la forme correcte du modèle, vous ne devez pas faire à nouveau cette surcharge car l’appel à votre surcharge virtuelle Dispose(bool) se fera automatiquement.

Lorsque vous implémentez un finaliseur, placez toute la logique de finalisation dans la méthode Dispose(bool). Votre méthode de finalisation ne fera qu’un simple appel virtuel à Dispose(false) et rien d’autre.

Comme on l’a noté plus haut, toute logique de codage incapable de s’exécuter dans un contexte de finalisation, doit être filtrée de sorte à ne pas être appelée si l’argument est à false.

• Ne jamais ré-implémenter l’interface IDisposable ou bien surcharger Dispose() ou Finalize() si un type de base de la hiérarchie les a déjà défini de façon conforme au modèle de conception Dispose.
  Vous devez juste surcharger Dispose(boolean) et y intégrer votre logique de nettoyage afin d’être certain que les appels vers les méthodes de la classe de base seront effectués. Ré implémenter Finalize se traduit en fait par un appel inutile à Dispose(bool).

• Ne jamais créer de variantes autres de Dispose que celles-ci :
  void Dispose()
  void Dispose(bool disposing)
  
   

Dispose doit être considéré comme un mot réservé de façon à standardiser ce modèle de et éviter les confusions entre développeurs et compilateurs. Certains langages comme C++ peuvent choisir d’implémenter automatiquement ce modèle sur certains types en ajoutant des méthodes comme ~T() ou !T() et encapsulant leur appel dans Dispose(bool).

Exemples d’implémentation

Le modèle simplifié sans finaliseur (C#)

Dans la majorité des cas, vous n’aurez pas besoin d’implémenter de méthode Finalize. Cet exemple démontre le cas le plus simple, par exemple la présence d’un type SafeHandle dont on doit organiser le nettoyage :

Cas avec finaliseur (C#)

Considérez cet exemple comme le prototype de toute implémentation correcte du cas avec finaliseur. L’exemple montre également à quoi doit ressembler une classe qui introduit pour la première fois dans une hiérarchie une logique de nettoyage :

Cet exemple montre une classe qui étend ComplexeCleanupBase et s’intègre dans le cycle de vie de Dispose et Finalize pour assurer un comportement correct au nettoyage :

Notez que ComplexCleanupExtender ne ré implémente pas Dispose ni Finalize puisque la classe parent s’en charge déjà. L’implémentation fournie par la classe de base restera toujours valide dans le contexte des classes dérivées.

Exemple avec finaliseur (C++)

La surcharge du comportement de Dispose est montrée juste après. Notez que le chaînage vers la classe de base s’effectue automatiquement :

Le problème du versionnage

Si vous choisissez d’ajouter ce modèle de conception à une classe existante et non scellée, vous pouvez perturber à votre insu des sous classes déjà existantes. Pour la même raison, changer de contrat de sémantique entre une classe de base et une classe dérivée peut soulever de subtils problèmes de compatibilité. Introduire une notion de « disposabilité » dans une classe de base alors que rien de tel n’existait auparavant est problématique.

De plus l’ajout de nouvelles méthodes à une classe de base peut générer de nouvelles alertes de compilation sur les sous classes existantes. Ce chapitre aborde les points que vous devez soigneusement étudier avant de prendre une décision.

• Introduire une méthode publique Dispose() ou une méthode protected Dispose(bool) dans une classe de base, lèvera des alertes de compilation dans les sous classes qui auront elle-même implémentées ces méthodes. Le développeur devra donc soit masquer ces nouvelles méthodes à l’aide du modificateur new ou la surcharger afin de clarifier ses intentions.
  Les développeurs qui traitent les alertes comme des erreurs risquent de ne pas pouvoir compiler leur code.
• Introduire la méthode virtuelle protected Dispose(bool) peut ne pas avoir l’effet attendu si les sous classes ont déjà implémentées Dispose(bool). La sous classe ne se chaînera en effet pas à la méthode homonyme de sa classe de base. On risque alors d’observer des pertes de ressources temporaires et même des finalisations qui ne se font pas si la sous classe appelle GC.SuppressFinalize. Si vous êtes l’auteur de la sous classe, il est évidemment facile de corriger le problème en ajoutant un base.Dispose(bool). Mais pour les types diffusés publiquement, vous ne pouvez contrôler l’usage fait par vos utilisateurs.
• Si vous sous classez un type IDisposable qui ne suit pas de façon correcte le modèle précédemment présenté, d’autres complications peuvent se produire.
  La table qui suit résume les différentes possibilités pour permettre à la sous classe de s’abonner correctement à la chaîne de contrôle de la durée de vie des ressources.
  
  Ce tableau explique comment écrire la sous classe de sorte que celles qui les dériveront ultérieurement dispose d’un contrat clair et standard. Les cas considérés incluent ce que l’on doit faire si la classe de base implémente IDisposable publiquement, de façon privée ou pas du tout, que la classe de base dispose ou non d’une méthode Dispose(bool) et/ou si la classe de base a ou non une surcharge de Finalize.

Dispose

Si un type implémente IDisposable et se conforme à l’un des modèles présentés précédemment, alors le guide de conception suivant s’applique. Notez que cela concerne tout code qui s’exécute à l’intérieur de Dispose(), Dispose(bool) ou tout autre méthode pouvant être appelée par Dispose.

 Conception de classes disposables

• Toujours implémenter IDisposable sur chaque type ayant un finaliseur. Cela donne à l’utilisateur un moyen d’effectuer un nettoyage déterministe de ces mêmes ressources dont est responsable le finaliseur. Vous pourriez également implémenter Dispose sur des types sans finaliseur, par exemple lorsque vous détruisez transitivement des objets ou en utilisant des objets qui gèrent déjà leurs ressources avec des finaliseurs.

• Toujours concevoir vos méthodes Dispose de sorte à pouvoir être appelées plusieurs fois. La méthode peut parfaitement choisir de ne rien faire après le premier appel. Mais elle ne doit pas générer d’exception.

• Toujours détruire transitivement les champs concernés de votre type à l’intérieur d’une  méthode Dispose. On doit appeler Dispose() sur chaque champ dont le cycle de vie dépend de l’objet.
  Par exemple, considérons un cas où notre objet détient un champ privé de type TextReader. Alors on doit appeler la méthode Dispose du TextReader depuis la méthode Dispose du type principal. Si ce code est implémenté dans Dispose(bool), alors l’appel TextReader.Dispose ne doit se faire que si l’argument booléen est égal à true : atteindre d’autres objets durant la finalisation n’est pas conseillé. De plus, si votre objet ne contrôle pas la durée de vie d’un autre objet IDisposable, alors il ne doit pas chercher à appeler sa méthode Dispose puisqu’une autre partie du code peut parfaitement compter sur le fait qu’il soit actif. Négliger cela peut provoquer des bugs très subtils.

• Considérez qu’il est toujours possible qu’un type IDisposable soit mis à null avant d’être détruit. Par exemple :

Dans cet exemple, étant donné a une instance de CyclicClassA et b une instance de CyclicClassB.

Si a.cycle = b et b.cycle = a, la destruction transitive devrait engendrer une boucle infinie. C’est pourquoi l’objet est mis à null pour éviter ce problème.

• Evitez de lever une exception depuis Dispose à l’exception de situations critiques où le processus qui exécute le code est corrompu. Les utilisateurs s’attendent à ce que Dispose ne lève jamais d’exception. Examinons l’exemple suivant :

Si Dispose pouvait lever une exception, la logique implémentée ensuite dans le bloc finally ne s’exécuterai jamais. Pour éviter ce problème, l’utilisateur serait obligé de placer un autre bloc try/finally dans le bloc finally ! Cela devient vite très compliqué à suivre.

De plus, si l’exécution de Dispose(false) provoque une exception, le processus se terminerait dans le contexte du finaliseur.

• Toujours rendre l’objet inutilisable après avoir été détruit. Recréer un objet qui a déjà été détruit est souvent difficile, surtout lorsque des destructions transitives se sont produites. Dans de tels cas, invoquer des appels à des méthodes de cet objet doit lever l’exception ObjectDisposedException. S’il est possible de reconstruire un état, soyez alors certain d’avertir l’utilisateur qu’il doit potentiellement re-détruire plusieurs fois l’objet : la première fois, et à chaque fois après la reconstruction.

L’exemple suivant montre un exemple de ce mécanisme. Il est conçu non pas comme un modèle de conception, mais comme un simple exemple :

• Toujours implémenter une méthode Close pour le nettoyage des classes pour lesquelles une telle terminologie est un standard, comme un fichier ou un socket. Dans ce cas, il est recommandé d’implémenter Close exactement de la même manière que Dispose. L’expérience montre en effet que les développeurs ne pensent pas à appeler les deux méthodes, mais l’une ou l’autre. Essayer de déléguer la responsabilité du nettoyage à Dispose, par exemple en ajoutant un appel à Close() depuis Dispose(). Documenter soigneusement les situations qui s’écartent de ce modèle.

Notez qu’un scénario justifiant une déviation est le cas d’un objet qui peut être ouvert et fermé plusieurs fois sans que l’on souhaite recréer une instance. C’est par exemple le cas de System.Data.SqlClient.SqlConnection. Il est possible d’ouvrir et de fermer une connexion vers une base de données plusieurs fois.

• Annuler les objets gérés volumineux dans la méthode Dispose. C’est rarement nécessaire, mais peut être intéressant si un champ est coûteux à conserver en l’état car cet objet peut éventuellement rester en mémoire fort longtemps. Le simple fait d’appeler Dispose ne signifie pas que les références de l’objet soient libérées. Cela peut arriver par exemple dans le cas d’un conteneur (l’objet que l’on détruit) qui est référencé depuis une variable à longue durée de vie (comme une variable statique) et n’est pas explicitement annulée. L’annuler peut permettre d’abréger son existence en mémoire en le rendant éligible plus tôt lors d’une collection du ramasse-miettes. La définition d’un objet volumineux et coûteux est bien sûr subjective et doit s’appuyer sur des mesures de performance.
• Eviter de créer des objets IDisposable de type valeur et ne jamais créer de valeur dont dépend la durée de vie d’un objet géré directement. A l’exception des situations pour lesquelles une valeur ne sera jamais copiée (c’est à dire est uniquement locale dans le corps d’une méthode) ou copiée de façon très contrôlée, il est difficile de prédire comment la destruction d’une valeur va interagir avec la sémantique de passage par copie du type valeur. Par exemple une fois qu’une nouvelle copie a été obtenue, une autre copie pourrait accéder aux champs déjà détruits par une ancienne copie.

Auteur : Joe Duffy