Skip to content

Threaded Queue Mode

Overview

Threading timing diagram
Threaded-Queue-Mode: generalized timing diagram

Threaded Queue Mode is designed exclusively for VidGear's VideoCapture Gears (namely FFGear, CamGear, and VideoGear) and select Network Gears (such as NetGear Client-end) to achieve high-performance, asynchronous, and error-free video frame handling.

Threaded-Queue-Mode is enabled by default. It should only be disabled if strictly necessary for specific debugging purposes.

Threaded-Queue-Mode is NOT required for live feeds (such as Camera Modules) and is automatically disabled to ensure minimum latency and real-time synchronization.

 

What does Threaded-Queue-Mode actually do?

Threaded-Queue-Mode helps VidGear do the Threaded Video-Processing tasks in highly optimized, well-organized, and most competent way possible:

A. Enables Multi-Threading

OpenCV's read() is a Blocking I/O function. When it fetches and decodes a frame, it halts the execution of the thread until the frame is ready. This often results in "sluggish" performance, especially on resource-constrained devices like Raspberry Pis.

TQM offloads the frame-decoding task to a dedicated Background Thread. By overlapping I/O wait times with your main program's logic, VidGear ensures that the CPU isn't sitting idle. While one thread waits for the next frame to decode, your main thread is free to process the current one.

B. Utilizes Fixed-Size Queues

While multithreading is powerful, shared memory can lead to race conditions or memory leaks if not handled correctly.

TQM solves this by using Thread-Safe, Fixed-Size Queues. These queues act as a synchronized buffer between the "producer" (the decoding thread) and the "consumer" (your main program). This provides a layer of thread isolation, ensuring that even if the decoding thread fluctuates in speed, your main process remains stable.

C. Accelerates Frame Processing

By maintaining a pre-decoded buffer in memory, TQM dramatically reduces latency. Instead of your code asking for a frame and waiting for the hardware to decode it, the frame is already sitting in the queue, ready to be "popped" instantly.

 

What are the advantages of Threaded-Queue-Mode?

  • Asynchronous FIFO Handling: Ensures frames are processed in the correct sequential order without blocking the main loop.
  • Overflow Management: Automatically handles synchronization between producer and consumer threads to prevent memory bloat.
  • O(1) Performance: Utilizes efficient data structures for nearly instantaneous frame retrieval.
  • Reduced Latency: Buffered frames ensure the "next" frame is always ready before your code asks for it.
  • GIL Mitigation: Optimizes performance by utilizing Python’s ability to release the GIL during I/O-bound tasks.

 

Manually disabling Threaded-Queue-Mode

To manually disable Threaded-Queue-Mode, VidGear provides THREADED_QUEUE_MODE boolean attribute for options dictionary parameter in respective VideoCapture APIs:

Important Warnings
  • Disabling Threaded-Queue-Mode does NOT disables Multi-Threading.
  • THREADED_QUEUE_MODE attribute does NOT work with Live feed, such as Camera Devices/Modules.
  • THREADED_QUEUE_MODE attribute is NOT supported by ScreenGear & NetGear APIs, as Threaded Queue Mode is essential for their core operations.

Disabling Threaded-Queue-Mode may lead to Random Intermittent Bugs or dropped frames that are difficult to debug. Only disable this if you are performing custom low-level thread management. More insight can be found here ➶"

THREADED_QUEUE_MODE (boolean): This attribute can be used to override Threaded-Queue-Mode mode to manually disable it:

options = {'THREADED_QUEUE_MODE': False} # to disable Threaded Queue Mode.

and you can pass it to options dictionary parameter of the respective API.