Operator Throttle

Primitive operator image not displayed. Problem loading file: ../../image/tk$spl/op$spl.utility$Throttle.svg

The Throttle operator is used to pace a stream to make it flow at a specified rate.

Checkpointed data

When the Throttle operator is checkpointed, logic state variables (if present) are saved in checkpoint.

Behavior in a consistent region

The Throttle operator can be an operator within the reachability graph of a consistent region. It cannot be the start of a consistent region. In a consistent region, a Throttle operator stores its state when a checkpoint is taken. When the region is reset, the operator restores the state from the checkpoint. When in a consistent region, the operator finishes draining only after processing all its input tuples that must be delayed. It is recommended for the Throttle operator to be run by the same thread (that is, fused and without threaded ports) as the start operator of the region to reduce the number of pending input tuples to be processed during a drain and reset.

Checkpointing behavior in an autonomous region

When the Throttle operator is in an autonomous region and configured with config checkpoint : periodic(T) clause, a background thread in SPL Runtime checkpoints the operator every T seconds, and such periodic checkpointing activity is asynchronous to tuple processing. Upon restart, the operator restores its state from the last checkpoint.

When the Throttle operator is in an autonomous region and configured with config checkpoint : operatorDriven clause, no checkpoint is taken at runtime. Upon restart, the operator restores to its initial state.

Such checkpointing behavior is subject to change in the future.

Examples

This example uses the Throttle operator. 


composite Main {                                                             
  graph                                                                      
    stream<rstring name, uint32 age> Beat = Beacon() {}                      
    // with rate only                                                        
    stream<rstring name, uint32 age> Throttled1 = Throttle(Beat)             
    {                                                                        
      param rate : 100.0;                                                    
    }                                                                        
    // with optional period                                                  
    stream<rstring name, uint32 age> Throttled2 = Throttle(Beat)             
    {                                                                        
      param rate   : 100.0;                                                  
            period : 0.05;                                                   
    }                                                                        
    // with punctuations included                                            
    stream<rstring name, uint32 age> Throttled3 = Throttle(Beat)             
    {                                                                        
      param rate               : 100.0;                                      
            period             : 0.05;                                       
           includePunctuations : true;                                      
    }                                                                        
}

Summary

Ports
This operator has 1 input port and 1 output port.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 4 parameters.

Required: rate

Optional: includePunctuations, period, precise

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

The Throttle operator is configurable with a single input port, which ingests tuples to be rate throttled.

Properties

Output Ports

Assignments
This operator does not allow assignments to output attributes.
Ports (0)

The Throttle operator is configurable with a single output port, which produces tuples at the specified rate. The schema of the output port must match that of the input port.

Properties

Parameters

This operator supports 4 parameters.

Required: rate

Optional: includePunctuations, period, precise

includePunctuations

Specifies whether punctuation is to be included in the rate computation. The default value is false.

Properties

period

Specifies the period to be used for maintaining the wanted rate in seconds. When making rate adjustments, the Throttle operator considers only the last period, going back from the current time. By default, the period is set to 10.0/rate.

Properties

precise

Specifies whether precise blocking is used. Some systems lack the required resolution to block for very small durations. In such cases, this option enables precise blocking with the use of busy wait.

Properties

rate

Specifies the wanted rate in tuples per seconds.

Properties

Code Templates

Throttle

stream<${inputStream}> ${outputStream} = Throttle(${inputStream}){
            param
                rate: ${throttleRate};
        }

Libraries

spl-std-tk-lib
Library Name: streams-stdtk-runtime
Include Path: ../../../impl/include