【Python】Using Timeouts with Thread-Safe Queues

Overview

By default, the put() and get() methods of queue.Queue wait indefinitely (block) until the operation is completed. By specifying the timeout argument, you can raise an exception (Full or Empty) if the operation does not complete within a set time. This prevents your program from freezing.

Specifications (Input/Output)

• Input: Timeout duration in seconds.
• Output: Data on success, or an exception on failure (timeout).
• Requirement: import queue is necessary.

Methods and Processing

Exception Classes and Descriptions

Basic Usage

When specifying a timeout, you should always wrap the call in a try-except block to handle the potential exception.

1. Put Timeout (Handling a Full Queue)

This occurs when the queue has a size limit (maxsize).

import queue

# Create a queue with a capacity of only 1
q = queue.Queue(maxsize=1)

# Add one item to fill the queue
q.put("Data1")
print("Added the first item")

try:
    # Try to add a second item to the full queue (wait for 2 seconds)
    print("Attempting to add a second item...")
    q.put("Data2", timeout=2)
except queue.Full:
    print("Timeout: The queue is full and the item could not be added.")

2. Get Timeout (Handling an Empty Queue)

This prevents the program from waiting indefinitely for data to arrive.

import queue

# Create an empty queue
q = queue.Queue()

try:
    # Try to retrieve data from an empty queue (wait for 2 seconds)
    print("Waiting for data...")
    item = q.get(timeout=2)
except queue.Empty:
    print("Timeout: The queue is empty and no data could be retrieved.")

Full Code

This demo function combines both scenarios. This is a common pattern in thread communication to exit a loop rather than waiting forever when no data arrives.

import queue
import time

def queue_timeout_demo():
    print("--- Demo: put(timeout) ---")
    # maxsize=1 means it fills up immediately
    q_limit = queue.Queue(maxsize=1)
    
    q_limit.put("First Item") # Success
    print("Queue status: Full")
    
    try:
        # Will be blocked because it is full. Give up after 1 second.
        start_time = time.time()
        q_limit.put("Second Item", timeout=1.0)
    except queue.Full:
        elapsed = time.time() - start_time
        print(f"Exception caught: queue.Full ({elapsed:.2f} seconds elapsed)")

    print("\n--- Demo: get(timeout) ---")
    # Empty queue
    q_empty = queue.Queue()
    print("Queue status: Empty")
    
    try:
        # Will be blocked because it is empty. Give up after 1.5 seconds.
        start_time = time.time()
        data = q_empty.get(timeout=1.5)
    except queue.Empty:
        elapsed = time.time() - start_time
        print(f"Exception caught: queue.Empty ({elapsed:.2f} seconds elapsed)")

if __name__ == "__main__":
    queue_timeout_demo()

Summary

• timeout=None (Default): Waits indefinitely.
• timeout=Positive number: Waits for the specified seconds and raises an exception if unsuccessful.
• timeout=0 (or block=False): Does not wait; succeeds or raises an exception immediately.

In concurrent programming, it is recommended to set a timeout and implement exception handling whenever possible to prevent system freezes or deadlocks.