CoFreeUnusedLibrariesEx (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

void CoFreeUnusedLibrariesEx(
  DWORD dwUnloadDelay,
  DWORD dwReserved
);

Parameters

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

• dwReserved
  [in] Reserved for future use; must be zero.

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 the DllCanUnloadNow function 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.

Using a dwUnloadDelay of 0 may lead to 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 dwUnloadDelay time can lead to performance issues because there is a lot more overhead in reloading a DLL than letting it page out.

The behavior above 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.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

Header	objbase.h
Library	ole32.lib
Windows Embedded CE	Windows CE .NET 4.2 and later

See Also

Reference

COM Functions
CoFreeUnusedLibraries
CoLoadLibrary
DllCanUnloadNow