Jekyll2022-08-09T12:53:47+00:00https://codecatalog.org/feed.xmlCode CatalogA curated collection of annotated code examples from prominent open-source projectsNew Article: Leader Election with Raft in Scylla2021-09-25T15:02:00+00:002021-09-25T15:02:00+00:00https://codecatalog.org/2021/09/25/scylla-raft-leader-election<h2 id="new-article-leader-election-with-raft-in-scylla"><a href="/2021/09/25/scylla-raft-leader-election.html">New Article: Leader Election with Raft in Scylla</a></h2>
<time datetime="2021-09-25">25 September 2021</time>
<p>A <a href="/articles/scylla-raft-leader-election">new article</a> about leader election with Raft in <a href="https://www.scylladb.com/">ScyllaDB</a> has been added to the catalog.</p>
<p><a href="https://en.wikipedia.org/wiki/Raft_(algorithm)">Raft</a> is a consensus algorithm that was designed to be easy to understand. In Raft all interactions with clients go through the leader node, which first needs to be elected. In this article, we look into how this is implemented in Scylla.</p>
<p>The code is written in C++.</p>
<p><a href="/articles/scylla-raft-leader-election">Scylla - Leader Election with Raft</a></p>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>New Article: Leader Election with Raft in ScyllaNew Article: Skip Lists in Visual Studio Code2021-09-15T06:27:00+00:002021-09-15T06:27:00+00:00https://codecatalog.org/2021/09/15/vscode-skip-list<h2 id="new-article-skip-lists-in-visual-studio-code"><a href="/2021/09/15/vscode-skip-list.html">New Article: Skip Lists in Visual Studio Code</a></h2>
<time datetime="2021-09-15">15 September 2021</time>
<p>A <a href="/articles/vscode-skip-list">new article</a> about skip list implementation in <a href="https://code.visualstudio.com/">Visual Studio Code</a> has been added to the catalog.</p>
<p><a href="https://en.wikipedia.org/wiki/Skip_list">Skip List</a> is a probabilistic data structure that can be used instead of balanced trees in most applications. Unlike other data structures with similar performance, like <a href="https://en.wikipedia.org/wiki/Red%E2%80%93black_tree">Red-black trees</a>, skip lists are notoriously easy to understand and implement.</p>
<p>The code is written in TypeScript.</p>
<p><a href="/articles/vscode-skip-list">Visual Studio Code - Skip Lists</a></p>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>New Article: Skip Lists in Visual Studio CodeNew Article: Graph Algorithms in Puppet2021-09-09T11:53:00+00:002021-09-09T11:53:00+00:00https://codecatalog.org/2021/09/09/puppet-graph-algorithms<h2 id="new-article-graph-algorithms-in-puppet"><a href="/2021/09/09/puppet-graph-algorithms.html">New Article: Graph Algorithms in Puppet</a></h2>
<time datetime="2021-09-09">09 September 2021</time>
<p>A <a href="/articles/puppet-graph-algorithms">new article</a> about graph algorithms in <a href="https://puppet.com">Puppet</a> has been added to the catalog. This is our second article featuring Puppet after <a href="/articles/puppet-connection-pool">Puppet - HTTP Connection Pool</a>.</p>
<p>We discuss how Puppet uses standard graph algorithms, such as <a href="https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm">Tarjan’s</a> strongly connected components algorithm, to manage dependencies between resources. It strongly resembles our older article about <a href="/articles/terraform-graph-algorithms">graph algorithms in Terraform</a> (if you read this article long ago, consider giving it another look - we recently made significant updates to it). We consider continuing reviewing uses of graph algorithms in popular open-source projects.</p>
<p>The code is written in Ruby.</p>
<p><a href="/articles/puppet-graph-algorithms">Puppet - Graph Algorithms</a></p>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>New Article: Graph Algorithms in PuppetWriting Well-Documented Code - Learn from Examples2021-09-04T15:58:00+00:002021-09-04T15:58:00+00:00https://codecatalog.org/2021/09/04/well-documented-code<h2 id="writing-well-documented-code---learn-from-examples"><a href="/2021/09/04/well-documented-code.html">Writing Well-Documented Code - Learn from Examples</a></h2>
<time datetime="2021-09-04">04 September 2021</time>
<p>Who doesn’t like well-documented code? I greatly appreciate when the author of the code I’m reading took his/her time to explain it.</p>
<p>While there’s a never-ending debate about how to write comments and how to write code that’s easy to read without comments, perhaps it can be generally accepted that documenting one’s code one way or another is an important skill for a programmer.</p>
<p>The reason we started Code Catalog is because we believe that we can improve our coding skills by reading good code written by others. Commenting code is no exception. So let’s look at a few examples of good code with helpful comments.</p>
<h3 id="exhibit-a---firecracker">Exhibit A - <a href="https://github.com/firecracker-microvm/firecracker">Firecracker</a></h3>
<p><em>Firecracker is an open source virtualization technology that is purpose-built for creating and managing secure, multi-tenant container and function-based services that provide serverless operational models. Firecracker runs workloads in lightweight virtual machines, called microVMs, which combine the security and isolation properties provided by hardware virtualization technology with the speed and flexibility of containers.</em></p>
<p>Take a look at Firecracker’s <a href="https://github.com/firecracker-microvm/firecracker/blob/2f92f4a2d189c504aa358928b3ad490aafa61cff/src/rate_limiter/src/lib.rs">rate limiter</a> responsible for throttling operations and bandwidth. It’s written in Rust and is based on the <a href="https://en.wikipedia.org/wiki/Token_bucket">Token Bucket</a> algorithm. We recently <a href="/articles/firecracker-rate-limiting">wrote about it</a>.</p>
<details>
<summary><em>Expand (very long block of code)</em></summary>
<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">// Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.</span>
<span class="c">// SPDX-License-Identifier: Apache-2.0</span>
<span class="nd">#![deny(missing_docs)]</span>
<span class="c">//! # Rate Limiter</span>
<span class="c">//!</span>
<span class="c">//! Provides a rate limiter written in Rust useful for IO operations that need to</span>
<span class="c">//! be throttled.</span>
<span class="c">//!</span>
<span class="c">//! ## Behavior</span>
<span class="c">//!</span>
<span class="c">//! The rate limiter starts off as 'unblocked' with two token buckets configured</span>
<span class="c">//! with the values passed in the `RateLimiter::new()` constructor.</span>
<span class="c">//! All subsequent accounting is done independently for each token bucket based</span>
<span class="c">//! on the `TokenType` used. If any of the buckets runs out of budget, the limiter</span>
<span class="c">//! goes in the 'blocked' state. At this point an internal timer is set up which</span>
<span class="c">//! will later 'wake up' the user in order to retry sending data. The 'wake up'</span>
<span class="c">//! notification will be dispatched as an event on the FD provided by the `AsRawFD`</span>
<span class="c">//! trait implementation.</span>
<span class="c">//!</span>
<span class="c">//! The contract is that the user shall also call the `event_handler()` method on</span>
<span class="c">//! receipt of such an event.</span>
<span class="c">//!</span>
<span class="c">//! The token buckets are replenished when a called `consume()` doesn't find enough</span>
<span class="c">//! tokens in the bucket. The amount of tokens replenished is automatically calculated</span>
<span class="c">//! to respect the `complete_refill_time` configuration parameter provided by the user.</span>
<span class="c">//! The token buckets will never replenish above their respective `size`.</span>
<span class="c">//!</span>
<span class="c">//! Each token bucket can start off with a `one_time_burst` initial extra capacity</span>
<span class="c">//! on top of their `size`. This initial extra credit does not replenish and</span>
<span class="c">//! can be used for an initial burst of data.</span>
<span class="c">//!</span>
<span class="c">//! The granularity for 'wake up' events when the rate limiter is blocked is</span>
<span class="c">//! currently hardcoded to `100 milliseconds`.</span>
<span class="c">//!</span>
<span class="c">//! ## Limitations</span>
<span class="c">//!</span>
<span class="c">//! This rate limiter implementation relies on the *Linux kernel's timerfd* so its</span>
<span class="c">//! usage is limited to Linux systems.</span>
<span class="c">//!</span>
<span class="c">//! Another particularity of this implementation is that it is not self-driving.</span>
<span class="c">//! It is meant to be used in an external event loop and thus implements the `AsRawFd`</span>
<span class="c">//! trait and provides an *event-handler* as part of its API. This *event-handler*</span>
<span class="c">//! needs to be called by the user on every event on the rate limiter's `AsRawFd` FD.</span>
<span class="k">use</span> <span class="nn">logger</span><span class="p">::</span><span class="n">error</span><span class="p">;</span>
<span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">os</span><span class="p">::</span><span class="nn">unix</span><span class="p">::</span><span class="nn">io</span><span class="p">::{</span><span class="n">AsRawFd</span><span class="p">,</span> <span class="n">RawFd</span><span class="p">};</span>
<span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">time</span><span class="p">::{</span><span class="n">Duration</span><span class="p">,</span> <span class="n">Instant</span><span class="p">};</span>
<span class="k">use</span> <span class="nn">std</span><span class="p">::{</span><span class="n">fmt</span><span class="p">,</span> <span class="n">io</span><span class="p">};</span>
<span class="k">use</span> <span class="nn">timerfd</span><span class="p">::{</span><span class="n">ClockId</span><span class="p">,</span> <span class="n">SetTimeFlags</span><span class="p">,</span> <span class="n">TimerFd</span><span class="p">,</span> <span class="n">TimerState</span><span class="p">};</span>
<span class="k">pub</span> <span class="k">mod</span> <span class="n">persist</span><span class="p">;</span>
<span class="nd">#[derive(Debug)]</span>
<span class="c">/// Describes the errors that may occur while handling rate limiter events.</span>
<span class="k">pub</span> <span class="k">enum</span> <span class="n">Error</span> <span class="p">{</span>
<span class="c">/// The event handler was called spuriously.</span>
<span class="nf">SpuriousRateLimiterEvent</span><span class="p">(</span><span class="o">&</span><span class="nv">'static</span> <span class="nb">str</span><span class="p">),</span>
<span class="p">}</span>
<span class="c">// Interval at which the refill timer will run when limiter is at capacity.</span>
<span class="k">const</span> <span class="n">REFILL_TIMER_INTERVAL_MS</span><span class="p">:</span> <span class="nb">u64</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>
<span class="k">const</span> <span class="n">TIMER_REFILL_STATE</span><span class="p">:</span> <span class="n">TimerState</span> <span class="o">=</span>
<span class="nn">TimerState</span><span class="p">::</span><span class="nf">Oneshot</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span><span class="p">));</span>
<span class="k">const</span> <span class="n">NANOSEC_IN_ONE_MILLISEC</span><span class="p">:</span> <span class="nb">u64</span> <span class="o">=</span> <span class="mi">1_000_000</span><span class="p">;</span>
<span class="c">// Euclid's two-thousand-year-old algorithm for finding the greatest common divisor.</span>
<span class="k">fn</span> <span class="nf">gcd</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="nb">u64</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">x</span> <span class="o">=</span> <span class="n">x</span><span class="p">;</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">y</span> <span class="o">=</span> <span class="n">y</span><span class="p">;</span>
<span class="k">while</span> <span class="n">y</span> <span class="o">!=</span> <span class="mi">0</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">t</span> <span class="o">=</span> <span class="n">y</span><span class="p">;</span>
<span class="n">y</span> <span class="o">=</span> <span class="n">x</span> <span class="o">%</span> <span class="n">y</span><span class="p">;</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">t</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">x</span>
<span class="p">}</span>
<span class="c">/// Enum describing the outcomes of a `reduce()` call on a `TokenBucket`.</span>
<span class="nd">#[derive(Clone,</span> <span class="nd">Debug,</span> <span class="nd">PartialEq)]</span>
<span class="k">pub</span> <span class="k">enum</span> <span class="n">BucketReduction</span> <span class="p">{</span>
<span class="c">/// There are not enough tokens to complete the operation.</span>
<span class="nb">Failure</span><span class="p">,</span>
<span class="c">/// A part of the available tokens have been consumed.</span>
<span class="nb">Success</span><span class="p">,</span>
<span class="c">/// A number of tokens `inner` times larger than the bucket size have been consumed.</span>
<span class="nf">OverConsumption</span><span class="p">(</span><span class="nb">f64</span><span class="p">),</span>
<span class="p">}</span>
<span class="c">/// TokenBucket provides a lower level interface to rate limiting with a</span>
<span class="c">/// configurable capacity, refill-rate and initial burst.</span>
<span class="nd">#[derive(Clone,</span> <span class="nd">Debug,</span> <span class="nd">PartialEq)]</span>
<span class="k">pub</span> <span class="k">struct</span> <span class="n">TokenBucket</span> <span class="p">{</span>
<span class="c">// Bucket defining traits.</span>
<span class="n">size</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="c">// Initial burst size.</span>
<span class="n">initial_one_time_burst</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="c">// Complete refill time in milliseconds.</span>
<span class="n">refill_time</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="c">// Internal state descriptors.</span>
<span class="c">// Number of free initial tokens, that can be consumed at no cost.</span>
<span class="n">one_time_burst</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="c">// Current token budget.</span>
<span class="n">budget</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="c">// Last time this token bucket saw activity.</span>
<span class="n">last_update</span><span class="p">:</span> <span class="n">Instant</span><span class="p">,</span>
<span class="c">// Fields used for pre-processing optimizations.</span>
<span class="n">processed_capacity</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">processed_refill_time</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">TokenBucket</span> <span class="p">{</span>
<span class="c">/// Creates a `TokenBucket` wrapped in an `Option`.</span>
<span class="c">///</span>
<span class="c">/// TokenBucket created is of `size` total capacity and takes `complete_refill_time_ms`</span>
<span class="c">/// milliseconds to go from zero tokens to total capacity. The `one_time_burst` is initial</span>
<span class="c">/// extra credit on top of total capacity, that does not replenish and which can be used</span>
<span class="c">/// for an initial burst of data.</span>
<span class="c">///</span>
<span class="c">/// If the `size` or the `complete refill time` are zero, then `None` is returned.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">new</span><span class="p">(</span><span class="n">size</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span> <span class="n">one_time_burst</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span> <span class="n">complete_refill_time_ms</span><span class="p">:</span> <span class="nb">u64</span><span class="p">)</span> <span class="k">-></span> <span class="nb">Option</span><span class="o"><</span><span class="n">Self</span><span class="o">></span> <span class="p">{</span>
<span class="c">// If either token bucket capacity or refill time is 0, disable limiting.</span>
<span class="k">if</span> <span class="n">size</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">||</span> <span class="n">complete_refill_time_ms</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">{</span>
<span class="k">return</span> <span class="nb">None</span><span class="p">;</span>
<span class="p">}</span>
<span class="c">// Formula for computing current refill amount:</span>
<span class="c">// refill_token_count = (delta_time * size) / (complete_refill_time_ms * 1_000_000)</span>
<span class="c">// In order to avoid overflows, simplify the fractions by computing greatest common divisor.</span>
<span class="k">let</span> <span class="n">complete_refill_time_ns</span> <span class="o">=</span> <span class="n">complete_refill_time_ms</span> <span class="o">*</span> <span class="n">NANOSEC_IN_ONE_MILLISEC</span><span class="p">;</span>
<span class="c">// Get the greatest common factor between `size` and `complete_refill_time_ns`.</span>
<span class="k">let</span> <span class="n">common_factor</span> <span class="o">=</span> <span class="nf">gcd</span><span class="p">(</span><span class="n">size</span><span class="p">,</span> <span class="n">complete_refill_time_ns</span><span class="p">);</span>
<span class="c">// The division will be exact since `common_factor` is a factor of `size`.</span>
<span class="k">let</span> <span class="n">processed_capacity</span><span class="p">:</span> <span class="nb">u64</span> <span class="o">=</span> <span class="n">size</span> <span class="o">/</span> <span class="n">common_factor</span><span class="p">;</span>
<span class="c">// The division will be exact since `common_factor` is a factor of `complete_refill_time_ns`.</span>
<span class="k">let</span> <span class="n">processed_refill_time</span><span class="p">:</span> <span class="nb">u64</span> <span class="o">=</span> <span class="n">complete_refill_time_ns</span> <span class="o">/</span> <span class="n">common_factor</span><span class="p">;</span>
<span class="nf">Some</span><span class="p">(</span><span class="n">TokenBucket</span> <span class="p">{</span>
<span class="n">size</span><span class="p">,</span>
<span class="n">one_time_burst</span><span class="p">,</span>
<span class="n">initial_one_time_burst</span><span class="p">:</span> <span class="n">one_time_burst</span><span class="p">,</span>
<span class="n">refill_time</span><span class="p">:</span> <span class="n">complete_refill_time_ms</span><span class="p">,</span>
<span class="c">// Start off full.</span>
<span class="n">budget</span><span class="p">:</span> <span class="n">size</span><span class="p">,</span>
<span class="c">// Last updated is now.</span>
<span class="n">last_update</span><span class="p">:</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">(),</span>
<span class="n">processed_capacity</span><span class="p">,</span>
<span class="n">processed_refill_time</span><span class="p">,</span>
<span class="p">})</span>
<span class="p">}</span>
<span class="c">// Replenishes token bucket based on elapsed time. Should only be called internally by `Self`.</span>
<span class="k">fn</span> <span class="nf">auto_replenish</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">)</span> <span class="p">{</span>
<span class="c">// Compute time passed since last refill/update.</span>
<span class="k">let</span> <span class="n">time_delta</span> <span class="o">=</span> <span class="k">self</span><span class="py">.last_update</span><span class="nf">.elapsed</span><span class="p">()</span><span class="nf">.as_nanos</span><span class="p">()</span> <span class="k">as</span> <span class="nb">u64</span><span class="p">;</span>
<span class="k">self</span><span class="py">.last_update</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="c">// At each 'time_delta' nanoseconds the bucket should refill with:</span>
<span class="c">// refill_amount = (time_delta * size) / (complete_refill_time_ms * 1_000_000)</span>
<span class="c">// `processed_capacity` and `processed_refill_time` are the result of simplifying above</span>
<span class="c">// fraction formula with their greatest-common-factor.</span>
<span class="k">let</span> <span class="n">tokens</span> <span class="o">=</span> <span class="p">(</span><span class="n">time_delta</span> <span class="o">*</span> <span class="k">self</span><span class="py">.processed_capacity</span><span class="p">)</span> <span class="o">/</span> <span class="k">self</span><span class="py">.processed_refill_time</span><span class="p">;</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">=</span> <span class="nn">std</span><span class="p">::</span><span class="nn">cmp</span><span class="p">::</span><span class="nf">min</span><span class="p">(</span><span class="k">self</span><span class="py">.budget</span> <span class="o">+</span> <span class="n">tokens</span><span class="p">,</span> <span class="k">self</span><span class="py">.size</span><span class="p">);</span>
<span class="p">}</span>
<span class="c">/// Attempts to consume `tokens` from the bucket and returns whether the action succeeded.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">reduce</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="k">mut</span> <span class="n">tokens</span><span class="p">:</span> <span class="nb">u64</span><span class="p">)</span> <span class="k">-></span> <span class="n">BucketReduction</span> <span class="p">{</span>
<span class="c">// First things first: consume the one-time-burst budget.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">></span> <span class="mi">0</span> <span class="p">{</span>
<span class="c">// We still have burst budget for *all* tokens requests.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">>=</span> <span class="n">tokens</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">-=</span> <span class="n">tokens</span><span class="p">;</span>
<span class="k">self</span><span class="py">.last_update</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="c">// No need to continue to the refill process, we still have burst budget to consume from.</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c">// We still have burst budget for *some* of the tokens requests.</span>
<span class="c">// The tokens left unfulfilled will be consumed from current `self.budget`.</span>
<span class="n">tokens</span> <span class="o">-=</span> <span class="k">self</span><span class="py">.one_time_burst</span><span class="p">;</span>
<span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.budget</span> <span class="p">{</span>
<span class="c">// Hit the bucket bottom, let's auto-replenish and try again.</span>
<span class="k">self</span><span class="nf">.auto_replenish</span><span class="p">();</span>
<span class="c">// This operation requests a bandwidth higher than the bucket size</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.size</span> <span class="p">{</span>
<span class="nd">error!</span><span class="p">(</span>
<span class="s">"Consumed {} tokens from bucket of size {}"</span><span class="p">,</span>
<span class="n">tokens</span><span class="p">,</span> <span class="k">self</span><span class="py">.size</span>
<span class="p">);</span>
<span class="c">// Empty the bucket and report an overconsumption of</span>
<span class="c">// (remaining tokens / size) times larger than the bucket size</span>
<span class="n">tokens</span> <span class="o">-=</span> <span class="k">self</span><span class="py">.budget</span><span class="p">;</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nf">OverConsumption</span><span class="p">(</span><span class="n">tokens</span> <span class="k">as</span> <span class="nb">f64</span> <span class="o">/</span> <span class="k">self</span><span class="py">.size</span> <span class="k">as</span> <span class="nb">f64</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.budget</span> <span class="p">{</span>
<span class="c">// Still not enough tokens, consume() fails, return false.</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Failure</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">-=</span> <span class="n">tokens</span><span class="p">;</span>
<span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span>
<span class="p">}</span>
<span class="c">/// "Manually" adds tokens to bucket.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">force_replenish</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">tokens</span><span class="p">:</span> <span class="nb">u64</span><span class="p">)</span> <span class="p">{</span>
<span class="c">// This means we are still during the burst interval.</span>
<span class="c">// Of course there is a very small chance that the last reduce() also used up burst</span>
<span class="c">// budget which should now be replenished, but for performance and code-complexity</span>
<span class="c">// reasons we're just gonna let that slide since it's practically inconsequential.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">></span> <span class="mi">0</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">+=</span> <span class="n">tokens</span><span class="p">;</span>
<span class="k">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">=</span> <span class="nn">std</span><span class="p">::</span><span class="nn">cmp</span><span class="p">::</span><span class="nf">min</span><span class="p">(</span><span class="k">self</span><span class="py">.budget</span> <span class="o">+</span> <span class="n">tokens</span><span class="p">,</span> <span class="k">self</span><span class="py">.size</span><span class="p">);</span>
<span class="p">}</span>
<span class="c">/// Returns the capacity of the token bucket.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">capacity</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.size</span>
<span class="p">}</span>
<span class="c">/// Returns the remaining one time burst budget.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">one_time_burst</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.one_time_burst</span>
<span class="p">}</span>
<span class="c">/// Returns the time in milliseconds required to to completely fill the bucket.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">refill_time_ms</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.refill_time</span>
<span class="p">}</span>
<span class="c">/// Returns the current budget (one time burst allowance notwithstanding).</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">budget</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.budget</span>
<span class="p">}</span>
<span class="c">/// Returns the initially configured one time burst budget.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">initial_one_time_burst</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.initial_one_time_burst</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c">/// Enum that describes the type of token used.</span>
<span class="k">pub</span> <span class="k">enum</span> <span class="n">TokenType</span> <span class="p">{</span>
<span class="c">/// Token type used for bandwidth limiting.</span>
<span class="n">Bytes</span><span class="p">,</span>
<span class="c">/// Token type used for operations/second limiting.</span>
<span class="n">Ops</span><span class="p">,</span>
<span class="p">}</span>
<span class="c">/// Enum that describes the type of token bucket update.</span>
<span class="k">pub</span> <span class="k">enum</span> <span class="n">BucketUpdate</span> <span class="p">{</span>
<span class="c">/// No Update - same as before.</span>
<span class="nb">None</span><span class="p">,</span>
<span class="c">/// Rate Limiting is disabled on this bucket.</span>
<span class="n">Disabled</span><span class="p">,</span>
<span class="c">/// Rate Limiting enabled with updated bucket.</span>
<span class="nf">Update</span><span class="p">(</span><span class="n">TokenBucket</span><span class="p">),</span>
<span class="p">}</span>
<span class="c">/// Rate Limiter that works on both bandwidth and ops/s limiting.</span>
<span class="c">///</span>
<span class="c">/// Bandwidth (bytes/s) and ops/s limiting can be used at the same time or individually.</span>
<span class="c">///</span>
<span class="c">/// Implementation uses a single timer through TimerFd to refresh either or</span>
<span class="c">/// both token buckets.</span>
<span class="c">///</span>
<span class="c">/// Its internal buckets are 'passively' replenished as they're being used (as</span>
<span class="c">/// part of `consume()` operations).</span>
<span class="c">/// A timer is enabled and used to 'actively' replenish the token buckets when</span>
<span class="c">/// limiting is in effect and `consume()` operations are disabled.</span>
<span class="c">///</span>
<span class="c">/// RateLimiters will generate events on the FDs provided by their `AsRawFd` trait</span>
<span class="c">/// implementation. These events are meant to be consumed by the user of this struct.</span>
<span class="c">/// On each such event, the user must call the `event_handler()` method.</span>
<span class="k">pub</span> <span class="k">struct</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="n">bandwidth</span><span class="p">:</span> <span class="nb">Option</span><span class="o"><</span><span class="n">TokenBucket</span><span class="o">></span><span class="p">,</span>
<span class="n">ops</span><span class="p">:</span> <span class="nb">Option</span><span class="o"><</span><span class="n">TokenBucket</span><span class="o">></span><span class="p">,</span>
<span class="n">timer_fd</span><span class="p">:</span> <span class="n">TimerFd</span><span class="p">,</span>
<span class="c">// Internal flag that quickly determines timer state.</span>
<span class="n">timer_active</span><span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">PartialEq</span> <span class="k">for</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="k">fn</span> <span class="nf">eq</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">,</span> <span class="n">other</span><span class="p">:</span> <span class="o">&</span><span class="n">RateLimiter</span><span class="p">)</span> <span class="k">-></span> <span class="nb">bool</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.bandwidth</span> <span class="o">==</span> <span class="n">other</span><span class="py">.bandwidth</span> <span class="o">&&</span> <span class="k">self</span><span class="py">.ops</span> <span class="o">==</span> <span class="n">other</span><span class="py">.ops</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="nn">fmt</span><span class="p">::</span><span class="n">Debug</span> <span class="k">for</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="k">fn</span> <span class="nf">fmt</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">,</span> <span class="n">f</span><span class="p">:</span> <span class="o">&</span><span class="k">mut</span> <span class="nn">fmt</span><span class="p">::</span><span class="n">Formatter</span><span class="p">)</span> <span class="k">-></span> <span class="nn">fmt</span><span class="p">::</span><span class="n">Result</span> <span class="p">{</span>
<span class="nd">write!</span><span class="p">(</span>
<span class="n">f</span><span class="p">,</span>
<span class="s">"RateLimiter {{ bandwidth: {:?}, ops: {:?} }}"</span><span class="p">,</span>
<span class="k">self</span><span class="py">.bandwidth</span><span class="p">,</span> <span class="k">self</span><span class="py">.ops</span>
<span class="p">)</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="c">/// Creates a new Rate Limiter that can limit on both bytes/s and ops/s.</span>
<span class="c">///</span>
<span class="c">/// # Arguments</span>
<span class="c">///</span>
<span class="c">/// * `bytes_total_capacity` - the total capacity of the `TokenType::Bytes` token bucket.</span>
<span class="c">/// * `bytes_one_time_burst` - initial extra credit on top of `bytes_total_capacity`,</span>
<span class="c">/// that does not replenish and which can be used for an initial burst of data.</span>
<span class="c">/// * `bytes_complete_refill_time_ms` - number of milliseconds for the `TokenType::Bytes`</span>
<span class="c">/// token bucket to go from zero Bytes to `bytes_total_capacity` Bytes.</span>
<span class="c">/// * `ops_total_capacity` - the total capacity of the `TokenType::Ops` token bucket.</span>
<span class="c">/// * `ops_one_time_burst` - initial extra credit on top of `ops_total_capacity`,</span>
<span class="c">/// that does not replenish and which can be used for an initial burst of data.</span>
<span class="c">/// * `ops_complete_refill_time_ms` - number of milliseconds for the `TokenType::Ops` token</span>
<span class="c">/// bucket to go from zero Ops to `ops_total_capacity` Ops.</span>
<span class="c">///</span>
<span class="c">/// If either bytes/ops *size* or *refill_time* are **zero**, the limiter</span>
<span class="c">/// is **disabled** for that respective token type.</span>
<span class="c">///</span>
<span class="c">/// # Errors</span>
<span class="c">///</span>
<span class="c">/// If the timerfd creation fails, an error is returned.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">new</span><span class="p">(</span>
<span class="n">bytes_total_capacity</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">bytes_one_time_burst</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">bytes_complete_refill_time_ms</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">ops_total_capacity</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">ops_one_time_burst</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="n">ops_complete_refill_time_ms</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span>
<span class="p">)</span> <span class="k">-></span> <span class="nn">io</span><span class="p">::</span><span class="n">Result</span><span class="o"><</span><span class="n">Self</span><span class="o">></span> <span class="p">{</span>
<span class="k">let</span> <span class="n">bytes_token_bucket</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span>
<span class="n">bytes_total_capacity</span><span class="p">,</span>
<span class="n">bytes_one_time_burst</span><span class="p">,</span>
<span class="n">bytes_complete_refill_time_ms</span><span class="p">,</span>
<span class="p">);</span>
<span class="k">let</span> <span class="n">ops_token_bucket</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span>
<span class="n">ops_total_capacity</span><span class="p">,</span>
<span class="n">ops_one_time_burst</span><span class="p">,</span>
<span class="n">ops_complete_refill_time_ms</span><span class="p">,</span>
<span class="p">);</span>
<span class="c">// We'll need a timer_fd, even if our current config effectively disables rate limiting,</span>
<span class="c">// because `Self::update_buckets()` might re-enable it later, and we might be</span>
<span class="c">// seccomp-blocked from creating the timer_fd at that time.</span>
<span class="k">let</span> <span class="n">timer_fd</span> <span class="o">=</span> <span class="nn">TimerFd</span><span class="p">::</span><span class="nf">new_custom</span><span class="p">(</span><span class="nn">ClockId</span><span class="p">::</span><span class="n">Monotonic</span><span class="p">,</span> <span class="k">true</span><span class="p">,</span> <span class="k">true</span><span class="p">)</span><span class="o">?</span><span class="p">;</span>
<span class="nf">Ok</span><span class="p">(</span><span class="n">RateLimiter</span> <span class="p">{</span>
<span class="n">bandwidth</span><span class="p">:</span> <span class="n">bytes_token_bucket</span><span class="p">,</span>
<span class="n">ops</span><span class="p">:</span> <span class="n">ops_token_bucket</span><span class="p">,</span>
<span class="n">timer_fd</span><span class="p">,</span>
<span class="n">timer_active</span><span class="p">:</span> <span class="k">false</span><span class="p">,</span>
<span class="p">})</span>
<span class="p">}</span>
<span class="c">// Arm the timer of the rate limiter with the provided `TimerState`.</span>
<span class="k">fn</span> <span class="nf">activate_timer</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">timer_state</span><span class="p">:</span> <span class="n">TimerState</span><span class="p">)</span> <span class="p">{</span>
<span class="c">// Register the timer; don't care about its previous state</span>
<span class="k">self</span><span class="py">.timer_fd</span><span class="nf">.set_state</span><span class="p">(</span><span class="n">timer_state</span><span class="p">,</span> <span class="nn">SetTimeFlags</span><span class="p">::</span><span class="n">Default</span><span class="p">);</span>
<span class="k">self</span><span class="py">.timer_active</span> <span class="o">=</span> <span class="k">true</span><span class="p">;</span>
<span class="p">}</span>
<span class="c">/// Attempts to consume tokens and returns whether that is possible.</span>
<span class="c">///</span>
<span class="c">/// If rate limiting is disabled on provided `token_type`, this function will always succeed.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">consume</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">tokens</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span> <span class="n">token_type</span><span class="p">:</span> <span class="n">TokenType</span><span class="p">)</span> <span class="k">-></span> <span class="nb">bool</span> <span class="p">{</span>
<span class="c">// If the timer is active, we can't consume tokens from any bucket and the function fails.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.timer_active</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">false</span><span class="p">;</span>
<span class="p">}</span>
<span class="c">// Identify the required token bucket.</span>
<span class="k">let</span> <span class="n">token_bucket</span> <span class="o">=</span> <span class="k">match</span> <span class="n">token_type</span> <span class="p">{</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span> <span class="k">=></span> <span class="k">self</span><span class="py">.bandwidth</span><span class="nf">.as_mut</span><span class="p">(),</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span> <span class="k">=></span> <span class="k">self</span><span class="py">.ops</span><span class="nf">.as_mut</span><span class="p">(),</span>
<span class="p">};</span>
<span class="c">// Try to consume from the token bucket.</span>
<span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">bucket</span><span class="p">)</span> <span class="o">=</span> <span class="n">token_bucket</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">refill_time</span> <span class="o">=</span> <span class="n">bucket</span><span class="nf">.refill_time_ms</span><span class="p">();</span>
<span class="k">match</span> <span class="n">bucket</span><span class="nf">.reduce</span><span class="p">(</span><span class="n">tokens</span><span class="p">)</span> <span class="p">{</span>
<span class="c">// When we report budget is over, there will be no further calls here,</span>
<span class="c">// register a timer to replenish the bucket and resume processing;</span>
<span class="c">// make sure there is only one running timer for this limiter.</span>
<span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Failure</span> <span class="k">=></span> <span class="p">{</span>
<span class="k">if</span> <span class="o">!</span><span class="k">self</span><span class="py">.timer_active</span> <span class="p">{</span>
<span class="k">self</span><span class="nf">.activate_timer</span><span class="p">(</span><span class="n">TIMER_REFILL_STATE</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">false</span>
<span class="p">}</span>
<span class="c">// The operation succeeded and further calls can be made.</span>
<span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span> <span class="k">=></span> <span class="k">true</span><span class="p">,</span>
<span class="c">// The operation succeeded as the tokens have been consumed</span>
<span class="c">// but the timer still needs to be armed.</span>
<span class="nn">BucketReduction</span><span class="p">::</span><span class="nf">OverConsumption</span><span class="p">(</span><span class="n">ratio</span><span class="p">)</span> <span class="k">=></span> <span class="p">{</span>
<span class="c">// The operation "borrowed" a number of tokens `ratio` times</span>
<span class="c">// greater than the size of the bucket, and since it takes</span>
<span class="c">// `refill_time` milliseconds to fill an empty bucket, in</span>
<span class="c">// order to enforce the bandwidth limit we need to prevent</span>
<span class="c">// further calls to the rate limiter for</span>
<span class="c">// `ratio * refill_time` milliseconds.</span>
<span class="k">self</span><span class="nf">.activate_timer</span><span class="p">(</span><span class="nn">TimerState</span><span class="p">::</span><span class="nf">Oneshot</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span>
<span class="p">(</span><span class="n">ratio</span> <span class="o">*</span> <span class="n">refill_time</span> <span class="k">as</span> <span class="nb">f64</span><span class="p">)</span> <span class="k">as</span> <span class="nb">u64</span><span class="p">,</span>
<span class="p">)));</span>
<span class="k">true</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c">// If bucket is not present rate limiting is disabled on token type,</span>
<span class="c">// consume() will always succeed.</span>
<span class="k">true</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c">/// Adds tokens of `token_type` to their respective bucket.</span>
<span class="c">///</span>
<span class="c">/// Can be used to *manually* add tokens to a bucket. Useful for reverting a</span>
<span class="c">/// `consume()` if needed.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">manual_replenish</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">tokens</span><span class="p">:</span> <span class="nb">u64</span><span class="p">,</span> <span class="n">token_type</span><span class="p">:</span> <span class="n">TokenType</span><span class="p">)</span> <span class="p">{</span>
<span class="c">// Identify the required token bucket.</span>
<span class="k">let</span> <span class="n">token_bucket</span> <span class="o">=</span> <span class="k">match</span> <span class="n">token_type</span> <span class="p">{</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span> <span class="k">=></span> <span class="k">self</span><span class="py">.bandwidth</span><span class="nf">.as_mut</span><span class="p">(),</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span> <span class="k">=></span> <span class="k">self</span><span class="py">.ops</span><span class="nf">.as_mut</span><span class="p">(),</span>
<span class="p">};</span>
<span class="c">// Add tokens to the token bucket.</span>
<span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">bucket</span><span class="p">)</span> <span class="o">=</span> <span class="n">token_bucket</span> <span class="p">{</span>
<span class="n">bucket</span><span class="nf">.force_replenish</span><span class="p">(</span><span class="n">tokens</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c">/// Returns whether this rate limiter is blocked.</span>
<span class="c">///</span>
<span class="c">/// The limiter 'blocks' when a `consume()` operation fails because there was not enough</span>
<span class="c">/// budget for it.</span>
<span class="c">/// An event will be generated on the exported FD when the limiter 'unblocks'.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">is_blocked</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">bool</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.timer_active</span>
<span class="p">}</span>
<span class="c">/// This function needs to be called every time there is an event on the</span>
<span class="c">/// FD provided by this object's `AsRawFd` trait implementation.</span>
<span class="c">///</span>
<span class="c">/// # Errors</span>
<span class="c">///</span>
<span class="c">/// If the rate limiter is disabled or is not blocked, an error is returned.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">event_handler</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="n">Result</span><span class="o"><</span><span class="p">(),</span> <span class="n">Error</span><span class="o">></span> <span class="p">{</span>
<span class="k">match</span> <span class="k">self</span><span class="py">.timer_fd</span><span class="nf">.read</span><span class="p">()</span> <span class="p">{</span>
<span class="mi">0</span> <span class="k">=></span> <span class="nf">Err</span><span class="p">(</span><span class="nn">Error</span><span class="p">::</span><span class="nf">SpuriousRateLimiterEvent</span><span class="p">(</span>
<span class="s">"Rate limiter event handler called without a present timer"</span><span class="p">,</span>
<span class="p">)),</span>
<span class="mi">_</span> <span class="k">=></span> <span class="p">{</span>
<span class="k">self</span><span class="py">.timer_active</span> <span class="o">=</span> <span class="k">false</span><span class="p">;</span>
<span class="nf">Ok</span><span class="p">(())</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c">/// Updates the parameters of the token buckets associated with this RateLimiter.</span>
<span class="c">// TODO: Please note that, right now, the buckets become full after being updated.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">update_buckets</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">bytes</span><span class="p">:</span> <span class="n">BucketUpdate</span><span class="p">,</span> <span class="n">ops</span><span class="p">:</span> <span class="n">BucketUpdate</span><span class="p">)</span> <span class="p">{</span>
<span class="k">match</span> <span class="n">bytes</span> <span class="p">{</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="n">Disabled</span> <span class="k">=></span> <span class="k">self</span><span class="py">.bandwidth</span> <span class="o">=</span> <span class="nb">None</span><span class="p">,</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nf">Update</span><span class="p">(</span><span class="n">tb</span><span class="p">)</span> <span class="k">=></span> <span class="k">self</span><span class="py">.bandwidth</span> <span class="o">=</span> <span class="nf">Some</span><span class="p">(</span><span class="n">tb</span><span class="p">),</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nb">None</span> <span class="k">=></span> <span class="p">(),</span>
<span class="p">};</span>
<span class="k">match</span> <span class="n">ops</span> <span class="p">{</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="n">Disabled</span> <span class="k">=></span> <span class="k">self</span><span class="py">.ops</span> <span class="o">=</span> <span class="nb">None</span><span class="p">,</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nf">Update</span><span class="p">(</span><span class="n">tb</span><span class="p">)</span> <span class="k">=></span> <span class="k">self</span><span class="py">.ops</span> <span class="o">=</span> <span class="nf">Some</span><span class="p">(</span><span class="n">tb</span><span class="p">),</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nb">None</span> <span class="k">=></span> <span class="p">(),</span>
<span class="p">};</span>
<span class="p">}</span>
<span class="c">/// Returns an immutable view of the inner bandwidth token bucket.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">bandwidth</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">Option</span><span class="o"><&</span><span class="n">TokenBucket</span><span class="o">></span> <span class="p">{</span>
<span class="k">self</span><span class="py">.bandwidth</span><span class="nf">.as_ref</span><span class="p">()</span>
<span class="p">}</span>
<span class="c">/// Returns an immutable view of the inner ops token bucket.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">ops</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">Option</span><span class="o"><&</span><span class="n">TokenBucket</span><span class="o">></span> <span class="p">{</span>
<span class="k">self</span><span class="py">.ops</span><span class="nf">.as_ref</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">AsRawFd</span> <span class="k">for</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="c">/// Provides a FD which needs to be monitored for POLLIN events.</span>
<span class="c">///</span>
<span class="c">/// This object's `event_handler()` method must be called on such events.</span>
<span class="c">///</span>
<span class="c">/// Will return a negative value if rate limiting is disabled on both</span>
<span class="c">/// token types.</span>
<span class="k">fn</span> <span class="nf">as_raw_fd</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="n">RawFd</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.timer_fd</span><span class="nf">.as_raw_fd</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">Default</span> <span class="k">for</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="c">/// Default RateLimiter is a no-op limiter with infinite budget.</span>
<span class="k">fn</span> <span class="nf">default</span><span class="p">()</span> <span class="k">-></span> <span class="n">Self</span> <span class="p">{</span>
<span class="c">// Safe to unwrap since this will not attempt to create timer_fd.</span>
<span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span><span class="nf">.expect</span><span class="p">(</span><span class="s">"Failed to build default RateLimiter"</span><span class="p">)</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="nd">#[cfg(test)]</span>
<span class="k">pub</span><span class="p">(</span><span class="n">crate</span><span class="p">)</span> <span class="k">mod</span> <span class="n">tests</span> <span class="p">{</span>
<span class="k">use</span> <span class="nn">super</span><span class="p">::</span><span class="o">*</span><span class="p">;</span>
<span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="n">thread</span><span class="p">;</span>
<span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">time</span><span class="p">::</span><span class="n">Duration</span><span class="p">;</span>
<span class="k">impl</span> <span class="n">TokenBucket</span> <span class="p">{</span>
<span class="c">// Resets the token bucket: budget set to max capacity and last-updated set to now.</span>
<span class="k">fn</span> <span class="nf">reset</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">)</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">=</span> <span class="k">self</span><span class="py">.size</span><span class="p">;</span>
<span class="k">self</span><span class="py">.last_update</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">fn</span> <span class="nf">get_last_update</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="o">&</span><span class="n">Instant</span> <span class="p">{</span>
<span class="o">&</span><span class="k">self</span><span class="py">.last_update</span>
<span class="p">}</span>
<span class="k">fn</span> <span class="nf">get_processed_capacity</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.processed_capacity</span>
<span class="p">}</span>
<span class="k">fn</span> <span class="nf">get_processed_refill_time</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">)</span> <span class="k">-></span> <span class="nb">u64</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.processed_refill_time</span>
<span class="p">}</span>
<span class="c">// After a restore, we cannot be certain that the last_update field has the same value.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">partial_eq</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">,</span> <span class="n">other</span><span class="p">:</span> <span class="o">&</span><span class="n">TokenBucket</span><span class="p">)</span> <span class="k">-></span> <span class="nb">bool</span> <span class="p">{</span>
<span class="p">(</span><span class="n">other</span><span class="nf">.capacity</span><span class="p">()</span> <span class="o">==</span> <span class="k">self</span><span class="nf">.capacity</span><span class="p">())</span>
<span class="o">&&</span> <span class="p">(</span><span class="n">other</span><span class="nf">.one_time_burst</span><span class="p">()</span> <span class="o">==</span> <span class="k">self</span><span class="nf">.one_time_burst</span><span class="p">())</span>
<span class="o">&&</span> <span class="p">(</span><span class="n">other</span><span class="nf">.refill_time_ms</span><span class="p">()</span> <span class="o">==</span> <span class="k">self</span><span class="nf">.refill_time_ms</span><span class="p">())</span>
<span class="o">&&</span> <span class="p">(</span><span class="n">other</span><span class="nf">.budget</span><span class="p">()</span> <span class="o">==</span> <span class="k">self</span><span class="nf">.budget</span><span class="p">())</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">impl</span> <span class="n">RateLimiter</span> <span class="p">{</span>
<span class="k">fn</span> <span class="nf">get_token_bucket</span><span class="p">(</span><span class="o">&</span><span class="k">self</span><span class="p">,</span> <span class="n">token_type</span><span class="p">:</span> <span class="n">TokenType</span><span class="p">)</span> <span class="k">-></span> <span class="nb">Option</span><span class="o"><&</span><span class="n">TokenBucket</span><span class="o">></span> <span class="p">{</span>
<span class="k">match</span> <span class="n">token_type</span> <span class="p">{</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span> <span class="k">=></span> <span class="k">self</span><span class="py">.bandwidth</span><span class="nf">.as_ref</span><span class="p">(),</span>
<span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span> <span class="k">=></span> <span class="k">self</span><span class="py">.ops</span><span class="nf">.as_ref</span><span class="p">(),</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_token_bucket_create</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">before</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="k">let</span> <span class="n">tb</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.capacity</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">*</span><span class="n">tb</span><span class="nf">.get_last_update</span><span class="p">()</span> <span class="o">>=</span> <span class="n">before</span><span class="p">);</span>
<span class="k">let</span> <span class="n">after</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">*</span><span class="n">tb</span><span class="nf">.get_last_update</span><span class="p">()</span> <span class="o"><=</span> <span class="n">after</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.get_processed_capacity</span><span class="p">(),</span> <span class="mi">1</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.get_processed_refill_time</span><span class="p">(),</span> <span class="mi">1_000_000</span><span class="p">);</span>
<span class="c">// Verify invalid bucket configurations result in `None`.</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1234</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.is_none</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">1234</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span><span class="nf">.is_none</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1234</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span><span class="nf">.is_none</span><span class="p">());</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_token_bucket_preprocess</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">tb</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.get_processed_capacity</span><span class="p">(),</span> <span class="mi">1</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.get_processed_refill_time</span><span class="p">(),</span> <span class="n">NANOSEC_IN_ONE_MILLISEC</span><span class="p">);</span>
<span class="k">let</span> <span class="n">thousand</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">;</span>
<span class="k">let</span> <span class="n">tb</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">3</span> <span class="o">*</span> <span class="mi">7</span> <span class="o">*</span> <span class="mi">11</span> <span class="o">*</span> <span class="mi">19</span> <span class="o">*</span> <span class="n">thousand</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">7</span> <span class="o">*</span> <span class="mi">11</span> <span class="o">*</span> <span class="mi">13</span> <span class="o">*</span> <span class="mi">17</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.get_processed_capacity</span><span class="p">(),</span> <span class="mi">3</span> <span class="o">*</span> <span class="mi">19</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span>
<span class="n">tb</span><span class="nf">.get_processed_refill_time</span><span class="p">(),</span>
<span class="mi">13</span> <span class="o">*</span> <span class="mi">17</span> <span class="o">*</span> <span class="p">(</span><span class="n">NANOSEC_IN_ONE_MILLISEC</span> <span class="o">/</span> <span class="n">thousand</span><span class="p">)</span>
<span class="p">);</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_token_bucket_reduce</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// token bucket with capacity 1000 and refill time of 1000 milliseconds</span>
<span class="c">// allowing rate of 1 token/ms.</span>
<span class="k">let</span> <span class="n">capacity</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">;</span>
<span class="k">let</span> <span class="n">refill_ms</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">;</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">tb</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">capacity</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">refill_ms</span> <span class="k">as</span> <span class="nb">u64</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">123</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.budget</span><span class="p">(),</span> <span class="n">capacity</span> <span class="o">-</span> <span class="mi">123</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="n">capacity</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Failure</span><span class="p">);</span>
<span class="c">// token bucket with capacity 1000 and refill time of 1000 milliseconds</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">tb</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">1100</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// safely assuming the thread can run these 3 commands in less than 500ms</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">1000</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.one_time_burst</span><span class="p">(),</span> <span class="mi">100</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">500</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.one_time_burst</span><span class="p">(),</span> <span class="mi">0</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">500</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">500</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Failure</span><span class="p">);</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">500</span><span class="p">));</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">500</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">);</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">1000</span><span class="p">));</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.reduce</span><span class="p">(</span><span class="mi">2500</span><span class="p">),</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nf">OverConsumption</span><span class="p">(</span><span class="mf">1.5</span><span class="p">));</span>
<span class="k">let</span> <span class="n">before</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="n">tb</span><span class="nf">.reset</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.capacity</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">tb</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">*</span><span class="n">tb</span><span class="nf">.get_last_update</span><span class="p">()</span> <span class="o">>=</span> <span class="n">before</span><span class="p">);</span>
<span class="k">let</span> <span class="n">after</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">*</span><span class="n">tb</span><span class="nf">.get_last_update</span><span class="p">()</span> <span class="o"><=</span> <span class="n">after</span><span class="p">);</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_default</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">default</span><span class="p">();</span>
<span class="c">// limiter should not be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// limiter should be disabled so consume(whatever) should work</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="nn">u64</span><span class="p">::</span><span class="nf">max_value</span><span class="p">(),</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="nn">u64</span><span class="p">::</span><span class="nf">max_value</span><span class="p">(),</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// calling the handler without there having been an event should error</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_err</span><span class="p">());</span>
<span class="nd">assert_eq!</span><span class="p">(</span>
<span class="nd">format!</span><span class="p">(</span><span class="s">"{:?}"</span><span class="p">,</span> <span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.err</span><span class="p">()</span><span class="nf">.unwrap</span><span class="p">()),</span>
<span class="s">"SpuriousRateLimiterEvent(</span><span class="err">\</span><span class="s">
</span><span class="se">\"</span><span class="s">Rate limiter event handler called without a present timer</span><span class="se">\"</span><span class="s">)"</span>
<span class="p">);</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_new</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">1001</span><span class="p">,</span> <span class="mi">1002</span><span class="p">,</span> <span class="mi">1003</span><span class="p">,</span> <span class="mi">1004</span><span class="p">,</span> <span class="mi">1005</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="k">let</span> <span class="n">bw</span> <span class="o">=</span> <span class="n">l</span><span class="py">.bandwidth</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bw</span><span class="nf">.capacity</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bw</span><span class="nf">.one_time_burst</span><span class="p">(),</span> <span class="mi">1001</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bw</span><span class="nf">.refill_time_ms</span><span class="p">(),</span> <span class="mi">1002</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bw</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">1000</span><span class="p">);</span>
<span class="k">let</span> <span class="n">ops</span> <span class="o">=</span> <span class="n">l</span><span class="py">.ops</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">ops</span><span class="nf">.capacity</span><span class="p">(),</span> <span class="mi">1003</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">ops</span><span class="nf">.one_time_burst</span><span class="p">(),</span> <span class="mi">1004</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">ops</span><span class="nf">.refill_time_ms</span><span class="p">(),</span> <span class="mi">1005</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">ops</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">1003</span><span class="p">);</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_manual_replenish</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// rate limiter with limit of 1000 bytes/s and 1000 ops/s</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// consume 123 bytes</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">123</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="n">l</span><span class="nf">.manual_replenish</span><span class="p">(</span><span class="mi">23</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">);</span>
<span class="p">{</span>
<span class="k">let</span> <span class="n">bytes_tb</span> <span class="o">=</span> <span class="n">l</span><span class="nf">.get_token_bucket</span><span class="p">(</span><span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bytes_tb</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">900</span><span class="p">);</span>
<span class="p">}</span>
<span class="c">// consume 123 ops</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">123</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="n">l</span><span class="nf">.manual_replenish</span><span class="p">(</span><span class="mi">23</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">);</span>
<span class="p">{</span>
<span class="k">let</span> <span class="n">bytes_tb</span> <span class="o">=</span> <span class="n">l</span><span class="nf">.get_token_bucket</span><span class="p">(</span><span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">bytes_tb</span><span class="nf">.budget</span><span class="p">(),</span> <span class="mi">900</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_bandwidth</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// rate limiter with limit of 1000 bytes/s</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// limiter should not be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// raw FD for this disabled should be valid</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.as_raw_fd</span><span class="p">()</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
<span class="c">// ops/s limiter should be disabled so consume(whatever) should work</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="nn">u64</span><span class="p">::</span><span class="nf">max_value</span><span class="p">(),</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// do full 1000 bytes</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// try and fail on another 100</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// since consume failed, limiter should be blocked now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait half the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// limiter should still be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait the other half of the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// the timer_fd should have an event on it by now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_ok</span><span class="p">());</span>
<span class="c">// limiter should now be unblocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// try and succeed on another 100 bytes this time</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_ops</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// rate limiter with limit of 1000 ops/s</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// limiter should not be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// raw FD for this disabled should be valid</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.as_raw_fd</span><span class="p">()</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
<span class="c">// bytes/s limiter should be disabled so consume(whatever) should work</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="nn">u64</span><span class="p">::</span><span class="nf">max_value</span><span class="p">(),</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// do full 1000 ops</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// try and fail on another 100</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// since consume failed, limiter should be blocked now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait half the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// limiter should still be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait the other half of the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// the timer_fd should have an event on it by now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_ok</span><span class="p">());</span>
<span class="c">// limiter should now be unblocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// try and succeed on another 100 ops this time</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_full</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// rate limiter with limit of 1000 bytes/s and 1000 ops/s</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// limiter should not be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// raw FD for this disabled should be valid</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.as_raw_fd</span><span class="p">()</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
<span class="c">// do full 1000 bytes</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// do full 1000 bytes</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// try and fail on another 100 ops</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// try and fail on another 100 bytes</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// since consume failed, limiter should be blocked now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait half the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// limiter should still be blocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// wait the other half of the timer period</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="n">REFILL_TIMER_INTERVAL_MS</span> <span class="o">/</span> <span class="mi">2</span><span class="p">));</span>
<span class="c">// the timer_fd should have an event on it by now</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_ok</span><span class="p">());</span>
<span class="c">// limiter should now be unblocked</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// try and succeed on another 100 ops this time</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Ops</span><span class="p">));</span>
<span class="c">// try and succeed on another 100 bytes this time</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_overconsumption</span><span class="p">()</span> <span class="p">{</span>
<span class="c">// initialize the rate limiter</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// try to consume 2.5x the bucket size</span>
<span class="c">// we are "borrowing" 1.5x the bucket size in tokens since</span>
<span class="c">// the bucket is full</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">2500</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// check that even after a whole second passes, the rate limiter</span>
<span class="c">// is still blocked</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">1000</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_err</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// after 1.5x the replenish time has passed, the rate limiter</span>
<span class="c">// is available again</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">500</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_ok</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// reset the rate limiter</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="c">// try to consume 1.5x the bucket size</span>
<span class="c">// we are "borrowing" 1.5x the bucket size in tokens since</span>
<span class="c">// the bucket is full, should arm the timer to 0.5x replenish</span>
<span class="c">// time, which is 500 ms</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">1500</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// check that after more than the minimum refill time,</span>
<span class="c">// the rate limiter is still blocked</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">200</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_err</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// try to consume some tokens, which should fail as the timer</span>
<span class="c">// is still active</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_err</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="c">// check that after the minimum refill time, the timer was not</span>
<span class="c">// overwritten and the rate limiter is still blocked from the</span>
<span class="c">// borrowing we performed earlier</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">100</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_err</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="c">// after waiting out the full duration, rate limiter should be</span>
<span class="c">// availale again</span>
<span class="nn">thread</span><span class="p">::</span><span class="nf">sleep</span><span class="p">(</span><span class="nn">Duration</span><span class="p">::</span><span class="nf">from_millis</span><span class="p">(</span><span class="mi">200</span><span class="p">));</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.event_handler</span><span class="p">()</span><span class="nf">.is_ok</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="o">!</span><span class="n">l</span><span class="nf">.is_blocked</span><span class="p">());</span>
<span class="k">assert</span><span class="o">!</span><span class="p">(</span><span class="n">l</span><span class="nf">.consume</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="nn">TokenType</span><span class="p">::</span><span class="n">Bytes</span><span class="p">));</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_update_buckets</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="k">mut</span> <span class="n">x</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">2000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="k">let</span> <span class="n">initial_bw</span> <span class="o">=</span> <span class="n">x</span><span class="py">.bandwidth</span><span class="nf">.clone</span><span class="p">();</span>
<span class="k">let</span> <span class="n">initial_ops</span> <span class="o">=</span> <span class="n">x</span><span class="py">.ops</span><span class="nf">.clone</span><span class="p">();</span>
<span class="n">x</span><span class="nf">.update_buckets</span><span class="p">(</span><span class="nn">BucketUpdate</span><span class="p">::</span><span class="nb">None</span><span class="p">,</span> <span class="nn">BucketUpdate</span><span class="p">::</span><span class="nb">None</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.bandwidth</span><span class="p">,</span> <span class="n">initial_bw</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.ops</span><span class="p">,</span> <span class="n">initial_ops</span><span class="p">);</span>
<span class="k">let</span> <span class="n">new_bw</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">123</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">57</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="k">let</span> <span class="n">new_ops</span> <span class="o">=</span> <span class="nn">TokenBucket</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">321</span><span class="p">,</span> <span class="mi">12346</span><span class="p">,</span> <span class="mi">89</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="n">x</span><span class="nf">.update_buckets</span><span class="p">(</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nf">Update</span><span class="p">(</span><span class="n">new_bw</span><span class="nf">.clone</span><span class="p">()),</span>
<span class="nn">BucketUpdate</span><span class="p">::</span><span class="nf">Update</span><span class="p">(</span><span class="n">new_ops</span><span class="nf">.clone</span><span class="p">()),</span>
<span class="p">);</span>
<span class="c">// We have manually adjust the last_update field, because it changes when update_buckets()</span>
<span class="c">// constructs new buckets (and thus gets a different value for last_update). We do this so</span>
<span class="c">// it makes sense to test the following assertions.</span>
<span class="n">x</span><span class="py">.bandwidth</span><span class="nf">.as_mut</span><span class="p">()</span><span class="nf">.unwrap</span><span class="p">()</span><span class="py">.last_update</span> <span class="o">=</span> <span class="n">new_bw</span><span class="py">.last_update</span><span class="p">;</span>
<span class="n">x</span><span class="py">.ops</span><span class="nf">.as_mut</span><span class="p">()</span><span class="nf">.unwrap</span><span class="p">()</span><span class="py">.last_update</span> <span class="o">=</span> <span class="n">new_ops</span><span class="py">.last_update</span><span class="p">;</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.bandwidth</span><span class="p">,</span> <span class="nf">Some</span><span class="p">(</span><span class="n">new_bw</span><span class="p">));</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.ops</span><span class="p">,</span> <span class="nf">Some</span><span class="p">(</span><span class="n">new_ops</span><span class="p">));</span>
<span class="n">x</span><span class="nf">.update_buckets</span><span class="p">(</span><span class="nn">BucketUpdate</span><span class="p">::</span><span class="n">Disabled</span><span class="p">,</span> <span class="nn">BucketUpdate</span><span class="p">::</span><span class="n">Disabled</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.bandwidth</span><span class="p">,</span> <span class="nb">None</span><span class="p">);</span>
<span class="nd">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="py">.ops</span><span class="p">,</span> <span class="nb">None</span><span class="p">);</span>
<span class="p">}</span>
<span class="nd">#[test]</span>
<span class="k">fn</span> <span class="nf">test_rate_limiter_debug</span><span class="p">()</span> <span class="p">{</span>
<span class="k">let</span> <span class="n">l</span> <span class="o">=</span> <span class="nn">RateLimiter</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">();</span>
<span class="nd">assert_eq!</span><span class="p">(</span>
<span class="nd">format!</span><span class="p">(</span><span class="s">"{:?}"</span><span class="p">,</span> <span class="n">l</span><span class="p">),</span>
<span class="nd">format!</span><span class="p">(</span>
<span class="s">"RateLimiter {{ bandwidth: {:?}, ops: {:?} }}"</span><span class="p">,</span>
<span class="n">l</span><span class="nf">.bandwidth</span><span class="p">(),</span>
<span class="n">l</span><span class="nf">.ops</span><span class="p">()</span>
<span class="p">),</span>
<span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div> </div>
</details>
<p>This code sparks joy, doesn’t it? Mostly due to how well it is documented. It starts with an extensive <a href="https://github.com/firecracker-microvm/firecracker/blob/2f92f4a2d189c504aa358928b3ad490aafa61cff/src/rate_limiter/src/lib.rs#L5-L44">doc comment</a> explaining what it does and the overall approach, and then the rest of the implementation is documented in abundant details.</p>
<p>E.g. consider the method below. It would still be rather readable even without comments, but they certainly make understanding it even easier.</p>
<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">/// Attempts to consume `tokens` from the bucket and returns whether the action succeeded.</span>
<span class="k">pub</span> <span class="k">fn</span> <span class="nf">reduce</span><span class="p">(</span><span class="o">&</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="k">mut</span> <span class="n">tokens</span><span class="p">:</span> <span class="nb">u64</span><span class="p">)</span> <span class="k">-></span> <span class="n">BucketReduction</span> <span class="p">{</span>
<span class="c">// First things first: consume the one-time-burst budget.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">></span> <span class="mi">0</span> <span class="p">{</span>
<span class="c">// We still have burst budget for *all* tokens requests.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">>=</span> <span class="n">tokens</span> <span class="p">{</span>
<span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">-=</span> <span class="n">tokens</span><span class="p">;</span>
<span class="k">self</span><span class="py">.last_update</span> <span class="o">=</span> <span class="nn">Instant</span><span class="p">::</span><span class="nf">now</span><span class="p">();</span>
<span class="c">// No need to continue to the refill process, we still have burst budget to consume from.</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c">// We still have burst budget for *some* of the tokens requests.</span>
<span class="c">// The tokens left unfulfilled will be consumed from current `self.budget`.</span>
<span class="n">tokens</span> <span class="o">-=</span> <span class="k">self</span><span class="py">.one_time_burst</span><span class="p">;</span>
<span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.budget</span> <span class="p">{</span>
<span class="c">// Hit the bucket bottom, let's auto-replenish and try again.</span>
<span class="k">self</span><span class="nf">.auto_replenish</span><span class="p">();</span>
<span class="c">// This operation requests a bandwidth higher than the bucket size</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.size</span> <span class="p">{</span>
<span class="nd">error!</span><span class="p">(</span>
<span class="s">"Consumed {} tokens from bucket of size {}"</span><span class="p">,</span>
<span class="n">tokens</span><span class="p">,</span> <span class="k">self</span><span class="py">.size</span>
<span class="p">);</span>
<span class="c">// Empty the bucket and report an overconsumption of</span>
<span class="c">// (remaining tokens / size) times larger than the bucket size</span>
<span class="n">tokens</span> <span class="o">-=</span> <span class="k">self</span><span class="py">.budget</span><span class="p">;</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nf">OverConsumption</span><span class="p">(</span><span class="n">tokens</span> <span class="k">as</span> <span class="nb">f64</span> <span class="o">/</span> <span class="k">self</span><span class="py">.size</span> <span class="k">as</span> <span class="nb">f64</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">if</span> <span class="n">tokens</span> <span class="o">></span> <span class="k">self</span><span class="py">.budget</span> <span class="p">{</span>
<span class="c">// Still not enough tokens, consume() fails, return false.</span>
<span class="k">return</span> <span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Failure</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">self</span><span class="py">.budget</span> <span class="o">-=</span> <span class="n">tokens</span><span class="p">;</span>
<span class="nn">BucketReduction</span><span class="p">::</span><span class="nb">Success</span>
<span class="p">}</span>
</code></pre></div></div>
<p>Can it be rewritten to make some comments redundant? Perhaps something like this:</p>
<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">// First things first: consume the one-time-burst budget.</span>
<span class="k">if</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">></span> <span class="mi">0</span> <span class="p">{</span>
<span class="c">// ...</span>
<span class="p">}</span>
<span class="k">-></span>
<span class="k">let</span> <span class="n">has_remaining_one_time_burst</span> <span class="o">=</span> <span class="k">self</span><span class="py">.one_time_burst</span> <span class="o">></span> <span class="mi">0</span><span class="p">;</span>
<span class="k">if</span> <span class="n">has_remaining_one_time_burst</span> <span class="p">{</span>
<span class="c">// ...</span>
<span class="p">}</span>
</code></pre></div></div>
<p>It is better? I’m not sure.</p>
<p>Some comments might be a little unnecessary, e.g.</p>
<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">// Compute time passed since last refill/update.</span>
<span class="k">let</span> <span class="n">time_delta</span> <span class="o">=</span> <span class="k">self</span><span class="py">.last_update</span><span class="nf">.elapsed</span><span class="p">()</span><span class="nf">.as_nanos</span><span class="p">()</span> <span class="k">as</span> <span class="nb">u64</span><span class="p">;</span>
</code></pre></div></div>
<p>- surely it’s perfectly clear already - but overall they make the code so easy to read.</p>
<h3 id="exhibit-b---protobuf">Exhibit B - <a href="https://github.com/protocolbuffers/protobuf">Protobuf</a></h3>
<p><em>Protocol buffers (Protobuf) are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.</em></p>
<p>Let’s look at Protobuf’s <a href="https://github.com/protocolbuffers/protobuf/blob/8a3c4948a49d3b38effea499fd9dee66f28cb0c4/src/google/protobuf/io/tokenizer.cc">tokenizer</a>. While the entire file is rather well-documented, what really stands out is the top-level comment about what the code does, why it is the way it is, what design alternatives were considered but rejected and why it exists in the first place. Comments like this are invaluable to understanding the code.</p>
<p>The tone of the comments is unusually personal, but I can’t complain. The only concern is if the code is updated by someone else, what should they do about the comments.</p>
<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Here we have a hand-written lexer. At first you might ask yourself,</span>
<span class="c1">// "Hand-written text processing? Is Kenton crazy?!" Well, first of all,</span>
<span class="c1">// yes I am crazy, but that's beside the point. There are actually reasons</span>
<span class="c1">// why I ended up writing this this way.</span>
<span class="c1">//</span>
<span class="c1">// The traditional approach to lexing is to use lex to generate a lexer for</span>
<span class="c1">// you. Unfortunately, lex's output is ridiculously ugly and difficult to</span>
<span class="c1">// integrate cleanly with C++ code, especially abstract code or code meant</span>
<span class="c1">// as a library. Better parser-generators exist but would add dependencies</span>
<span class="c1">// which most users won't already have, which we'd like to avoid. (GNU flex</span>
<span class="c1">// has a C++ output option, but it's still ridiculously ugly, non-abstract,</span>
<span class="c1">// and not library-friendly.)</span>
<span class="c1">//</span>
<span class="c1">// The next approach that any good software engineer should look at is to</span>
<span class="c1">// use regular expressions. And, indeed, I did. I have code which</span>
<span class="c1">// implements this same class using regular expressions. It's about 200</span>
<span class="c1">// lines shorter. However:</span>
<span class="c1">// - Rather than error messages telling you "This string has an invalid</span>
<span class="c1">// escape sequence at line 5, column 45", you get error messages like</span>
<span class="c1">// "Parse error on line 5". Giving more precise errors requires adding</span>
<span class="c1">// a lot of code that ends up basically as complex as the hand-coded</span>
<span class="c1">// version anyway.</span>
<span class="c1">// - The regular expression to match a string literal looks like this:</span>
<span class="c1">// kString = new RE("(\"([^\"\\\\]|" // non-escaped</span>
<span class="c1">// "\\\\[abfnrtv?\"'\\\\0-7]|" // normal escape</span>
<span class="c1">// "\\\\x[0-9a-fA-F])*\"|" // hex escape</span>
<span class="c1">// "\'([^\'\\\\]|" // Also support single-quotes.</span>
<span class="c1">// "\\\\[abfnrtv?\"'\\\\0-7]|"</span>
<span class="c1">// "\\\\x[0-9a-fA-F])*\')");</span>
<span class="c1">// Verifying the correctness of this line noise is actually harder than</span>
<span class="c1">// verifying the correctness of ConsumeString(), defined below. I'm not</span>
<span class="c1">// even confident that the above is correct, after staring at it for some</span>
<span class="c1">// time.</span>
<span class="c1">// - PCRE is fast, but there's still more overhead involved than the code</span>
<span class="c1">// below.</span>
<span class="c1">// - Sadly, regular expressions are not part of the C standard library, so</span>
<span class="c1">// using them would require depending on some other library. For the</span>
<span class="c1">// open source release, this could be really annoying. Nobody likes</span>
<span class="c1">// downloading one piece of software just to find that they need to</span>
<span class="c1">// download something else to make it work, and in all likelihood</span>
<span class="c1">// people downloading Protocol Buffers will already be doing so just</span>
<span class="c1">// to make something else work. We could include a copy of PCRE with</span>
<span class="c1">// our code, but that obligates us to keep it up-to-date and just seems</span>
<span class="c1">// like a big waste just to save 200 lines of code.</span>
<span class="c1">//</span>
<span class="c1">// On a similar but unrelated note, I'm even scared to use ctype.h.</span>
<span class="c1">// Apparently functions like isalpha() are locale-dependent. So, if we used</span>
<span class="c1">// that, then if this code is being called from some program that doesn't</span>
<span class="c1">// have its locale set to "C", it would behave strangely. We can't just set</span>
<span class="c1">// the locale to "C" ourselves since we might break the calling program that</span>
<span class="c1">// way, particularly if it is multi-threaded. WTF? Someone please let me</span>
<span class="c1">// (Kenton) know if I'm missing something here...</span>
<span class="c1">//</span>
<span class="c1">// I'd love to hear about other alternatives, though, as this code isn't</span>
<span class="c1">// exactly pretty.</span>
</code></pre></div></div>
<p>Read more about this piece of code in <a href="/articles/protobuf-tokenizer">our article</a>.</p>
<h3 id="exhibit-c---aws-cli">Exhibit C - <a href="https://github.com/aws/aws-cli">AWS CLI</a></h3>
<p><em>Universal Command Line Interface for Amazon Web Services.</em></p>
<p>This <a href="https://github.com/aws/aws-cli/blob/2f09fcc0e28784affb472d9aa0d3dd2c3ab513de/awscli/shorthand.py">shorthand parser</a> in AWS CLI demonstrates that good comments don’t need to be verbose.</p>
<p>The parser (learn more about it in our <a href="/articles/aws-cli-shorthand-parser">article</a>), which is already quite easy to understand (short methods doing one thing each, good names), is made even more readable by short comments with the expected format of the input in the beginning of most parsing methods. E.g.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">_parameter</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># parameter = keyval *("," keyval)
</span> <span class="n">params</span> <span class="o">=</span> <span class="p">{}</span>
<span class="n">key</span><span class="p">,</span> <span class="n">val</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_keyval</span><span class="p">()</span>
<span class="n">params</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span>
<span class="n">last_index</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_index</span>
<span class="k">while</span> <span class="bp">self</span><span class="p">.</span><span class="n">_index</span> <span class="o"><</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">.</span><span class="n">_input_value</span><span class="p">):</span>
<span class="bp">self</span><span class="p">.</span><span class="n">_expect</span><span class="p">(</span><span class="s">','</span><span class="p">,</span> <span class="n">consume_whitespace</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">key</span><span class="p">,</span> <span class="n">val</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_keyval</span><span class="p">()</span>
<span class="c1"># If a key is already defined, it is likely an incorrectly written
</span> <span class="c1"># shorthand argument. Raise an error to inform the user.
</span> <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">params</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">DuplicateKeyInObjectError</span><span class="p">(</span>
<span class="n">key</span><span class="p">,</span> <span class="bp">self</span><span class="p">.</span><span class="n">_input_value</span><span class="p">,</span> <span class="n">last_index</span> <span class="o">+</span> <span class="mi">1</span>
<span class="p">)</span>
<span class="n">params</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span>
<span class="n">last_index</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_index</span>
<span class="k">return</span> <span class="n">params</span>
<span class="k">def</span> <span class="nf">_keyval</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># keyval = key "=" [values]
</span> <span class="n">key</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_key</span><span class="p">()</span>
<span class="bp">self</span><span class="p">.</span><span class="n">_expect</span><span class="p">(</span><span class="s">'='</span><span class="p">,</span> <span class="n">consume_whitespace</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">values</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">_values</span><span class="p">()</span>
<span class="k">return</span> <span class="n">key</span><span class="p">,</span> <span class="n">values</span>
</code></pre></div></div>
<p><code class="language-plaintext highlighter-rouge"># parameter = keyval *("," keyval)</code> and <code class="language-plaintext highlighter-rouge"># keyval = key "=" [values]</code> really help, don’t they? Even though <code class="language-plaintext highlighter-rouge">_keyval</code> is almost trivial, the comment makes it even clearer.</p>
<h3 id="disclaimer">Disclaimer</h3>
<p>The usual disclaimer: terms like <em>good</em> and <em>helpful</em> are subjective. If you disagree that these code examples are documented well, let’s debate. Leave a comment or <a href="mailto:ainzzorl@gmail.com">shoot me an email</a>.</p>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>Writing Well-Documented Code - Learn from ExamplesNew Article: Displaying Diffs in Jest2021-08-31T18:16:00+00:002021-08-31T18:16:00+00:00https://codecatalog.org/2021/08/31/jest-diff<h2 id="new-article-displaying-diffs-in-jest"><a href="/2021/08/31/jest-diff.html">New Article: Displaying Diffs in Jest</a></h2>
<time datetime="2021-08-31">31 August 2021</time>
<p>A <a href="/articles/jest-diff">new article</a> about displaying diffs in <a href="https://jestjs.io">Jest</a> has been added to the catalog. This is our second article featuring Jest after <a href="/articles/jest-test-sequencer">Jest - Test Sequencer</a>.</p>
<p>We discuss how Jest shows human-readable diffs between the expected and the actual values when test assertions fail. We review the main flow of diffing two JavaScript objects, but not the underlying sequence difference implementation, which is based on the Myers algorithm.</p>
<p>The code is written in TypeScript.</p>
<p><a href="/articles/jest-diff">Jest - Displaying Diffs</a></p>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>New Article: Displaying Diffs in Jest 31 August 2021New Article: Correcting Typos in Ruby with did_you_mean2021-08-26T13:55:00+00:002021-08-26T13:55:00+00:00https://codecatalog.org/2021/08/26/did_you_mean-spell-checking<article>
<h2>
<a href="/2021/08/26/did_you_mean-spell-checking.html">
New Article: Correcting Typos in Ruby with did_you_mean
</a>
</h2>
<time datetime="2021-08-26">26 August 2021</time>
<p>
A <a href="/articles/did_you_mean-spell-checking">new article</a> about using spell-checking to correct typos in Ruby code with <a href="https://github.com/ruby/did_you_mean">did_you_mean</a> gem has been added to the catalog. The whole existence of this gem <a href="(https://news.ycombinator.com/item?id=8496581">sparks controversy</a> about static vs dynamic languages.
</p>
<p>
We also highly recommend listening to the <a href="https://www.youtube.com/watch?v=sca1C0Qk6ZE">gem author's talk</a> about it.
</p>
<p>
<a href="/articles/did_you_mean-spell-checking">did_you_mean - Correcting Typos in Ruby</a>
</p>
</article>
<span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span>New Article: Correcting Typos in Ruby with did_you_mean 26 August 2021New Article: Decorating Artifact Caches in Buck2021-08-13T09:19:00+00:002021-08-13T09:19:00+00:00https://codecatalog.org/2021/08/13/buck-artifact-cache-decorator<article>
<h2>
<a href="/2021/08/13/buck-artifact-cache-decorator.html">
New Article: Decorating Artifact Caches in Buck
</a>
</h2>
<time datetime="2021-08-13">13 August 2021</time>
<p>
A <a href="/articles/buck-artifact-cache-decorators">new article</a> about decorators for artifact caches in <a href="https://buck.build/">Buck</a>, a multi-language build system developed and used by Facebook, has been added to the catalog.
</p>
<p>
The code is written in Java. It uses the classical <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorator</a> design pattern to add behavior to individual cache instances without affecting the behavior of other objects from the same class.
</p>
<p>
<a href="/articles/buck-artifact-cache-decorators">Buck - Artifact Cache Decorators</a>
</p>
</article>
<p><span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span></p>New Article: Decorating Artifact Caches in Buck 13 August 2021New Article: Protocol Buffers Tokenizer2021-08-12T13:44:00+00:002021-08-12T13:44:00+00:00https://codecatalog.org/2021/08/12/protobuf-tokenizer<article>
<h2>
<a href="/2021/08/12/protobuf-tokenizer.html">
New Article: Protocol Buffers Tokenizer
</a>
</h2>
<time datetime="2021-08-12">12 August 2021</time>
<p>
A <a href="/articles/protobuf-tokenizer">new article</a> about tokenizing <a href="https://developers.google.com/protocol-buffers/">Protocol Buffers</a> has been added to the catalog.
</p>
<p>
This code was written in C++ back in 2008, and it's still used very widely at Google and outside. What stands out about it are how thoroughly the design decisions are documented and the personal tone of the comments.
</p>
<p>
<a href="/articles/protobuf-tokenizer">Protocol Buffers - Tokenizer</a>
</p>
</article>
<span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span>New Article: Protocol Buffers Tokenizer 12 August 2021New Article: HTTP Connection Pooling in Puppet2021-08-10T09:11:00+00:002021-08-10T09:11:00+00:00https://codecatalog.org/2021/08/10/puppet-connection-pool<article>
<h2>
<a href="/2021/08/10/puppet-connection-pool.html">
New Article: HTTP Connection Pooling in Puppet
</a>
</h2>
<time datetime="2021-08-10">10 August 2021</time>
<p>
A <a href="/articles/puppet-connection-pool">new article</a> about connection pools in <a href="https://puppet.com/">Puppet</a> has been added to the catalog.
</p>
<p>
The code is written in Ruby. Its goal is to avoid making a new TCP connection and SSL handshake for each request by reusing persistent connections.
</p>
<p>
<a href="/articles/puppet-connection-pool">Puppet - HTTP Connection Pool</a>
</p>
</article>
<span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span>New Article: HTTP Connection Pooling in Puppet 10 August 2021New Article: Test Sequencing in Jest2021-08-09T17:19:00+00:002021-08-09T17:19:00+00:00https://codecatalog.org/2021/08/09/jest-test-sequencer<article>
<h2>
<a href="/2021/08/09/jest-test-sequencer.html">
New Article: Test Sequencing in Jest
</a>
</h2>
<time datetime="2021-08-09">09 August 2021</time>
<p>
A <a href="/articles/jest-test-sequencer">new article</a> about ordering tests in <a href="https://jestjs.io/">Jest</a> has been added to the catalog.
</p>
<p>
The code is written in TypeScript and attempts to improve user-perceived responsiveness and speed of the test run. It's achieved by prioritizing tests that failed during the last run and slower tests.
</p>
<p>
<a href="/articles/jest-test-sequencer">Jest - Test Sequencer</a>
</p>
</article>
<span style="background-color: #ccccff">
<i>
<b>
Help Code Catalog grow: <a href="https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE">suggest</a> your favorite code or weight in on <a href="https://github.com/ainzzorl/goodcode/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+example%22">open article proposals</a>.
</b>
</i>
</span>New Article: Test Sequencing in Jest 09 August 2021