Rate Limiting With RateDrop

A RateDrop object limits how often Frame objects are forwarded to downstream consumers.

You typically add a RateDrop when a downstream Slave cannot keep up with the full incoming rate but still benefits from seeing a representative subset of traffic. Common examples include live monitoring, file capture of diagnostic samples, or GUI update paths that should not consume every Frame produced by the main stream.

At a high level, RateDrop supports two operating modes:

  • Time mode, where forwarded Frame objects are separated by at least a configured time interval

  • Count mode, where roughly one Frame is kept and then a configured number of following Frame objects are dropped

Constructor

  • Python: ris.RateDrop(period, value)

  • C++: ris::RateDrop::create(period, value)

Rate Drop Behavior

The meaning of value depends on the period flag:

  • period=True: value is interpreted as seconds between forwarded Frame objects. For example, value=0.1 forwards at about 10 Hz.

  • period=False: value is interpreted as a drop-count setting. One Frame is forwarded, then roughly value Frame objects are suppressed before forwarding the next one.

  • value=0 in count mode effectively disables dropping.

Time mode is usually the better choice for live displays and diagnostics, because it produces a more predictable output rate. Count mode is useful when the source rate is already stable and the goal is simply to thin the stream.

Python Time Mode Example

The most common use is to limit a monitoring or logging path to a fixed approximate rate.

import rogue.interfaces.stream as ris

# Data source
src = MyCustomMaster()

# Data destination
dst = MyCustomSlave()

# Keep at most one Frame every 0.01 seconds, about 100 Hz
rate = ris.RateDrop(True, 0.01)

# Connect the RateDrop object between the source and the destination
src >> rate >> dst

C++ Time Mode Example

#include "rogue/Helpers.h"
#include "rogue/interfaces/stream/RateDrop.h"
#include "MyCustomMaster.h"
#include "MyCustomSlave.h"

int main() {
   // Data source
   auto src = MyCustomMaster::create();

   // Data destination
   auto dst = MyCustomSlave::create();

   // Keep at most one Frame every 0.01 seconds, about 100 Hz
   auto rate = rogue::interfaces::stream::RateDrop::create(true, 0.01);

   // Connect the RateDrop object between the source and the destination
   rogueStreamConnect(src, rate);
   rogueStreamConnect(rate, dst);
   return 0;
}

Python Count Mode Example

Count mode is useful when the source rate is steady and you want to keep only a sparse subset of the traffic.

import rogue.interfaces.stream as ris

# Data source
src = MyCustomMaster()

# Data destination
dst = MyCustomSlave()

# Forward one Frame, then drop about ten
sparse = ris.RateDrop(False, 10)

src >> sparse >> dst

Logging

RateDrop uses Rogue C++ logging with the static logger name pyrogue.stream.RateDrop.

If you want implementation messages from the object itself, enable that logger before constructing the RateDrop:

import rogue
import rogue.interfaces.stream as ris

rogue.Logging.setFilter('pyrogue.stream.RateDrop', rogue.Logging.Debug)
rate = ris.RateDrop(True, 0.1)

RateDrop does not expose a separate runtime setDebug(...) helper. If you want to inspect the thinned stream payload, attach a debug Slave downstream and enable setDebug(maxBytes, name) there.

What To Explore Next

API Reference