Last Updated on September 12, 2022

You can execute tasks asynchronously with the ThreadPoolExecutor by calling the map() function.

In this tutorial, you will discover how to use the map() function to execute tasks with the thread pool in Python.

Let’s get started.

Need to Call Functions in Separate Threads

You may have a for loop that calls a function for each item in an iterable like a list.

How can you make each function call in a separate thread?

Or put another way:

How can you make the for-loop concurrent?

Alternatively, you may be using the built-in map() function to apply the function to each item in an iterable for you.

You can learn more about the built-in functions here:

• Python Built-in Functions

This does not perform the task() function to each item until we iterate the results, so-called lazy evaluation:

Therefore, it is common to see this operation consolidated to the following:

How can you execute each call by map() with threads?

How to Apply a Function to an Iterable in Separate Threads

The ThreadPoolExecutor in Python provides a pool of reusable threads for executing ad hoc tasks.

You can specify the number of threads to create in the thread pool as an argument, which does not have to be related to the number of CPUs or CPU cores in your system.

You can also submit tasks by calling the map() function and specifying the name of the function to execute and the iterable of items to which your function will be applied.

Each call to the target function with one item from the iterable will be executed in a separate thread.

You can then iterate over the results as we would with map(), except we may have to wait for the results as the tasks complete in separate threads. This waiting is called “blocking” and happens automatically.

Although the tasks are executed concurrently, the results are iterated in the order of the iterable provided to the map() function, the same as the built-in map() function.

In this way, we can think of the thread pool version of map() as a concurrent version of the map() function and is ideal if you are looking to update your for loop to use threads.

We can call the map() function to execute the functions in separate threads and process the results using the common for-loop idiom, as follows:

The map() function also takes a chunksize argument, but this has no effect with the ThreadPoolExecutor and can be safely ignored.

How to Wait for Results With Timeout

We may want to limit how long we are willing to wait for a task to complete and return a result when iterating results.

This can be achieved by setting the timeout argument when calling map() and specifying how long we are willing to wait in seconds.

If more than the timeout number of seconds elapses before a task completes and returns a result, then a TimeoutError is raised that may need to be handled.

How to Wait for All Results to Complete

We don’t have to wait for the results from the call to the map() function in order to continue.

For example, we can call map() with a target task function and an iterable and then carry on with other operations.

The call to map() does not block, meaning that we do not have to wait for the results unless we iterate the results returned from the call to the map() explicitly.

This might be helpful if our target task function does not return a result, although you may want to use the submit() function on the ThreadPoolExecutor instead.

Alternatively, we may want the map() function to call the target function in separate threads and wait for all tasks to complete.

This can be achieved by calling the shutdown() function of the ThreadPoolExecutor, which, by default, will wait for all scheduled and running tasks to complete before returning.

Alternately, we use the context manager of the thread pool that will automatically shut down the thread pool for us when we are finished and will block until all tasks have completed.

How to Call map() With Multiple Arguments

The ThreadPoolExecutor map() function supports target functions that take more than one argument by providing more than one iterable as arguments to the call to map().

For example, we can define a target function for map that takes two arguments, then provide two iterables to the call to map(). The map() function will then apply the function with both sets of arguments and stop when the shortest iterable is exhausted.

If you want to provide ad hoc arguments to your target task function, e.g. variable numbers of arguments or the same argument to multiple function calls, then you may be better off using the submit() function on the ThreadPoolExecutor.

Now that we are familiar with how to use map() function to call a function using threads in Python, let’s look at a worked example.

Example of Using map() With the ThreadPoolExecutor

Let’s explore how to use the map() function on the ThreadPoolExecutor with a worked example.

First, we can define a simple task that will sleep for a variable amount of time less than one second.

The task takes a unique name and will return a message that it has completed.

This task is a good candidate for calling the built-in map() function and the ThreadPoolExecutor map() function because it is a pure function that does not have any side effects and does not access or change state outside of the function itself.

Next, we can define a thread pool with ten worker threads using the context manager.

Next, we can call the map() function to apply the task() function to a range of integers from 0 to 9.

Finally, we can report the results as they are made available in the order that the tasks were submitted to the thread pool for execution.

Tying this together, the complete example of calling map() to apply a function to a range of data using worker threads in the ThreadPoolExecutor is listed below.

Running the example first creates the thread pool, then submits the tasks to the thread pool for execution.

The tasks are completed and results are retrieved and reported as they become available in the order that tasks were submitted.

Example of Using map() With a Time Limit

We may want the results from the function calls, but are unwilling to wait an extended period.

This can be achieved by setting the timeout argument when calling the map() function.

As we process the results by iterating the value returned from the calling map, if a task takes more than the timeout to return a value, then a TimeoutError is raised, which we can choose to handle.

The list below updates the example to wait a timeout of a tiny fraction of a second, and if the timeout elapses, a message is reported.

Running the example starts the thread pool, then submits ten function call tasks to the pool.

We wait a fraction of a second for the first result before a TimeoutError is raised and caught, reporting a message that we gave up waiting.

Note that if a TimeoutError is raised, it does not impact the tasks that already exist in the thread pool. For example, although we were impatient for a result, the tasks will continue to run and the thread pool will not close until all tasks have completed.

Example of Using map () and Waiting for All Tasks to Complete

We may have a target task function that does not return a value, and yet we may want to call the function for an iterable of data and wait for all tasks to complete.

We can do this by calling map, not iterating the results and using the context manager to close the thread pool, which will wait for all tasks to complete.

First, let’s update our target task function to not return a value, but instead report a value directly via a print statement.

We can then submit the tasks to the thread pool via a call to map() without iterating the results.

The call to map() does not block, so we are able to carry on with other tasks in our program.

We can then wait for all tasks in the thread pool to complete by allowing the context manager to call shutdown() for us and return once all tasks have finished.

To make this clear, we will add a print statement that we are waiting for tasks to complete.

Once all tasks have completed, we can carry on without a program.

Tying this together, the complete example of waiting for all map() tasks to complete in the ThreadPoolExecutor is listed below.

Running the example starts the thread pool and submits five tasks by calling the map() function.

We do not iterate the results of the tasks; instead, we start waiting for the tasks to complete immediately with an implicit call to shutdown() by the context manager.

The tasks complete one by one and we then carry on with our program once all tasks have completed.

Example of Using map() With Multiple Arguments

We may want to call a target task function that takes more than one argument.

This can be done with the built-in map() function and with the ThreadPoolExecutor map() function.

Both map() functions take one or more iterables and the map function will stop calling the target task function with values from each iterable when the shortest iterable is exhausted.

We can update our target task function to take two values and to return a tuple that combines the values after a short sleep.

We can define two lists of data that we will use as iterables for our call to map.

Finally, we can update our call to map() to take both iterables of data.

Tying this together, the complete example of calling map to execute function calls with two arguments asynchronously with the ThreadPoolExecutor is listed below.

Running the example first starts the thread pool, then submits three function calls to the worker threads, one for each pair of values in the two iterables passed to map.

Each task returns a tuple that is printed.

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 use the map() function to execute tasks asynchronously with the ThreadPoolExecutor.

Do you have any questions about how to use the map() function?
Ask your questions in the comments below and I will do my best to answer.

Photo by David Marcu on Unsplash