CoFreeUnusedLibrariesEx function (combaseapi.h)

Article
09/06/2022

Unloads any DLLs that are no longer in use and whose unload delay has expired.

Syntax

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

Parameters

[in] dwUnloadDelay

The delay in milliseconds between the time that the DLL has stated it can be unloaded until it becomes a candidate to unload. Setting this parameter to INFINITE uses the system default delay (10 minutes). Setting this parameter to 0 forces the unloading of any DLLs without any delay.

[in] dwReserved

This parameter is reserved and must be 0.

Return value

None

Remarks

COM supplies functions to reclaim memory held by DLLs containing components. The most commonly used function is CoFreeUnusedLibraries. CoFreeUnusedLibraries does not immediately release DLLs that have no active object. There is a 10-minute delay for multithreaded apartments (MTAs) and neutral apartments (NAs). For single-threaded apartments (STAs), there is no delay.

The 10-minute delay for CoFreeUnusedLibraries is to avoid multithread race conditions caused by unloading a component DLL. This default delay may be too long for many applications.

COM maintains a list of active DLLs that have had components loaded for the apartments that can be hosted on the thread where this function is called. When CoFreeUnusedLibrariesEx is called, each DLL on that list has its DllCanUnloadNow function called. If DllCanUnloadNow returns S_FALSE (or is not exported), this DLL is not ready to be unloaded. If DllCanUnloadNow returns S_OK, this DLL is moved off the active list to a "candidate-for-unloading" list.

Adding the DLL to the candidate-for-unloading list time-stamps the DLL dwUnloadDelay milliseconds from when this move occurs. When CoFreeUnusedLibrariesEx (or CoFreeUnusedLibraries) is called again, at least dwUnloadDelay milliseconds from the call that moved the DLL to the candidate-for-unloading list, the DLL is actually freed from memory. If COM uses the component DLL while the DLL is on the candidate-for-unloading list, it is moved back to the active list.

Setting dwUnloadDelay to 0 may have unexpected consequences. The component DLL may need some time for cleanup after it returns from the DllCanUnloadNow function. For example, if the DLL had its own worker threads, using a value of 0 would most likely lead to a problem because the code executing on these threads would be unmapped, caused by the unloading of the DLL before the worker threads have a chance to exit. Also, using too brief of a value for dwUnloadDelay can lead to performance issues because there is more overhead in reloading a DLL than letting it page out.

This behavior is triggered by the DLL supplying components with threading models set to Free, Neutral, or Both. For a threading model set to Apartment (or if no threading model is specified), dwUnloadDelay is treated as 0 because these components are tied to the single thread hosting the apartment.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	combaseapi.h (include Objbase.h)
Library	Ole32.lib
DLL	ComBase.dll