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

gwr_components/flow_controls/
rate_limiter.rs
