Last Updated on September 12, 2022

You can check the number of remaining tasks in the ThreadPoolExecutor by the size of the _work_queue protected member.

In this tutorial, you will discover how to check the number of remaining tasks in the ThreadPoolExecutor.

Let’s get started.

Need to Check the Number of Remaining Tasks

The ThreadPoolExecutor provides a flexible way to execute ad hoc tasks using a pool of worker threads.

You can submit tasks to the thread pool by calling the submit() function and passing in the name of the function you wish to execute on another thread.

Calling the submit() function will return a Future object that allows you to check on the status of the task and get the result from the task once it completes.

We may need to check the number of remaining tasks in the ThreadPoolExecutor.

This may be for many reasons, such as submitting tasks and not retaining or having access to the associated Future objects.

How can we check the number of tasks that remain in the ThreadPoolExecutor?

How to Check the Number of Tasks Remaining in the ThreadPoolExecutor

There are a number of ways that we can check the number of tasks that remain in the ThreadPoolExecutor.

One approach is to report the number of pending tasks. That is, tasks that have been submitted but have not started executing.

This can be achieved by checking the size of the _work_queue protected member of the ThreadPoolExecutor class.

This is an instance of the SimpleQueue class and we can check the number of items in the queue via the qsize() function.

For example:

You can learn more about thread-safe queues and the SimpleQueue class here:

• queue — A synchronized queue class

This value in addition to the number of worker threads in the thread pool will give a reasonable approximation of the number of remaining tasks.

If we know how many tasks were submitted to the thread pool, we can also check the number of remaining tasks by counting the number of tasks that have been completed.

One approach would be to collect all of the Future objects for the tasks in the thread pool, then use as_completed() in a for loop and update a counter as each task is done.

For example:

A similar approach to this would be to update and report the number of remaining tasks using a done callback for each Future.

This can be achieved by defining a function that takes a Future object and adding it to the Future object for each task shortly after they are submitted by calling the add_done_callback() function.

You can learn more about adding callback functions here:

• How to Add a Callbacks to the ThreadPoolExecutor in Python

The callback function can update a counter for the number of completed tasks and then report the number of tasks that remain. A lock is required as the callback function is called by the worker thread for the task and may be called concurrently by multiple worker threads.

An example of a callback function to check and report the number of remaining tasks is listed below.

This function can be registered on Future objects as follows:

The downside of these last two approaches is that it requires that you know how many tasks were submitted to the thread pool and it requires that you store and have access to the Future object for each submitted task.

Now that we know how to check the number of remaining tasks in the thread pool, let’s look at some worked examples.

Example of Checking the Number of Remaining Tasks Using Queue Size

Let’s explore how we can report the number of remaining tasks using the size of the queue within the ThreadPoolExecutor.

Firstly, let’s define a mock task that will sleep for a moment.

Next, we can create a thread pool with four worker threads and submit 50 tasks.

In this example, we want to report an estimate of the number of remaining tasks frequently. One approach is to report the number of remaining tasks as each task in the pool is completed.

This can be achieved by passing a list of all Future objects to the as_completed() function.

Each iteration, we can then access the _work_queue member of the ThreadPoolExecutor class and report the size of this queue via the qsize() function.

This will report the total number of tasks that are queued up and ready for execution. If we add the number of worker threads in the pool to this number, we will get a rough estimate of the number of remaining tasks.

Tying this together, the complete example of checking and reporting the number of remaining tasks in the thread pool is listed below.

Running the example creates the thread pool and submits the tasks as per normal.

Then, as tasks are completed, the count of the number of remaining tasks is reported.

We can see that the results are quite reasonable until the queue of tasks is empty, and then the estimate is fixed at a value of four. We could fix this by reporting something like “four or fewer tasks remain” at this point.

We might not have access to the Future objects for tasks submitted to the thread pool.

In this case, we can spin and check the _work_queue each iteration until the queue of tasks is empty.

For example:

This is not ideal as the main thread will perform unnecessary computation, but it will provide a simple way of checking and reporting the progress of the thread pool without access to the Future objects.

Tying this together, the complete example is listed below.

Running the example creates the thread pool and submits the fifty tasks as before.

We can see that this approach will report the same number of tasks occasionally and skip over numbers in the count as it is operating based on a sleep timer rather than responding to the actual completion of tasks in the pool.

Example of Checking the Number of Remaining Tasks With a Count

A simpler approach to checking and reporting the number of remaining tasks is to simply count.

This requires both access to the Future objects in order to update the count as tasks finish, and to record the number of tasks that were submitted in the first place.

First, we can define a constant that specifies the number of tasks that will be submitted.

Next, we can define a variable that will keep track of the number of tasks that have been completed.

Finally, we can use the as_completed() function to iterate Future objects as tasks are completed and update the count and report the current number of tasks that remain.

Tying this together, the complete example of using a count in the main thread to report the number of remaining tasks in the thread pool is listed below.

Running the example creates the thread pool and submits fifty tasks.

As tasks are completed, the count of completed tasks is updated and we are able to report an accurate estimate of the number of tasks that remain.

This is a reliable approach but does require access to the Future objects and the count of tasks that were submitted.

Example of Checking the Number of Remaining Tasks With a Callback

Another approach to checking and reporting the number of remaining tasks is to use a done callback.

This requires that we know how many tasks were submitted, but does not require the Future objects, beyond registering the callback.

As before, we must define the total number of tasks that were submitted. In this case, we will use a global constant.

Next, we need to define a count variable for the number of tasks that were completed and a mutual exclusion lock.

A Lock is needed to update the count of completed tasks in the callback. This is because the callback function will increment the count and can be accessed concurrently by the worker thread in the thread pool that is executing the callback function.

The Lock protects the critical section of updating the count by ensuring only one thread can execute the block at the same time.

Next, we can define our callback function.

The function will need access to the count of completed tasks and the lock, both of which are global variables.

The function can then acquire the lock using the context manager, a preferred approach so that we don’t have to explicitly call acquire() and release() on the lock.

Once we have the lock, the function can update the count and report the current progress in terms of the number of remaining tasks.

The complete callback function is listed below.

Next, all that remains is to register the callback function on the Future object for each submitted task.

This can be achieved by calling the add_done_callback() function and specifying the callback function name.

And that’s it.

Tying this together, the complete example of checking and reporting the number of remaining tasks in the ThreadPoolExecutor using a callback is listed below.

Running the example creates the thread pool and submits the tasks as before.

The progress is then reported as each task is completed, providing an accurate estimate of the number of remaining tasks without access to the Future objects in the main thread.

Further Reading

This section provides additional resources that you may find helpful.

Books

• ThreadPoolExecutor Jump-Start, Jason Brownlee, (my book!)
• Concurrent Futures API Interview Questions
• ThreadPoolExecutor Class API Cheat Sheet

I also recommend specific chapters from the following books:

• Effective Python, Brett Slatkin, 2019.
  • See Chapter 7: Concurrency and Parallelism
• Python in a Nutshell, Alex Martelli, et al., 2017.
  • See: Chapter: 14: Threads and Processes

Guides

• Python ThreadPoolExecutor: The Complete Guide
• Python ProcessPoolExecutor: The Complete Guide
• Python Threading: The Complete Guide
• Python ThreadPool: The Complete Guide

APIs

• concurrent.futures - Launching parallel tasks
• threading — Thread-based parallelism

References

• Thread (computing), Wikipedia.
• Futures and promises, Wikipedia.
• Thread pool, Wikipedia.

Takeaways

You now know how to check the number of tasks remaining in the ThreadPoolExecutor.

Do you have any questions about how to check the number of remaining tasks?
Ask your questions in the comments below and I will do my best to answer.

Photo by Zoltan Tasi on Unsplash