Unload_dll

How to Safely Unload a DLL in Windows Using C++ Unloading a Dynamic Link Library (DLL) is a critical task for long-running applications that need to update plugins, free system resources, or manage complex dependencies without a full restart. However, improper unloading often leads to access violations, deadlocks, or memory corruption.

This guide explores the safest ways to unload a DLL, handle thread-safety issues, and avoid common pitfalls. 1. The Standard Approach: FreeLibrary

For DLLs loaded explicitly at runtime via LoadLibrary, the standard way to unload them is using FreeLibrary.

#include #include int main() { // 1. Load the DLL HMODULE hModule = LoadLibrary(L”MyPlugin.dll”); if (hModule == NULL) { std::cerr << “Failed to load DLL.” << std::endl; return 1; } // … Use GetProcAddress to call functions … // 2. Unload the DLL if (FreeLibrary(hModule)) { std::cout << “DLL successfully unloaded.” << std::endl; } else { std::cerr << “FreeLibrary failed: ” << GetLastError() << std::endl; } return 0; } Use code with caution. How it works:

Windows maintains a per-process reference count for each DLL.

LoadLibrary increments the count; FreeLibrary decrements it.

When the count reaches zero, the system calls DllMain with DLL_PROCESS_DETACH and unmaps the library from the process’s address space. 2. Solving the “Self-Unload” Problem

A common challenge arises when a DLL needs to unload itself (e.g., a background worker thread within the DLL finishes its task and wants to release the library).

Calling FreeLibrary and then ExitThread separately creates a race condition: the library might be unmapped before the ExitThread code can execute, causing an immediate crash. The Solution: Use FreeLibraryAndExitThread.

// Inside the DLL’s worker thread function DWORD WINAPI WorkerThread(LPVOID lpParam) { HMODULE hModule = (HMODULE)lpParam; // … Perform work … // Unload the DLL and terminate the thread in one atomic operation FreeLibraryAndExitThread(hModule, 0); // Code here is never reached. } Use code with caution. 3. Critical Safety Best Practices A. Avoid the “Loader Lock”

Windows uses a global synchronization object called the Loader Lock during DLL loading and unloading. Never call FreeLibrary inside DllMain.

Avoid complex cleanup, thread synchronization, or loading other DLLs inside DLL_PROCESS_DETACH, as this can lead to deadlocks. B. Clean Up External Pointers

FreeLibrary function (libloaderapi.h) – Win32 – Microsoft Learn