DllMain and the Loader Lock — The Real Reason You Are Told to "Do Nothing in DLL Initialization"

“When we load our own DLL, LoadLibrary never returns.” “It hangs only on certain PCs, or only when the service starts.” When you see failures like these, one of the first places to check is the DLL’s initialization code: DllMain and everything it calls.

DllMain is not like an application’s ordinary initialization function. It is a function the OS calls while holding the loader lock, so what it may do is tightly restricted. Microsoft’s position that “the ideal DllMain is an empty stub” comes from the fact that this restriction affects not only your own DLL but the other DLLs and threads in the process.¹

This article is for developers who write DLLs, plug-ins, and C++/CLI wrappers on Windows. It works through the topic in this order: why it stops, then where to move initialization, then how to shut down, then how to investigate a hang.

1. The Bottom Line First — Keep DllMain Small and Change When the Work Runs

Rather than looking for a safe way to write something inside DllMain, the basic approach is to reduce the work that runs there. Decide what stays in the following order.¹

What is easy to miss is that the same restrictions apply to the constructors and destructors of global and static C++ objects. In C++/CLI, you also eliminate every path that executes MSIL under the loader lock. Whether the DllMain body itself is empty is not enough to judge by.²³

If you are investigating a hang right now, start at Section 7; if you are reviewing a design, read Sections 2 through 6 in order, and you can match each prohibition with its remedy.

2. The Mechanism — DllMain Is Called Inside the Loader Lock

2.1 It Is Called Not Only at Load Time but Also When Threads Start and Exit

DllMain is the entry point the OS loader calls when a DLL enters or leaves a process or a thread. There are four notifications.²

A thread-start notification goes not only to the DLL that created the thread but to every DLL loaded in the process. DllMain is not “code that runs once when my DLL is loaded”. In a process that creates threads frequently, it runs on every notification.²

If you do not need the notifications, one option is to call DisableThreadLibraryCalls inside DLL_PROCESS_ATTACH. It cannot be used in a DLL linked with the static CRT, however, and static TLS imposes a condition of its own, so Section 5.3 treats that decision separately.⁴

2.2 Being Called With the Lock Held Is Where Every Restriction Starts

To keep DLL loads, unloads, and notifications consistent, the OS loader serializes them with a single loader lock per process. The important point is that it acquires this lock before calling DllMain and keeps holding it while DllMain runs.¹

During that time, any other thread in the same process that tries to load a DLL or to proceed through a thread start or exit notification waits for the lock to be released. It is not a place where you may insert a long wait just because it suits your own DLL.

flowchart TB
    accTitle: Why work in DllMain affects DLL notifications across the process
    accDescr: The loader acquires the process-wide loader lock before calling DllMain, and DLL loads and thread notifications on other threads wait for it to be released, so work in DllMain affects other DLLs and threads too
    loader["Loader acquires the shared lock"] --> dll["DllMain runs"]
    dll --> ret["DllMain returns"]
    ret --> unlock["Loader lock is released"]
    other["DLL load or notification on another thread"] --> wait["Waits for the same lock to be released"]
    unlock --> resume["Waiting work can proceed"]
    wait --> resume

Figure 1: The shared lock is held while DllMain runs, so a wait there stops the progress of other DLLs and threads.

The prohibitions that follow make sense once you ask “does this work need, directly or indirectly, the loader lock or the initialization of another DLL?”

3. Why It Stops — Understanding the Prohibitions Through Four Paths

3.1 Calling Something That Loads Another DLL

Avoid calling LoadLibrary / FreeLibrary from DllMain. LoadLibrary creates circular dependencies in the load order and leads to a DLL being used before its initialization code has run. On the shutdown side, there is likewise a risk of using a DLL that has already been processed or released.²

Not having written LoadLibrary yourself does not make you safe. Some User, Shell, and COM functions load other system components internally, and they can touch a component that is not yet initialized or already released and cause an access violation.²

The baseline of what can safely be called is the functions in Kernel32.dll that do not load other DLLs, since Kernel32.dll is guaranteed to be loaded by the time DllMain runs. For example, you can create synchronization objects such as critical sections and mutexes, and you can use TLS. The official documentation states explicitly, however, that no exhaustive list of safe functions exists. Do not reason “it is in Kernel32, so anything goes” or “I can create a synchronization object, so I may wait for other threads”.²

3.2 Waiting Inside DllMain for Another Thread to Exit

The classic deadlock happens when the DLL is unloaded: DllMain asks a worker thread to stop and then waits for it to exit.

Even after the worker finishes its own work, it has to pass through the DLL_THREAD_DETACH notification on thread exit. That notification needs the loader lock, which the waiting DllMain is holding. The result is that DllMain waits for the worker, and the worker waits for DllMain to return.⁵

sequenceDiagram
    accTitle: Why waiting for a thread in DllMain deadlocks
    accDescr: DllMain, holding the loader lock, waits for a worker thread to exit, but the exiting worker thread waits for the loader lock to be released for its DLL_THREAD_DETACH notification, so the two wait on each other and deadlock
    participant L as Loader (holding the lock)
    participant D as DllMain
    participant W as Worker thread
    L->>D: Notify DLL_PROCESS_DETACH
    D->>W: Request exit and wait for completion
    W->>W: Finish work and head for thread exit
    Note over W: Exit notification needs the loader lock
    Note over D,W: DllMain waits holding the lock, W waits for the lock

Figure 2: Even after the worker finishes its work, it cannot get through the thread exit notification, so the exit wait inside DllMain never ends.

This is not a case of “it stops if you are unlucky”; the mutual wait holds structurally. The cleanup needed at unload is treated in Section 6, separately from the work at process exit.

3.3 Your Own Lock and the Loader Lock Are Acquired in Opposite Orders

It is not only thread start and exit; APIs such as GetModuleHandle also need the loader lock internally. When the following two paths overlap, the lock acquisition order is inverted.⁶

• On the DllMain side, code that already holds the loader lock tries to take private lock G.
• On the worker side, code that already holds private lock G calls an API and tries to take the loader lock.

flowchart TB
    accTitle: Order inversion between the loader lock and a private lock
    accDescr: DllMain goes for a private lock while holding the loader lock, and a worker thread goes for the loader lock, for GetModuleHandle and the like, while holding the private lock, so the acquisition order is inverted and they deadlock
    d["DllMain: holding the loader lock"] --> dg["Goes for private lock G"]
    w["Worker: holding private lock G"] --> wl["Goes for the loader lock"]
    dg -.-> dead["Deadlock from inverted acquisition order"]
    wl -.-> dead
    wl -.-> api["Required internally by GetModuleHandle and others"]

Figure 3: When one side takes the loader lock and then G, and the other takes G and then the loader lock, each waits for the other to release.

The official guidance asks you to treat the loader lock as the top of the application’s lock hierarchy, that is, the lock acquired first. By the time you are inside DllMain, that lock is already held. Check not only the name of the function you call but also which locks you are holding when you call it.⁶

3.4 Even Just Creating a Thread Leaves Start-Wait and Lifetime Problems

CreateThread inside DllMain is not recommended either. The new thread cannot begin running its thread function until the DLL_THREAD_ATTACH notification has been processed. Because the current DllMain holds the loader lock, waiting inside that DllMain for the thread to start or finish deadlocks.⁵

Not waiting does not solve everything either. If the DLL is unloaded after DllMain returns but before the thread you created has started running, the thread’s start address points at code that has already been released, and a crash remains possible.⁵

flowchart TB
    accTitle: Two problems that remain when a thread is created in DllMain
    accDescr: A thread created in DllMain waits for the loader lock for its start notification, so if DllMain waits for it to start or finish they deadlock, and even if DllMain returns without waiting, the code's lifetime ends and it crashes if the DLL is unloaded before the thread starts running
    create["Thread created inside DllMain"] --> pending["New thread waits for the start notification"]
    pending --> q{"Wait for start or completion inside DllMain?"}
    q -->|"Yes"| dead["Mutual wait while holding the lock"]
    q -->|"No"| returns["Return from DllMain"]
    returns --> race["DLL unloaded before the thread starts running"]
    race --> crash["Code at the start address is gone"]

Figure 4: Not waiting inside DllMain and protecting the lifetime of the DLL the created thread uses are two separate requirements.

4. Two Places That Are Dangerous Even When DllMain Is Empty

4.1 Dynamic Initialization of Global and Static Objects

In a DLL linked with the CRT (the C/C++ runtime), the constructors and destructors of global and static C++ objects run through the CRT’s entry point. They are effectively part of DllMain and are subject to the same restrictions.²

Putting configuration-file loading, logger startup, COM initialization, or thread startup into a constructor only hides where the call is made; the moment it runs is still inside the loader lock. If that complex work includes loading another DLL or synchronizing with threads, it is exactly as dangerous as writing it in the DllMain body.

flowchart TB
    accTitle: How global object initialization becomes a landmine
    accDescr: Loading the DLL acquires the loader lock and the constructors of global objects run through the CRT, so a LoadLibrary, thread synchronization, or COM initialization inside them is an execution of what DllMain prohibits
    load["DLL load (loader lock acquired)"] --> crt["CRT entry point"]
    crt --> ctor["Global object constructor"]
    ctor --> ng1["LoadLibrary-equivalent work"]
    ctor --> ng2["Start a thread and wait for it to finish"]
    ctor --> ng3["Use of COM or User32"]
    ng1 -.-> risk["All of these are DllMain prohibitions"]
    ng2 -.-> risk
    ng3 -.-> risk

Figure 5: Review not only the DllMain body but also the initialization and termination of static objects called from the CRT.

Treat compile-time constant initialization, for example anything that can be constexpr, separately from complex run-time initialization. Defer dynamic initialization that involves function calls, and arrange for the first access to happen outside DllMain as well.

4.2 MSIL Executed in a C++/CLI Callee

Wrapping a native DLL in C++/CLI is covered in Calling Native DLLs from C#: C++/CLI Wrapper vs P/Invoke. In this configuration, watch for paths that execute MSIL (managed code) under the loader lock. If executing the MSIL requires CLR initialization or the load of another assembly, a deadlock is possible.³

The compiler emits warning C4747 for code in which DllMain directly tries to execute MSIL. But it cannot detect indirect execution through a function in another module. The absence of the warning alone is no basis for calling the code safe. Dynamic initializers of static objects are also in scope.³

flowchart TB
    accTitle: Whether MSIL execution under the loader lock can be detected
    accDescr: Code in which DllMain executes MSIL directly can be detected by the compiler with warning C4747, but indirect execution through a function in another module cannot, so it has to be prevented by reviewing the call tree and compiling natively throughout
    d2["Call from DllMain"] --> dir["Executes MSIL directly"]
    d2 --> ind["Executes via another module"]
    dir --> c47["Detected by warning C4747"]
    ind --> nc["Compiler cannot detect it"]
    nc -.-> rv["Prevent by review and #pragma unmanaged"]

Figure 6: In addition to the direct path that C4747 detects, review calls that go through another module.

The remedy is to compile DllMain and every function reachable from it as native code with #pragma unmanaged, or to have no DllMain at all. Even with the latter, do not overlook indirect paths such as static initializers.³

5. Designing Initialization — Make It Static, Defer It, Keep Only the Minimum

5.1 Before Leaving Something in DllMain, Ask Whether Its Timing Can Change

The official baseline is to complete whatever initialization you can at compile time and defer the rest as far as possible. Only work that must be detected early as a load failure stays, as an exception and at a minimum.¹

For instance, there can be a requirement to make the DLL load itself fail because a configuration file it depends on is corrupt. Even then, narrow it to “attempt the required work and fail immediately” rather than running other initialization first and failing afterward. This is not an exception that permits complex initialization at load time.¹

flowchart TB
    accTitle: Design guidelines for DLL initialization
    accDescr: First consider whether initialization can be static at compile time; if not, default to deferring it to first use, and leave in DllMain only the minimum that must be detected early as a load failure
    q1{"Decidable at compile time?"} -->|"Yes"| s["Make it static initialization"]
    q1 -->|"No"| q2{"Must the failure be detected at load?"}
    q2 -->|"No"| lazy["Defer to first use (the default)"]
    q2 -->|"Yes"| min["Do only the minimum in DllMain"]
    lazy -.-> once["Guard with INIT_ONCE or a function-local static"]

Figure 7: Consider static and deferred initialization first, and leave in DllMain only the minimum that needs early detection.

5.2 Deferred Initialization Has to Be Designed Down to “Who Calls It First”

For mutual exclusion on first use, you can use one-time initialization with INIT_ONCE or a C++ function-local static (a magic static). The idea is to move complex global objects to a pointer created on first access or to a function-local static.

Deferring alone, however, does not get you out of the loader lock. The restriction is lifted only when the first access comes from “an ordinary API called after the DLL load has completed”. In that case, it can be designed as ordinary initialization code that may use nearly the entire Windows API.¹

Conversely, if that first access happens from DllMain or a static initializer, the initialization still ends up running under the loader lock. Beyond extracting an initialization function, confirm who calls it first, and when.

flowchart TB
    accTitle: When deferred initialization escapes the loader lock
    accDescr: If the first access of deferred initialization comes from an ordinary API after the load completes, it can initialize outside the loader lock, but if it comes from DllMain or a static initializer, it runs under the same restrictions
    first{"Where does the first access come from?"}
    first -->|"Ordinary API after the load completes"| outside["Initialize outside the loader lock"]
    first -->|"DllMain or a static initializer"| inside["Initialize under the same restrictions"]
    outside --> once["Guard with INIT_ONCE or a function-local static"]
    inside --> move["Move the moment of first access too"]

Figure 8: INIT_ONCE and function-local statics take care of mutual exclusion for the initialization; they do not guarantee it is called outside the loader lock.

5.3 Decide on DisableThreadLibraryCalls by Three Conditions

In a DLL that does not depend on thread notifications, calling DisableThreadLibraryCalls in DLL_PROCESS_ATTACH stops the DLL_THREAD_ATTACH / DLL_THREAD_DETACH notifications. In a process that creates threads frequently, this reduces notification overhead.⁴

Before applying it, check the static CRT, static TLS, and whether anything uses the notifications. A DLL linked with the static CRT must not call it, because the CRT itself needs the thread notifications. When static TLS via thread_local or __declspec(thread) is in effect, the call itself fails and returns FALSE.⁴

flowchart TB
    accTitle: Deciding whether to call DisableThreadLibraryCalls
    accDescr: A DLL linked with the static CRT must not call it, and with static TLS in effect the call itself fails so it is not called, but a DLL that is neither and does not use thread notifications can call it in DLL_PROCESS_ATTACH, checking the return value, to cut notification cost
    q1{"Linked with the static CRT?"} -->|"Yes"| no2["Must not call it"]
    q1 -->|"No"| q2{"Uses static TLS?"}
    q2 -->|"Yes"| eff["Call fails anyway (FALSE)"]
    q2 -->|"No"| q3{"Needs thread notifications?"}
    q3 -->|"No"| yes["Call it in ATTACH (check the return value)"]
    q3 -->|"Yes"| keep["Do not call it; handle the notifications"]

Figure 9: Distinguish the static CRT, where it must not be used, from static TLS, where it fails, and check the return value even when notifications are unneeded.

It is an optimization to consider for a typical DLL that uses the dynamically linked CRT and meets these conditions. DisableThreadLibraryCalls exists to reduce notifications; it is not a means of doing complex initialization in DllMain.

6. Shutdown — Separate DLL Unload From Process Exit

6.1 The Same DLL_PROCESS_DETACH, but What Remains Afterward Differs

DLL_PROCESS_DETACH is delivered both when only the DLL is unloaded and when the whole process exits. The notification has the same name, but the premises for cleanup differ.⁵

On an unload via FreeLibrary, the process keeps running afterward. So threads must be stopped, and open handles, allocated resources, state that needs persisting, and so on must be cleaned up properly. As Section 3.2 showed, however, waiting inside DllMain for a thread’s natural exit for that purpose deadlocks.⁵

Better still, avoid a design in which a DLL that can be unloaded owns threads at all; moving thread ownership to the EXE side is the safest option. For an existing design in which the DLL owns threads, consider the following stop protocol together with its constraints, never one without the other.

6.2 The Officially Documented Stop Protocol When the DLL Owns a Worker

Microsoft’s best practices document a stop procedure for unload that waits not for “the thread’s natural exit” but for “a signal that it has reached a consistent state”.⁵

1. The DllMain side signals the worker to stop, using an event.
2. The worker winds down its current work to a consistent state, signals completion, and enters an infinite wait.
3. The DllMain side confirms the consistent state and ends the thread with TerminateThread.

It looks rough, but it was documented under the constraint that waiting for a natural exit makes the exit notification collide with the loader lock. The premise is that the work of reaching the consistent state also obeys the same restrictions as DllMain. If that work enters a load of another DLL or a wait for the loader lock, a deadlock with the side waiting for the signal is unavoidable.⁵

sequenceDiagram
    accTitle: Waiting at unload for consistency completion rather than natural exit
    accDescr: DllMain signals the worker to stop, the worker reaches a consistent state while obeying the same restrictions as DllMain, signals back, and enters an infinite wait, and DllMain confirms the consistent state before terminating the thread
    participant D as DllMain (at unload)
    participant W as Worker thread
    D->>W: Signal stop with an event
    W->>W: Reach a consistent state under the same restrictions
    W->>D: Signal consistency reached
    W->>W: Enter an infinite wait
    D->>W: Confirm consistency, then TerminateThread
    Note over D,W: What is awaited is the consistency signal, not natural exit

Figure 10: Even with this protocol, the work that establishes the consistent state must not wait for the loader lock.

This does not mean that any running thread may simply be cut off. First consider whether the thread can be owned outside the DLL.

6.3 At Process Exit, the Ideal Is to Return Without Doing Anything

By the time DLL_PROCESS_DETACH is delivered at process exit, the other threads have exited or been forcibly terminated, and the consistency of the address space cannot be relied on. The state of dependent DLLs and runtimes cannot be trusted either, so cleanup such as freeing memory becomes dangerous rather than helpful. The official guidance also says that the ideal handler in this case is empty.⁵

Write out data that needs persisting in the application’s own shutdown code. Do not use DLL_PROCESS_DETACH as the last place where anything can be tidied up.

flowchart TB
    accTitle: Cleanup premises differ between DLL unload and process exit
    accDescr: When only the DLL is unloaded, the process keeps running so resources must be cleaned up, but avoid waiting for natural exit inside DllMain; at process exit, do not rely on the consistency of other threads and resources, basically return without doing anything, and write out state to save in the application's shutdown code beforehand
    reason{"Reason for DLL_PROCESS_DETACH?"}
    reason -->|"DLL unload only"| alive["Process keeps running afterward"]
    alive --> cleanup["Clean up remaining resources properly"]
    cleanup -.-> nojoin["Do not wait for natural exit inside DllMain"]
    reason -->|"Process exit"| processEnd["State of other threads and resources is uncertain"]
    processEnd --> empty["Basically return without doing anything"]
    empty -.-> save["Save beforehand in the application's shutdown code"]

Figure 11: Decide not just “is cleanup needed” but whether the process keeps running and whether the resources used for cleanup can be trusted.

7. Investigating a Hang — Find the Side Waiting for the Loader Lock and the Side Holding It

7.1 Confirm the Pair of Mutually Waiting Threads in a Dump

Capture a dump at the moment of the freeze and examine each thread’s stack. The typical fingerprint is a pair: a thread waiting for a lock inside a loader function in ntdll.dll whose name starts with Ldr, and a thread waiting for something else inside DllMain or a static initializer (dynamic initializer).

A thread stopped in the middle of a LoadLibrary call is another typical participant. Once the relationship between the side waiting for the lock and the side holding it while waiting for something else connects, you can almost certainly conclude that it is a loader-lock deadlock.

flowchart TB
    accTitle: Confirming a loader-lock mutual wait from a hang dump
    accDescr: In each thread's stack look for a lock wait in Ldr functions and a wait inside DllMain or a static initializer, confirm that the two are waiting on each other, and if the typical pair does not appear, investigate other kinds of hang as well
    dump["Capture a dump during the hang"] --> stacks["Examine each thread's stack"]
    stacks --> ldr["Lock wait in Ldr functions"]
    stacks --> init["Wait inside DllMain or a static initializer"]
    ldr --> pair{"Does the mutual-wait relationship connect?"}
    init --> pair
    pair -->|"Yes"| found["Loader-lock deadlock"]
    pair -->|"Not visible"| more["Investigate other kinds of hang too"]

Figure 12: Do not decide from a single stack; look for the pair of the side waiting for the loader lock and the side holding it while waiting.

Conditions such as “occasionally at startup”, “only on a particular machine”, or “only when run as a service” are clues as well. The mutual wait forms when a DLL load coincides with a thread start or exit, so environment differences and execution timing change how it surfaces.

7.2 Prevent It With Application Verifier and Callee Review

Running tests with Application Verifier enabled detects the typical DllMain mistakes at run time.¹ In C++/CLI, do not ignore warning C4747, and check the indirect paths the warning cannot detect from the perspective of Section 4.2.

In review, look for functions that call LoadLibrary indirectly among the work reachable from DllMain. COM initialization, some CRT features, and delay-load imports are things to check. In particular, it is easy to overlook that the first call to a delay-loaded import function becomes a LoadLibrary internally. Even if the function name lives outside DllMain, as long as the caller is DllMain, the restriction remains.

8. Summary — Look Not at Function Names but at “When, and Under Which Lock, It Runs”

The DllMain restrictions can all be understood from one point: it is called while holding the process-wide loader lock. Not only your own DllMain but also the CRT’s static initialization and termination and C++/CLI’s indirect calls fall within the same scope.

Start a review by asking whether initialization can be made static and whether the rest can be deferred until after the load completes. Check all the way down to the first access of the deferred work, and if notifications are unnecessary, consider DisableThreadLibraryCalls after checking the static CRT and static TLS conditions.

On the shutdown side, separate a DLL-only unload from a whole-process exit. If the DLL owns a worker, follow the protocol of signal, consistency check, and termination, and where possible move thread ownership to the EXE side. Bring DllMain at process exit close to empty, and put data saving in the application’s own shutdown code.

flowchart TB
    accTitle: The order for reviewing DllMain and what it calls
    accDescr: Examine the scope including not only DllMain but static initialization and indirect calls, move initialization to static or after-load, design stopping and cleanup according to the shutdown reason, then confirm with Application Verifier and dumps
    scope["DllMain, static initialization, and callees"] --> timing["Move initialization to static or after-load"]
    timing --> first["Also check the first access of deferred work"]
    first --> shutdown["Design cleanup per shutdown reason"]
    shutdown --> verify["Confirm with Verifier, warnings, and dumps"]

Figure 13: Tracking not only what initialization does but when it runs and its lifetime at shutdown lets you treat the prohibitions as a single design policy.

The question to ask at a borderline case is “is this work acceptable to run while holding the loader lock?” Not cramming questionable initialization into DllMain, and changing when it runs instead, is the starting point of a safe DLL design.

Related Articles

• How Windows DLL Name Resolution Works - Search Order and SxS
• Calling Native DLLs from C#: C++/CLI Wrapper vs P/Invoke
• Practical Multithreading Best Practices: C++ Edition
• Spurious Wakeups — Why Condition Variables Wake “Without Being Notified” and How to Wait Correctly on Windows
• Reading Crash Dumps with WinDbg + SOS — A Practical Guide to Analysis After Collection
• COM STA/MTA Fundamentals - Threading Models and How to Avoid Hangs

Related Consulting Areas

KomuraSoft LLC handles root-cause investigation (dump analysis) of hangs and deadlocks at startup or DLL load time, design reviews around DllMain and static initialization, and reworking C++/CLI wrappers and plug-in DLLs toward a safe initialization design. You are welcome to consult us even at the hard-to-reproduce stage of “startup freezes only in a particular environment”.

• Bug Investigation and Root-Cause Analysis
• Technical Consulting and Design Review
• Windows Application Development
• Contact Us

References

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

Can you really do nothing at all in DllMain?

"Do nothing" is not an exaggeration; it is the official design policy, and Microsoft itself says the ideal DllMain is a near-empty stub. What is safe is limited to the functions in Kernel32.dll, which is guaranteed to be loaded by the time DllMain runs, that do not load other DLLs. For example, you can create critical sections and mutexes and use TLS. Conversely, LoadLibrary/FreeLibrary, synchronization with other threads, and calls into User32, Shell, COM, and the like are forbidden because they cause deadlocks and access violations. For initialization you are unsure about, the right answer is not to do it in DllMain but to defer it until the first time it is used.

Do the constructors of C++ global variables (static objects) also fall under the DllMain restrictions?

They do. When the DLL is linked with the CRT (the C++ runtime), the constructors and destructors of global and static objects run through the entry point the CRT provides, effectively as part of DllMain. That means calling LoadLibrary in a constructor, starting another thread and waiting for it to finish, initializing COM, and so on all carry the same danger as doing them in DllMain. For global objects with complex initialization, shift the execution timing outside DllMain: keep a pointer and create the object on first access, or use a function-local static.

Should I call DisableThreadLibraryCalls?

It is useful under conditions. If the DLL does not need DLL_THREAD_ATTACH/DETACH notifications, calling DisableThreadLibraryCalls in DLL_PROCESS_ATTACH stops the notification on every thread creation and destruction and reduces overhead in a process that creates threads frequently. There are two exceptions, however. Do not call it in a DLL linked with the static CRT (the static CRT needs the thread notifications). And when static TLS via thread_local or __declspec(thread) is in effect, the call itself fails and returns FALSE, so make a habit of checking the return value. Use it in a typical DLL with the dynamically linked CRT, after confirming that nothing depends on the thread notifications.

Why does a C++/CLI (mixed managed) DLL hang at startup?

The typical cause is an attempt to execute MSIL (managed code) while the loader lock is held. In a C++/CLI mixed assembly, if DllMain, the functions it calls, or the dynamic initializers of global variables are compiled to MSIL, CLR initialization or the load of another assembly becomes necessary under the loader lock, and that can deadlock. The compiler emits warning C4747 when DllMain tries to execute MSIL directly, but it cannot detect indirect execution through another module. The remedy is to compile DllMain and its call tree as native code with #pragma unmanaged, or not to have a DllMain at all.

May I clean up resources in DLL_PROCESS_DETACH?

The answer differs between "process exit" and "unload via FreeLibrary". In DLL_PROCESS_DETACH at process exit, the other threads have already been forcibly terminated and there is no guarantee that the address space is consistent, so cleanup such as freeing memory is actually dangerous, and the official guidance is that "the ideal handler is empty". Write out data that needs persisting in the application's own shutdown code, and in the handler basically do nothing and return. On an unload via FreeLibrary, by contrast, the process keeps running, so complete cleanup, such as stopping threads and closing handles, is required. Waiting for a thread to exit inside DllMain deadlocks, however, so you have to follow the protocol the official documentation describes: signal, wait until a consistent state, and do the final work outside DllMain.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.