Skip to content

Threaded Queue Modeβš“


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

Threaded Queue Mode is designed exclusively for VidGear's Videocapture Gears (namely CamGear, VideoGear) and few Network Gears (such as NetGear(Client's end)) for achieving high-performance, asynchronous, error-free video-frames handling.

Threaded-Queue-Mode is enabled by default, but can be disabled, only if extremely necessary.

Threaded-Queue-Mode is NOT required and thereby automatically disabled for Live feed such as Camera Devices/Modules, since .


What does Threaded-Queue-Mode exactly 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βš“

In case you don't already know, OpenCV's' read() is a Blocking I/O function for reading and decoding the next video-frame, and consumes much of the I/O bound memory depending upon our video source properties & system hardware. This essentially means, the corresponding thread that reads data from it, is continuously blocked from retrieving the next frame. As a result, our python program appears slow and sluggish even without any type of computationally expensive image processing operations. This problem is far more severe on low memory SBCs like Raspberry Pis.

In Threaded-Queue-Mode, VidGear creates several Python Threads within one process to offload the frame-decoding task to a different thread. Thereby, VidGear is able to execute different Video I/O-bounded operations at the same time by overlapping there waiting times. Moreover, threads are managed by operating system itself and is capable of distributing them between available CPU cores efficiently. In this way, Threaded-Queue-Mode keeps on processing frames faster in the background without affecting by sluggishness in our main python program thread.

B. Utilizes Fixed-Size Queuesβš“

Although Multi-threading is fast, easy, and efficient, it can lead to some serious undesired effects like frame-skipping, Global Interpreter Lock, race conditions, etc. This is because there is no isolation whatsoever in python threads, and in case there is any crash it will cause the whole process to crash. That's not all, the memory of the process is shared by different threads and that may result in random process crashes due to unwanted race conditions.

These problems are avoided in Threaded-Queue-Mode by utilizing Thread-Safe, Memory-Efficient, and Fixed-Size Queues (with approximately same O(1) performance in both directions), that isolates the frame-decoding thread from other parallel threads and provide synchronized access to incoming frames without any obstruction.

C. Accelerates Frame Processingβš“

With queues, VidGear always maintains a fixed-length frames buffer in the memory and blocks the thread temporarily if the queue is full to avoid possible frame drops or otherwise pops out the frames synchronously without any obstructions. This significantly accelerates frame processing rate (and therefore our overall video processing pipeline) comes from dramatically reducing latency β€” since we don’t have to wait for the read() method to finish reading and decoding a frame; instead, there is always a pre-decoded frame ready for us to process.


What are the advantages of Threaded-Queue-Mode?βš“

  • Enables Blocking, Sequential and Threaded LIFO Frame Handling.

  • Sequentially adds and releases frames from queues and handles the overflow.

  • Utilizes thread-safe, memory efficient queues that appends and pops frames with same O(1) performance from either side.

  • Faster frame access due to buffered frames in the queue.

  • Provides isolation for source thread and prevents GIL.


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 that can be quite difficult to discover. 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.


Last update: July 4, 2023