Here is a link to the official channel 9 recording of the talk:  

• https://channel9.msdn.com/Events/Build/2013/3-108   
• Abstract: The apps that run on a device are one of the biggest factors that determine its battery
  life. With this in mind, we designed the Windows app lifecycle for maximum
  battery life. But that doesn’t mean the app model precludes background
  activities. This talk explains the background scenarios supported in Windows
  and shows you how to write background tasks. It also covers best practices for
  authoring background tasks so that the connected standby lifetime of the device
  doesn’t suffer.

Enjoy.

• Being productive when your app is offscreen
• Being productive in the background – background tasks

Enjoy.

So how does a programmer distinguish between being because the process is exiting or because the DLL is being freed? Actually before we go there, does it even matter to distinguish between these two cases? The answer is yes, it matters a whole lot. When the process is exiting and your DLL receives the DLL_PROCESS_DETACH callout, the other threads in the process might have already exited, so if you try to do some synchronization here that might not work. Or think of the situation where you have created a ginormous memory block in your DLL_PROCESS_ATTACH and free it in your DETACH callout. The process is already exiting; technically you don’t need to clean up your resources because the OS will do it for you, so why do unnecessary work? Note: Heap operations are considered suspect in DllMains because of the process-wide LoaderLock around DllMains.

With that said going back to the original question, how do you distinguish between process exit and FreeLibrary? This is mentioned in the DllMain documentation but its not very prominent so I am including the relevant parts here:

From MSDN: http://msdn.microsoft.com/en-us/library/ms682583(VS.85).aspx

When handling DLL_PROCESS_DETACH, a DLL should free resources such as heap memory only if the DLL is being unloaded dynamically (the lpReserved parameter is NULL). If the process is terminating (the lpvReserved parameter is non-NULL), all threads in the process except the current thread either have exited already or have been explicitly terminated by a call to the ExitProcess function, which might leave some process resources such as heaps in an inconsistent state. In this case, it is not safe for the DLL to clean up the resources. Instead, the DLL should allow the operating system to reclaim the memory.

Example Usage:

And that’s how easy it is to detect the process is exiting in your DllMain. Now if you ever close a process and you see that Windows is taking some time to close it, you know what the DLLs in the process are not doing.

The DllMain is an optional entry point into a dynamic link library (DLL) which is called by the system when the DLL is first loaded into a process or when it is unloaded from a process. Think of it as a constructor and destructor of the DLL. In addition, each DLL’s entry point is also called when the system starts or terminates a thread within a process with the appropriate reason. This tip is with regards to the thread attach callouts.

From MSDN documentation:

Let’s examine the default case where all DLLs receive these thread attach callouts:

• Let’s say you have a process with a 50 DLLs loaded in its memory and the process creates a new thread. In the default case, the system will have to send the DLL_THREAD_ATTACH callout to each of the 50 DLLs.
• It’s possible that for some of those DLLs, their DllMain code has been paged out from memory. So, when a thread is created you would now have to pay the cost to page in their DllMain code.
• And if it turns out that your DllMain is not interested in the DLL_THREAD_* reason and falls through the switch statement, then it was called unnecessarily.

This is an unnecessary overhead. I have seen only a few instances of DLLs having a genuine reason to track when a thread is created in the process space. Majority of the DLLs don’t need to know when a thread is created or terminated in the process. Also, note the remark in the above table for DLL_THREAD_ATTACH, you will not receive the callout for any threads created before the DLL is dynamically loaded. This implies you will not be able to accurately track the number of threads in a process using this technique. 

DisableThreadLibraryCalls

To avoid receiving these thread attach/detach callouts for your DLLs, you can call DisableThreadLibraryCalls in your DllMain.

http://msdn.microsoft.com/en-us/library/ms682579(VS.85).aspx

Example Usage:

And that’s it, your DLL will no longer will receive the thread attach/detach callouts.

This is a quick recap of all the posts in the threadpool series and the methods supported by the wrapper classes.

• Introduction to the Windows Threadpool (Part 1)
• Threadpool Work item priority
• Introduction to the Windows Threadpool (part 2)
• Threadpool Timer Functions
• Waiting on Events from within Threadpool

Class windowsthreadpool::SimpleThreadPool

Class windowsthreadpool::PrivateThreadPool

Class windowsthreadpool::Timer

Download source code from MSDN Code Gallery.  

Till now we have seen how to use the default process-wide threadpool to submit work items, how to create your own private threadpool and how to create timer objects to execute callbacks when the timer fires. In this post (final one in the threadpool series), we will see how to create waiter objects so that you can run your callback code when an event fires.

Both the windowsthreadpool::SimpleThreadPool and windowsthreadpool::PrivateThreadPool class support the following member functions to support events; RegisterEvent, ReRegisterEvent and DestroyEvent. To wait on an event, you need to call RegisterEvent; once that event fires, you need to call ReRegisterEvent to wait on it again. DestroyEvent closes the wait object in the threadpool so that you no longer wait on that event.

Example Code:

In this example, we create an event and register interest in the event by queuing a work item to the process-wide threadpool along with a pointer to our callback (HelloWorld). When the event is set, the callback “HelloWorld” executes. A different callback (HelloWorld2) is registered with the private threadpool for the same event. This callback will run twice.

The RegisterEvent method takes in a function pointer to the callback function, an event handle and a timeout value. If the timeout is -1, then it waits indefinitely for the event. The RegisterEvent method returns an opaque handle which is passed as input to the DestroyEvent and ReRegisterEvent methods. Once a raised event is handled in the callback, you need to re-register interest in the event for the threadpool to call your callback again.

The majority of the work for these methods is happening in the internal class WaitCallBack. When you register an event, it first creates TP_WAIT object by calling CreateThreadpoolWait using the same environment block for all work items queued via the same threadpool. It then passes this wait object along with the event handle and a timeout value to SetThreadpoolWait. If a user wants to wait indefinitely for the event to fire, then you need to pass NULL as the timeout value to SetThreadpoolWait.

The ReRegisterEvent method simply calls the SetThreadpoolWait as shown above.

The DestroyEvent method indicates that you are no longer interested in this event. Remember back in the first post I mentioned that if you call CloseThreadpoolCleanupGroupMembers, it allows you to free all work objects, wait objects and timers associated with the cleanup group in one call. So that’s why in the DestroyEvent method, we check if WaitForAll has already been called (which would imply the wait object is already freed) and if not then call the internal DestroyEvent method.

And that’s it! Over the course of this series on threadpool we have learnt how to queue work items to the default process-wide threadpool, create your own private threadpool, queue work items to it, create a background threadpool which runs low priority work items, create timer objects and wait on events to run code when the events are signaled.

The only functionality that’s not covered in this series is using the threadpool to perform asynchronous IO.  Maybe I will cover that in a later series. In the meantime, if you have any questions on the win32 threadpool, please leave a comment and I will try to get it answered.

Download source code from MSDN Code Gallery.

The threadpool provides timer functionality with the SetThreadpoolTimer and CreateThreadpoolTimer functions; the ability to call your functions at specified times.  In this blog post I will show how to use the wrapper windowsthreadpool::Timer class provided to obtain timer functionality by using these APIs.  

Example code:

The function “Hello” will be called a 1000 milliseconds from now and from then on will repeatedly be called every 1000 milliseconds until the timer is destroyed by calling “delete t”. Since there is a Sleep(10000) before the delete call, the function “Hello” will be called ten times.

The timer class has four constructors which let you create timer objects and when the object goes out of scope the timer is destroyed or you can explicitly call DestroyTimer method to cancel the timer. The timer class accepts THREADPOOLCALLBACK as the template type; this type is defined as a function pointer accepting a PVOID as a parameter and returning nothing.  The timer class needs this definition because it needs to know the function signature of the callback method (Hello).

The timer constructor accepts the starting time in milliseconds for the timer to expire, a period in milliseconds if the timer is expected to fire periodically, a function pointer to the callback and a pointer to the parameter if required. If the period is zero, the timer is a one-time timer and will fire only once.

To close the timer you can explicitly call DestroyTimer() or if the timer goes out of scope, then its destructor will close the timer object. To close a timer in the threadpool, you have to call SetThreadpoolTimer with the pftDueTime parameter set to NULL and the msPeriod and msWindowLength parameters set to 0. The timer object is then closed with CloseThreadpoolTimer.

The timer class uses the TimerCallback class internally to create timer objects in the default process-wide threadpool, set the appropriate time and period and destroy the timer object when it goes out of scope.

Notice the ACCEPTABLELAG parameter to the SetThreadpoolTimer call. The last parameter is the amount of time that you can wait for this timer to fire once it expires. ACCEPTABLELAG is defined in timer.h.

Example: If you have two timers set within a process, one fires after 100milliseconds and another fires after 110milliseconds. Windows will now have to set off the first timer and 10mSecs later set off the next timer. However, if the first timer had set the last parameter to 20milliseconds which means it’s acceptable for the timer to fire as late as 120milliseconds from now, than Windows would only need to do work once. At time 110milliseconds from now, Windows will fire both the timers and both callbacks will run. This is generally known as timer coalescing and is useful for Windows to prevent unnecessary timers from firing and decreasing battery life. More information about timer coalescing available here.

Next up, how to call functions when events are fired…

Download source code from MSDN Code Gallery.

In the previous posts, I talked about using the windowsthreadpool::SimpleThreadPool class to queue work items to the process-wide threadpool and queuing work items with different priorities.  In this post, I will show how to create your own private threadpool using the class windowsthreadpool::PrivateThreadPool.

Private Threadpool

The private threadpool allows a developer to have their own pool and control work items that are queued to the threadpool. In addition, having a private threadpool also allows the developer to control the maximum and minimum of threads the threadpool can create.

To create a private threadpool, you need to call CreateThreadpool which returns a handle to the pool object, which is done in the constructor of the class PrivateThreadPool. The private pool is closed in the destructor by calling CloseThreadpool.

You queue work items to the private threadpool using the same methods (QueueUserWorkItem) as the simple threadpool class and wait for the work items to finish using the same WaitForAll. Because we are using a private threadpool, we need to associate our callback environment block with our private threadpool, so that all work items submitted using this environment block are submitted to the private threadpool. This is done in the InitializeInfra method by calling the function SetThreadpoolCallbackPool.

Submitting work items to a private threadpool requires using function SubmitThreadpoolWork. This function takes in a pointer to a TP_WORK object which is created with the CreateThreadpoolWork function. The work is submitted using an internal helper class WorkCallBack which is similar to the helper class SimpleThreadPool uses except in this it uses SubmitThreadpoolwork to submit work items. The WorkCallBack instance is destroyed in the callback method after the user callback runs. 

The private threadpool supports two operations that are not supported by the default process wide threadpool, setting the maximum and minimum number of threads that the threadpool can create. It should be pretty obvious why these operations are not supported on the default process-wide threadpool; the process-wide threadpool is also used by the system to execute its work items, so you don’t want the developer to set arbitrary limits on this threadpool and accidentally impact system performance. If you are creating your own private threadpool, you shouldn’t have to set the maximum and minimum number of threads; the system is capable of managing thread lifetimes on its own and unless you really notice some problem don’t have to change these settings.

As mentioned in the previous post, if you have low priority work items, instead of modifying the thread’s priority in the callback, you should use a private threadpool. In the example below I am creating a background threadpool which can have a maximum of only one thread. So at any given time only one work item can execute. And if there are no more work items to execute the threadpool will kill that thread as well as determined by its internal heuristics.

Example Code:

And that’s it, your own private threadpool. As the private threadpool only has one thread, each work item executes serially, so technically we don’t need to queue with low priority, the same behavior can be obtained by just queuing normally.

Since this is a private threadpool to run background work items, if you really want you could even modify the thread priority in the work item. However, note that if you do modify the thread priority in the work item, the priority needs to be reset back to the original value before the work item returns.

Next up; creating a timer class using the win32 threadpool functions...

In the previous post, I talked about how to queue work items to the process-wide system threadpool using TrySubmitThreadpoolCallback. In this post, I will talk about work item priority and how to queue low priority work items. 

The thread that your work item executes is not owned by your application; it’s owned and managed by the system. That implies the application should not modify the state because it has no visibility into other work items that might be scheduled to run on this thread. Depending on how the state was modified, other work items may not react well.

One of the most common ways developers modify thread state is by lowering the thread priority in the work item. This is a no-no and has unintended consequences, even if you reset the thread’s priority before returning from your work item.

Here’s why: In Windows 7, the threadpool uses something called a concurrency control to control the number of concurrently running threads. This number is typically equal to the number of cores on the machine; if a machine has two cores, then the threadpool will have a concurrency control number of 2. This seems quite logical, if you have two cores, only two threads can execute code. Note: If a work item blocks for any reason, then a new thread is created by the threadpool to execute other work items so all cores stay busy.

However, if the work item lowers the priority of the thread below normal and there is another normal priority thread in the system which is ready to run, then the Windows scheduler schedules the normal priority thread and preempts the lower priority threadpool work item thread. This is bad because the threadpool sees that the thread whose priority has been lowered is still in a ready state. A thread in ready state counts towards your concurrently running threads, because technically it could run as soon as it is scheduled. Therefore, the threadpool thinks it has two running threads in the system. However, only one thread is actually running, so work items in the threadpool will get starved. This is especially egregious when it happens in the shared process-wide threadpool which has system work items, because it could impact system-wide performance.

Note: if you increase the thread priority in the callback, then it may not starve the other work items the same way as theoretically the callback should now finish quicker. However, this is still not recommended especially if you are in the process-wide system threadpool as the thread is not yours to modify. Plus if everyone decides to boost their priority this way then work items will be starved and the system performance will be impacted.

This is not a theoretical concern and is quite real based on our experience. If you have any work items that need to execute at lower priority, there are two alternatives:

1. Create your own private threadpool which services only your work items and set their priorities as needed.  If these work items are starved or executed slowly the Windows system is not affected. Later in the series I will show how to use the wrapper class windowsthreadpool::PrivateThreadPool to do exactly this.
2. Use the threadpool function SetThreadpoolCallbackPriority to set the priority on a work item. This function does not modify thread priorities; instead it uses separate queues for low, high and normal priority work items. The MSDN documentation hints at this:

The QueueUserWorkItemWithHiPri and QueueUserWorkItemWithLowPri methods in the SimpleThreadPool class use the SetThreadpoolCallbackPriority function to change work item priority. We create a new environment structure, initialize the structure, set the appropriate priority and associate it with our cleanup group so that we can wait on the work items using the WaitForAll method.

Next up, how to create your own private threadpool…