Stream buffer overflow

Starting with Tobii Pro SDK version 2.0, most streams provided by the SDK use a circular buffer to temporarily store data in order to prevent data loss. In the event of a stream buffer overflow, a notification is published by the SDK. This indicates that data loss might occur. This article discusses the practical implications of the buffer and the underlying concepts behind stream buffer overflow.

This is a new feature in Tobii Pro SDK 2.0 and only applies to SDK version 2.0 or later.

Overview of how your code is affected

The buffer helps prevent data loss during brief interruptions of the execution of code using the Tobii Pro SDK. However, in the event of continuous slowdowns, a buffer overflow (as explained below) and resulting data loss will occur. Therefore, it is recommended that you:

  • Avoid writing code that "hogs" resources and does not yield control to the parts of your code that use the Tobii Pro SDK, such as an empty while loop in Python.
  • Avoid straining your computer, whether it be through your script (for example, intense image manipulations during a recording) or by running resource-intensive programs in the background.
  • Subscribe to notifications indicating buffer overflow, when the code examples for your programming language suggest you do so.

More information is available in the programming language-specific documentation.

Circular buffer

The primary purpose of a circular buffer is to enable efficient, constant-time access to data stored in a fixed-size buffer. Unlike traditional linear buffers, circular buffers wrap around when they reach the end, allowing for seamless and continuous data processing without the need to shift elements.

In managing data flow, we must define the terms Tail and Head:

  • Head: This refers to the front or starting point of the data structure where elements are read or dequeued.
  • Tail: Conversely, the tail represents the end point of the data structure where new elements are added or enqueued.

Circular buffer

Stream buffer overflow

In a circular buffer, a buffer overflow occurs when new data is attempted to be written into the buffer, but there is no more space available to accommodate it. This situation typically arises if data is being written into the circular buffer at a faster rate than it is being read or consumed, in which case the buffer will eventually fill up. When the buffer is full and new data is written, it overwrites the oldest data in the buffer. However, if the rate of writing exceeds the rate of reading consistently, it can lead to a situation where the buffer fills up faster than it can be emptied, causing a buffer overflow, in this case called a stream buffer overflow.

Stream buffer overflow notifications

When a stream buffer overflow occurs, the underlying SDK will publish a notification: TOBII_PRO_NOTIFICATION_STREAM_BUFFER_OVERFLOW. Be sure to subscribe and filter to these notifications in your preferred binding. If a stream buffer overflow is not adressed, data might be lost.