Understanding the rationale behind a rule when trying to circumvent it
Summary
This article from Microsoft's Old New Thing blog explains the rationale behind best practices for Windows kernel callback functions, particularly why blocking or waiting on work items defeats their purpose, using a cautionary tale about drivers causing system hangs.
<p>In the documentation for <a href="https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/windows-kernel-mode-process-and-thread-manager#best-practices-for-implementing-process-and-thread-related-callback-functions"> best practices for implementing process and thread-related callback functions</a>, it calls out</p>
<blockquote class="q">
<ul>
<li>Keep routines short and simple.</li>
<li>Don’t make calls into a user mode service to validate the process, thread, or image.</li>
<li>Don’t make registry calls.</li>
<li>Don’t make blocking and/or Interprocess Communication (IPC) function calls.</li>
<li>Don’t synchronize with other threads because it can lead to reentrancy deadlocks.</li>
</ul>
</blockquote>
<p>So far so good. It seems that these callback functions need to operate quickly and cannot block. These are callbacks that are invoked when a process starts or exits, when a thread starts or exits, when a DLL or EXE is loaded or unloaded, and various other low-level events.</p>
<p>The various prohibitions above suggest that these callouts are called during the process creation/termination sequence, so if you take a long time to deal with them, you are slowing down the entire system. And the rather extreme requirements, like “Don’t make registry calls,” suggest that they might even be called while the system holds internal locks.</p>
<p>The list of best practices continues:</p>
<blockquote class="q">
<ul>
<li>Use System Worker Threads to queue work especially work involving:
<ul>
<li>Slow APIs or APIs that call into other process.</li>
<li>Any blocking behavior that could interrupt threads in core services.</li>
</ul>
</li>
</ul>
</blockquote>
<p>Okay, so this is providing a suggestion on how you can offload expensive work to code running outside the callback. This once again highlights that the callback itself needs to be fast with minimal blocking.</p>
<p>My colleagues in enterprise support often run into cases where the reason for a system hang is a driver violating the rule that these callbacks must return quickly. For example, a common anti-pattern is a driver whose callback starts by following the guidance above to queue work to a System Worker Thread, but then they block until the work item completes.</p>
<p>This is a case of following the rules without understanding why the rules are there.</p>
<p>The rule is that the callback needs to be fast and return quickly. The driver followed the letter of the law by delegating the work to a System Worker Thread, and there’s no rule that says “Don’t wait for work items”, so they must have figured that this gave them a loophole for executing synchronous long-running work.</p>
<p>But the rules “Don’t make blocking and/or Interprocess Communication (IPC) function calls” and “Don’t synchronize with other threads because it can lead to reentrancy deadlocks” make it clear that you shouldn’t be blocking in your callback for extended periods of time. The “Don’t”s are just calling out some common ways that your callback can block.</p>
<p>And it looks like the documentation was updated in 2020 to call out this specific case:</p>
<blockquote>
<ul>
<li>If you use System Worker Threads, don’t wait on the work to complete. Doing so defeats the purpose of queuing the work to be completed asynchronously.</li>
</ul>
</blockquote>
<p>One could argue that this rule is already covered by the “Don’t synchronize with other threads” rule, but I guess the driver vendor interpreted it as “But I’m not synchronizing with another thread. I’m synchronizing on an event!” But of course, the event is set by another thread, so you are effectively synchronizing with another thread.</p>
<p>My colleague in enterprise support describes this as the “It wasn’t me, it was my brother” excuse. You are told by your parents not to turn on the television set, so you tell your brother to do it. Technically, you didn’t turn the television set on, but in effect, you did because your brother is acting under your instructions. (This is why contracts often contain wording like “may not disclose or cause to be disclosed,” so that you can’t say “No, I totally didn’t disclose it. I gave the information to Bob, and it was Bob who disclosed it!”)</p>
<p>The documentation should open with something like this:</p>
<blockquote class="q"><p>The callback function must perform its work quickly without blocking. If you need to do complex work or synchronize with other threads or processes, do the work asynchronously, such as by using System Worker Threads.</p></blockquote>
<p>And then it can give a list of examples of things that count as blocking.</p>
<blockquote class="q"><p>Some examples of blocking that is not allowed from the callback function:</p></blockquote>
<p>And then it can follow up with additional constraints.</p>
<blockquote class="q"><p>Furthermore, the callback function may not perform any of the following operations:</p></blockquote>
<p>The post <a href="https://devblogs.microsoft.com/oldnewthing/20260611-00/?p=112415">Understanding the rationale behind a rule when trying to circumvent it</a> appeared first on <a href="https://devblogs.microsoft.com/oldnewthing">The Old New Thing</a>.</p>
View Cached Full Text
Cached at: 06/12/26, 02:50 PM
# Understanding the rationale behind a rule when trying to circumvent it - The Old New Thing
Source: [https://devblogs.microsoft.com/oldnewthing/20260611-00?p=112415](https://devblogs.microsoft.com/oldnewthing/20260611-00?p=112415)
In the documentation for[best practices for implementing process and thread\-related callback functions](https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/windows-kernel-mode-process-and-thread-manager#best-practices-for-implementing-process-and-thread-related-callback-functions), it calls out
> - Keep routines short and simple\. - Don’t make calls into a user mode service to validate the process, thread, or image\. - Don’t make registry calls\. - Don’t make blocking and/or Interprocess Communication \(IPC\) function calls\. - Don’t synchronize with other threads because it can lead to reentrancy deadlocks\.
So far so good\. It seems that these callback functions need to operate quickly and cannot block\. These are callbacks that are invoked when a process starts or exits, when a thread starts or exits, when a DLL or EXE is loaded or unloaded, and various other low\-level events\.
The various prohibitions above suggest that these callouts are called during the process creation/termination sequence, so if you take a long time to deal with them, you are slowing down the entire system\. And the rather extreme requirements, like “Don’t make registry calls,” suggest that they might even be called while the system holds internal locks\.
The list of best practices continues:
> - Use System Worker Threads to queue work especially work involving:- Slow APIs or APIs that call into other process\. - Any blocking behavior that could interrupt threads in core services\.
Okay, so this is providing a suggestion on how you can offload expensive work to code running outside the callback\. This once again highlights that the callback itself needs to be fast with minimal blocking\.
My colleagues in enterprise support often run into cases where the reason for a system hang is a driver violating the rule that these callbacks must return quickly\. For example, a common anti\-pattern is a driver whose callback starts by following the guidance above to queue work to a System Worker Thread, but then they block until the work item completes\.
This is a case of following the rules without understanding why the rules are there\.
The rule is that the callback needs to be fast and return quickly\. The driver followed the letter of the law by delegating the work to a System Worker Thread, and there’s no rule that says “Don’t wait for work items”, so they must have figured that this gave them a loophole for executing synchronous long\-running work\.
But the rules “Don’t make blocking and/or Interprocess Communication \(IPC\) function calls” and “Don’t synchronize with other threads because it can lead to reentrancy deadlocks” make it clear that you shouldn’t be blocking in your callback for extended periods of time\. The “Don’t”s are just calling out some common ways that your callback can block\.
And it looks like the documentation was updated in 2020 to call out this specific case:
> - If you use System Worker Threads, don’t wait on the work to complete\. Doing so defeats the purpose of queuing the work to be completed asynchronously\.
One could argue that this rule is already covered by the “Don’t synchronize with other threads” rule, but I guess the driver vendor interpreted it as “But I’m not synchronizing with another thread\. I’m synchronizing on an event\!” But of course, the event is set by another thread, so you are effectively synchronizing with another thread\.
My colleague in enterprise support describes this as the “It wasn’t me, it was my brother” excuse\. You are told by your parents not to turn on the television set, so you tell your brother to do it\. Technically, you didn’t turn the television set on, but in effect, you did because your brother is acting under your instructions\. \(This is why contracts often contain wording like “may not disclose or cause to be disclosed,” so that you can’t say “No, I totally didn’t disclose it\. I gave the information to Bob, and it was Bob who disclosed it\!”\)
The documentation should open with something like this:
> The callback function must perform its work quickly without blocking\. If you need to do complex work or synchronize with other threads or processes, do the work asynchronously, such as by using System Worker Threads\.
And then it can give a list of examples of things that count as blocking\.
> Some examples of blocking that is not allowed from the callback function:
And then it can follow up with additional constraints\.
> Furthermore, the callback function may not perform any of the following operations:
### Category
### Topics
## Author
Raymond has been involved in the evolution of Windows for more than 30 years\. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie\-jeebies\. The Web site spawned a book, coincidentally also titled The Old New Thing \(Addison Wesley 2007\)\. He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information\.
Similar Articles
If C# and JavaScript lets me await a Windows Runtime asynchronous operation more than once, why not C++/WinRT?
Raymond Chen explains why C++/WinRT does not allow multiple awaits on asynchronous operations like C#, JavaScript, and Python do, citing the lack of a standard library task type and the principle of not paying for unused functionality.
Why not have changes in API behavior depend on the SDK you link against?
The article examines the pitfalls of altering API behavior depending on the linked SDK version, using Windows' CoInitializeSecurity as a case study. It discusses issues with DLL version mismatches and tail call optimization that complicate this approach.
The case of the hang when the user changed keyboard layouts
A debugging story about a Windows program hanging when the user changes keyboard layouts due to a background thread that created a window but wasn't pumping messages. The fix is to either pump messages or destroy the window.
All means are fair except solving the problem
A blog post describing how an industry veteran's code misuse warning caused critical workflows to fail, but instead of fixing the misuse, colleagues suggested various workarounds like adding more output handlers or suppressing warnings—highlighting the common engineering tendency to avoid solving root problems.
If you're just going to sit there doing nothing, at least do nothing correctly
This article from The Old New Thing explains the concept of making APIs 'inert'—do nothing in a way that avoids breaking existing apps—using examples like printing support on Xbox and retiring widget APIs.