Skip to main content

gwr_components/flow_controls/
rate_limiter.rs

1// Copyright (c) 2023 Graphcore Ltd. All rights reserved.
2
3//! Provide effective bandwidth limit for a component.
4//!
5//! A [RateLimiter] is given a
6//! [clock](gwr_engine::time::clock::Clock) and a rate in `bits per tick`.
7//! It calculates the service duration for an object. Components such as
8//! [Limiter](crate::flow_controls::limiter::Limiter) use this duration and the
9//! clock to enforce the rate limit.
10//!
11//! The [RateLimiter] therefore requires objects to implement the
12//! [TotalBytes] trait so that the number of bits of the object can be
13//! determined.
14//!
15//! # Creating a Rate Limiter
16//!
17//! [RateLimiter]s should normally be constructed using the
18//! [rc_limiter!](crate::rc_limiter) macro. This returns a
19//! `Result<Rc<RateLimiter>, SimError>`, rejecting a zero rate. Components
20//! normally accept an `Rc<RateLimiter>` as a rate limiter argument.
21//! They are `Rc`ed because they are used immutably and as a result the same
22//! rate limiter can be shared by all components that have the same bandwidth.
23//!
24//! # Examples:
25//!
26//! Here is a basic example of a rate limiter being used by the
27//! [Limiter](crate::flow_controls::limiter) component which is connected
28//! between a source and sink.
29//!
30//! A [source](crate::source::Source) is used to produce 4-byte packets.
31//! The rate limiter is configured to run on a 1GHz clock at a rate of 16 bits
32//! per tick.
33//!
34//! As a result, the total time for the simulation should be `20.0ns` because
35//! each of the 10 packets should take 2 clock ticks to pass through the
36//! [Limiter](crate::flow_controls::limiter) and be consumed by the
37//! [Sink](crate::sink::Sink).
38//!
39//! ```rust
40//! # use gwr_components::flow_controls::limiter::Limiter;
41//! # use gwr_components::sink::Sink;
42//! # use gwr_components::source::Source;
43//! # use gwr_components::{connect_port, rc_limiter, option_box_repeat};
44//! # use gwr_engine::engine::Engine;
45//! # use gwr_engine::run_simulation;
46//!
47//! // Create the engine.
48//! let mut engine = Engine::default();
49//!
50//! // Create a 1GHz clock.
51//! let clock = engine.clock_ghz(1.0);
52//!
53//! // And build a 16 bits-per-tick rate limiter.
54//! let rate_limiter = rc_limiter!(&clock, 16).unwrap();
55//!
56//! // Build the source (initially with no generator).
57//! let source = Source::new_and_register(&engine, engine.top(), "source", None);
58//!
59//! // Create a packet that uses the source as its trace-control entity.
60//! let packet = 0; // TODO implement a packet type to use here
61//!
62//! // Configure the source to produce ten of these packets.
63//! source.set_generator(option_box_repeat!(packet ; 10));
64//!
65//! // Create the a limiter component to enforce the limit
66//! let limiter = Limiter::new_and_register(&engine, &clock, engine.top(), "limit", rate_limiter);
67//!
68//! // Create the sink to accept these packets.
69//! let sink = Sink::new_and_register(&engine, &clock, engine.top(), "sink");
70//!
71//! // Connect the components.
72//! connect_port!(source, tx => limiter, rx)
73//!     .expect("should be able to connect `Source` to `Limiter`");
74//! connect_port!(limiter, tx => sink, rx)
75//!     .expect("should be able to connect `Limiter` to `Sink`");
76//!
77//! // Run the simulation.
78//! run_simulation!(engine);
79//!
80//! // Ensure the time is as expected.
81//! assert_eq!(engine.time_now_ns(), 20.0);
82//! ```
83
84use std::marker::PhantomData;
85
86use gwr_engine::time::clock::Clock;
87use gwr_engine::traits::TotalBytes;
88use gwr_engine::types::SimError;
89
90/// Create a [RateLimiter] wrapped in an [Rc](std::rc::Rc), returning a
91/// [`SimError`] if the rate is zero.
92///
93/// This is the most common form of [RateLimiter] used because all of its
94/// methods can be used immutably and therefore it can be shared by any number
95/// of components with the same bandwidth limit.
96#[macro_export]
97macro_rules! rc_limiter {
98    ($clock:expr, $bits_per_tick:expr) => {
99        $crate::flow_controls::rate_limiter::RateLimiter::new($clock, $bits_per_tick)
100            .map(std::rc::Rc::new)
101    };
102}
103
104#[macro_export]
105macro_rules! option_rc_limiter {
106    ($clock:expr, $bits_per_tick:expr) => {
107        $crate::rc_limiter!($clock, $bits_per_tick).map(Some)
108    };
109}
110
111#[derive(Clone)]
112pub struct RateLimiter<T>
113where
114    T: TotalBytes,
115{
116    /// Clock rate limiter is attached to.
117    clock: Clock,
118
119    /// Bits per tick that can pass through this interface.
120    bits_per_tick: usize,
121
122    phantom: PhantomData<T>,
123}
124
125impl<T> RateLimiter<T>
126where
127    T: TotalBytes,
128{
129    /// Create a rate limiter, rejecting a zero rate.
130    pub fn new(clock: &Clock, bits_per_tick: usize) -> Result<Self, SimError> {
131        if bits_per_tick == 0 {
132            return Err(SimError("rate limiter rate must be positive".into()));
133        }
134        Ok(Self {
135            clock: clock.clone(),
136            bits_per_tick,
137            phantom: PhantomData,
138        })
139    }
140
141    pub(super) fn clock(&self) -> &Clock {
142        &self.clock
143    }
144
145    /// Calculate a packet's service duration without overflowing its bit count.
146    pub fn ticks(&self, value: &T) -> Result<u64, SimError> {
147        let bits = value
148            .total_bytes()
149            .checked_mul(8)
150            .ok_or_else(|| SimError("rate limiter packet bit count overflows".into()))?;
151        self.ticks_from_bits(bits)
152    }
153
154    /// Round up to whole ticks, rejecting an unrepresentable duration.
155    fn ticks_from_bits(&self, bits: usize) -> Result<u64, SimError> {
156        u64::try_from(bits.div_ceil(self.bits_per_tick))
157            .map_err(|_| SimError("rate limiter duration exceeds u64".into()))
158    }
159}