Threaded Queue Mode¶

Overview¶

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.

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:

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.