Last Updated on September 12, 2022

You can make thread-safe calls to print() using a mutex lock such as threading.Lock.

In this tutorial you will discover how to make calls to print() thread-safe in Python.

Let’s get started.

Need Thread-Safe Print

A thread is a thread of execution in a computer program.

Every Python program has at least one thread of execution called the main thread. Both processes and threads are created and managed by the underlying operating system.

Sometimes we may need to create additional threads in our program in order to execute code concurrently.

Python provides the ability to create and manage new threads via the threading module and the threading.Thread class.

You can learn more about Python threads in the guide:

• Threading in Python: The Complete Guide

In concurrent programming, we may want to print statements to the command line (also called the terminal or command prompt) via the print() built-in function.

This may be for many reasons, such as:

• Primary output from the program for the user.
• Debugging print statements for threads.
• Reporting progress of tasks in threads.

Is calling print() from multiple threads thread-safe? If not, how can we make print thread-safe?

How to Thread-Safe Print

The print() function is a built-in function for printing a string on stdout and is not thread-safe.

The print() function takes a string message, or an object that can be converted to a string.

For example:

By default, messages are appended with a newline character ‘\n‘, although an alternate ending can be specified via the “end” argument.

An “end” value of None will not include a separator between messages, printing on the same line.

For example:

By default, messages are not flushed to stdout until an internal buffer is full. Messages can be forced to flush after each call, which can be achieved by setting the “flush” argument to True.

For example:

By default, it reports messages to stdout, although can be configured to output messages to any file via the “file” argument.

Recall that stdout refers to “standard out” or “standard output” which is the stream for output messages in the command line (also called terminal or command prompt).

Calls to print from multiple threads is not thread-safe and will likely result in the corruption of messages as threads are context switched.

In order to make the print() function thread-safe, it needs to be treated as a critical section and protected with a mutual exclusion (mutex) lock.

This can be achieved with an instance of the threading.Lock class.

First, an instance of the lock can be created.

The lock can then be shared with all threads that need to print.

Prior to printing, the thread must acquire the lock, call print, then release the lock.

For example:

Only one thread can hold the lock at a time. As only one thread can hold the lock, it means that only one thread can print at a time.

Other threads that attempt to acquire the lock while it is already acquired will automatically wait until the lock is available.

It is critical that the lock is released after it is no longer needed, to allow other threads to acquire it. Otherwise those threads waiting for the lock will never progress, resulting in a concurrency failure condition called a deadlock.

An easy way to acquire the lock and release it automatically is via the context manager interface for the threading.Lock class.

For example:

You can learn more about mutex locks in this tutorial:

• How to Use a Mutex Lock in Python

Next, let’s look at some worked examples of printing in a thread-safe manner.

Example of Thread-Unsafe Print

Before we look at examples of thread-safe calls to print(), let’s look at an example of how calling print from multiple threads is not thread-safe.

In this example we will create 1,000 threads, each of which will generate a random number between 0 and 1, block for that fraction of a second, then report the value by calling print(). The print statements will step on each other and will result in a corrupted stream of messages.

First, we will define a function that takes a unique integer for the task, generates a random number by calling random.random(), blocks by calling time.sleep() then reports the number by calling print() with a formatted string.

The task() function below implements this.

Next, in the main thread, we can create 1,000 instances of the threading.Thread class, each configured to call our task() function with a unique integer from 0 to 999.

We can do this in a list comprehension in order to create a list of threading.Thread objects.

We can then call the start() method on each thread to start their execution, and then wait for all threads to finish by calling the join() method.

We expect a race condition in the print statement as all 1,000 threads will attempt to print messages concurrently.

The result will be a corruption of the messages that are printed, rather than a clean one message per line.

Note, this is still a problem, even if we set the “flush” argument to True, requiring that the stream always flush messages.

Tying this together, the complete example of print being not thread-safe is listed below.

Running the example first creates the 1,000 threads and configures them to execute our task() function.

The threads are started and the main thread blocks until all threads are terminated.

Each thread generates a random number, blocks and reports its value.

The result is 1,000 messages printed concurrently to stdout.

A truncated example of the output is listed below.

Note, your specific results will differ each time the program is run due to the use of random numbers.

This demonstrates that print() function is not thread-safe.

Next, let’s look at how we can call print() in a thread-safe manner.

Example of Thread-Safe Print

We can update the example in the previous section to be thread-safe.

This can be achieved by creating a mutex lock and sharing among all threads that need to print. The task() function can then be updated so that the lock must be acquired prior to calling the print statement.

First, we can update the task() function to take a lock as an argument.

Next, we can update the call to print() to be protected by the lock using the context manager interface.

In the main thread, we can create an instance of the lock to be shared among all threads.

We can then pass the lock as an argument to each thread when it is configured.

Tying this together, the complete example of calling the print() function in a thread-safe manner is listed below.

First, a shared lock is created.

Running the example creates and configures 1,000 threads, passing the lock to each.

The main thread starts all the worker threads then waits for all threads to terminate.

Each thread generates its random number, blocks, then attempts to acquire the lock. Once acquired, the thread will report its message and then release the lock.

A truncated example of the output is listed below.

The result is a clean one message per line with no corruption of messages seen with the thread-unsafe version.

Note, your specific results will differ each time the program is run due to the use of random numbers.

Next, let’s look at an example of how we can print in a thread-safe manner using a dedicated thread.

Example of Dedicated Print Thread With Queue

Another approach to thread-safe printing is to use a single dedicated thread to perform all printing.

Because only one thread can call print(), it is guaranteed to be thread-safe.

This can be achieved by creating a queue shared among all threads that need to print. Threads can put messages on the queue. A dedicated thread for printing can be created that runs in the background and gets messages from the queue and calls print.

We can update the thread-unsafe version developed above to use this dedicated printing thread approach.

First, we can define a task function to be executed by the printing thread. This function will take the shared queue as an argument. It will loop forever and get messages from the queue by calling get() and report the messages by calling print().

The printer() function below implements this.

The printer thread will block until messages appear on the queue via the call to Queue.get(), meaning that it will be computationally efficient.

You can learn more about blocking calls in this tutorial:

• Thread Blocking Call in Python

Next, we can update our task() function executed by worker threads to take the shared queue as an argument and to put messages on the queue instead of calling print.

The updated task() function with these changes is listed below.

Finally, in the main thread we can create an instance of a queue, such as the queue.Queue class. This is a thread-safe data structure on which messages as objects can be appended via put() and removed and retrieved via get().

We can then create a new thread for printing. We can configure it to call our printer() function, to run in the background by setting “daemon” to True and to give it a useful name like ‘Printer‘.

Because the printer thread is a daemon thread, it will run in the background and will not prevent the Python process from terminating once all worker threads and the main thread terminate.

You can learn more about daemon threads in this tutorial:

• How to Use Daemon Threads in Python

Finally, we can pass the instance of the shared queue to each worker thread as an argument.

Tying this together, the complete example of using a dedicated printing thread is listed below.

Running the example first creates the shared queue.

It then creates and configures the printer thread and starts executing it in the background.

Next, the worker threads are created and configured. Finally, the main thread starts the worker threads and waits for them to terminate.

Each worker thread performs its task, generating a random number and blocking. It then puts its messages on the queue and terminates.

The printer thread runs in a loop, each iteration taking one message of the queue and then printing it. Because there is only a single printer thread, it is the only thread calling print(), which makes it thread-safe.

A truncated example of the output is listed below.

Note, your specific results will differ each time the program is run due to the use of random numbers.

Further Reading

This section provides additional resources that you may find helpful.

Python Threading Books

• Python Threading Jump-Start, Jason Brownlee (my book!)
• Threading API Interview Questions
• Threading Module API Cheat Sheet

I also recommend specific chapters in the following books:

• Python Cookbook, David Beazley and Brian Jones, 2013.
  • See: Chapter 12: Concurrency
• 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 Threading: The Complete Guide
• Python ThreadPoolExecutor: The Complete Guide
• Python ThreadPool: The Complete Guide

APIs

• threading - Thread-based parallelism
• queue — A synchronized queue class

References

• Thread (computing), Wikipedia.
• Process (computing), Wikipedia.

Takeaways

You now know how to call print() in a thread-safe manner.

Do you have any questions?
Ask your questions in the comments below and I will do my best to answer.

Photo by Arrul lin on Unsplash