CoFreeUnusedLibrariesEx, fonction (combaseapi.h)

Article
08/22/2023

Décharge toutes les DLL qui ne sont plus utilisées et dont le délai de déchargement a expiré.

Syntaxe

void CoFreeUnusedLibrariesEx(
  [in] DWORD dwUnloadDelay,
  [in] DWORD dwReserved
);

Paramètres

[in] dwUnloadDelay

Délai en millisecondes entre le moment où la DLL a déclaré qu’elle peut être déchargée jusqu’à ce qu’elle devienne un candidat au déchargement. La définition de ce paramètre sur INFINITE utilise le délai par défaut du système (10 minutes). La définition de ce paramètre sur 0 force le déchargement des DLL sans délai.

[in] dwReserved

Ce paramètre est réservé et doit être 0.

Valeur de retour

None

Remarques

COM fournit des fonctions pour récupérer la mémoire détenue par des DLL contenant des composants. La fonction la plus couramment utilisée est CoFreeUnusedLibraries. CoFreeUnusedLibraries ne libère pas immédiatement les DLL qui n’ont pas d’objet actif. Il y a un délai de 10 minutes pour les appartements multithreads (MTA) et les appartements neutres (AN). Pour les appartements à thread unique (STA), il n’y a aucun délai.

Le délai de 10 minutes pour CoFreeUnusedLibraries est d’éviter les conditions de course multithread causées par le déchargement d’une DLL de composant. Ce délai par défaut peut être trop long pour de nombreuses applications.

COM tient à jour une liste des DLL actives pour lesquelles des composants ont été chargés pour les appartements qui peuvent être hébergés sur le thread où cette fonction est appelée. Lorsque CoFreeUnusedLibrariesEx est appelé, chaque DLL de cette liste a sa fonction DllCanUnloadNow appelée. Si DllCanUnloadNow retourne S_FALSE (ou n’est pas exporté), cette DLL n’est pas prête à être déchargée. Si DllCanUnloadNow retourne S_OK, cette DLL est déplacée hors de la liste active vers une liste « candidate-for-load ».

L’ajout de la DLL à la liste de candidats pour le déchargement marque le délai de la DLL dwUnloadDelay millisecondes à partir du moment où ce déplacement se produit. Lorsque CoFreeUnusedLibrariesEx (ou CoFreeUnusedLibraries) est appelé à nouveau, au moins dwUnloadDelay millisecondes de l’appel qui a déplacé la DLL vers la liste candidate-for-load, la DLL est en fait libérée de la mémoire. Si COM utilise la DLL de composant alors que la DLL figure sur la liste des candidats pour le déchargement, elle est déplacée vers la liste active.

La définition de dwUnloadDelay sur 0 peut avoir des conséquences inattendues. La DLL du composant peut avoir besoin d’un certain temps pour le nettoyage après son retour à partir de la fonction DllCanUnloadNow . Par exemple, si la DLL avait ses propres threads de travail, l’utilisation d’une valeur de 0 entraînerait probablement un problème, car le code s’exécutant sur ces threads serait non mappé, dû au déchargement de la DLL avant que les threads de travail aient la possibilité de quitter. En outre, l’utilisation d’une valeur trop courte pour dwUnloadDelay peut entraîner des problèmes de performances, car il y a plus de surcharge dans le rechargement d’une DLL que dans sa mise en page.

Ce comportement est déclenché par la DLL fournissant des composants avec des modèles de thread définis sur Free, Neutral ou Both. Pour un modèle de thread défini sur Apartment (ou si aucun modèle de thread n’est spécifié), dwUnloadDelay est traité comme 0, car ces composants sont liés au thread unique hébergeant l’appartement.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	combaseapi.h (inclure Objbase.h)
Bibliothèque	Ole32.lib
DLL	ComBase.dll