Funzione CoFreeUnusedLibrariesEx (combaseapi.h)

Articolo
08/22/2023

Scarica tutte le DLL che non sono più in uso e il cui ritardo di scaricamento è scaduto.

Sintassi

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

Parametri

[in] dwUnloadDelay

Ritardo in millisecondi tra il tempo in cui la DLL ha dichiarato che può essere scaricata fino a quando non diventa un candidato per scaricare. L'impostazione di questo parametro su INFINITE usa il ritardo predefinito del sistema (10 minuti). L'impostazione di questo parametro su 0 forza lo scaricamento di qualsiasi DLL senza alcun ritardo.

[in] dwReserved

Questo parametro è riservato e deve essere 0.

Valore restituito

nessuno

Osservazioni

COM fornisce funzioni per recuperare la memoria contenuta nelle DLL contenenti componenti. La funzione più comunemente usata è CoFreeUnusedLibraries. CoFreeUnusedLibraries non rilascia immediatamente DLL che non hanno alcun oggetto attivo. C'è un ritardo di 10 minuti per appartamenti multithreaded (MTA) e appartamenti neutrali (NA). Per gli appartamenti a thread singolo (STA), non è previsto alcun ritardo.

Il ritardo di 10 minuti per CoFreeUnusedLibraries consiste nell'evitare condizioni di race race multithread causate dallo scaricamento di una DLL componente. Questo ritardo predefinito può essere troppo lungo per molte applicazioni.

COM gestisce un elenco di DLL attive con componenti caricati per gli appartamenti che possono essere ospitati nel thread in cui viene chiamata questa funzione. Quando viene chiamato CoFreeUnusedLibrariesEx , ogni DLL in tale elenco ha la relativa funzione DllCanUnloadNow chiamata. Se DllCanUnloadNow restituisce S_FALSE (o non viene esportata), questa DLL non è pronta per essere scaricata. Se DllCanUnloadNow restituisce S_OK, questa DLL viene spostata dall'elenco attivo in un elenco "candidato per lo scaricamento".

Aggiungendo la DLL all'elenco dei timestamp candidati per lo scaricamento, la DLL dwUnloadDelay millisecondi da quando si verifica questo spostamento. Quando viene chiamato di nuovo CoFreeUnusedLibrariesEx (o CoFreeUnusedLibraries), almeno dwUnloadDelay millisecondi dalla chiamata che ha spostato la DLL nell'elenco candidato per lo scaricamento, la DLL viene effettivamente liberata dalla memoria. Se COM usa la DLL del componente mentre la DLL si trova nell'elenco candidato per lo scaricamento, viene spostata nuovamente nell'elenco attivo.

L'impostazione di dwUnloadDelay su 0 può avere conseguenze impreviste. La DLL del componente potrebbe richiedere tempo per la pulizia dopo la restituzione dalla funzione DllCanUnloadNow . Ad esempio, se la DLL dispone di thread di lavoro propri, l'uso di un valore pari a 0 causerebbe probabilmente un problema perché il codice in esecuzione su questi thread sarebbe stato decompresso, causato dallo scaricamento della DLL prima che i thread di lavoro abbiano la possibilità di uscire. Inoltre, l'uso di un valore troppo breve per dwUnloadDelay può causare problemi di prestazioni perché il ricaricamento di una DLL comporta un sovraccarico maggiore rispetto all'uscita della pagina.

Questo comportamento viene attivato dalla DLL che fornisce componenti con modelli di threading impostati su Free, Neutral o Both. Per un modello di threading impostato su Apartment (o se non è specificato alcun modello di threading), dwUnloadDelay viene considerato 0 perché questi componenti sono collegati al thread singolo che ospita l'apartment.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	combaseapi.h (include Objbase.h)
Libreria	Ole32.lib
DLL	ComBase.dll