<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>newbmiao</name>
    <email>newbvirgil@gmail.com</email>
  </author>
  <generator uri="https://hexo.io/">Hexo</generator>
  <icon>https://www.gravatar.com/avatar/644a62fb3ee1c60061ebca1d0996b0ae</icon>
  <id>https://newbmiao.github.io/</id>
  <link href="https://newbmiao.github.io/" rel="alternate"/>
  <link href="https://newbmiao.github.io/atom.xml" rel="self"/>
  <rights>All rights reserved 2026, newbmiao</rights>
  <subtitle>start from a newb...(https://newbmiao.github.io)</subtitle>
  <title>newbmiao</title>
  <updated>2026-11-20T07:47:44.000Z</updated>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="devops" scheme="https://newbmiao.github.io/categories/devops/"/>
    <category term="devops" scheme="https://newbmiao.github.io/tags/devops/"/>
    <category term="network" scheme="https://newbmiao.github.io/tags/network/"/>
    <content>
      <![CDATA[<!-- synced-from-wechat: devops-subnets-preview-tool-en.md --><p>If you’ve planned a VNet, you know the drill. Wiki holds the “official” diagram. Excel is where you actually try cuts. IPAM kicks in once people agree on addresses. That’s fine until you need to split a <code>/22</code> three different ways the night before a meeting.</p><p>I just wanted something you could open, chop up, undo, and send to someone—without hunting down who changed which <code>/27</code> two weeks ago.</p><span id="more"></span><h2 id="The-old-standby"><a href="#The-old-standby" class="headerlink" title="The old standby"></a>The old standby</h2><p>I used <a href="https://www.davidc.net/sites/default/subnets/subnets.html">davidc’s Visual Subnet Calculator</a> for a long time. Ugly page, but Divide and Join just click. That’s where a lot of us learned what a <code>/26</code> actually looks like.</p><p>What I missed: names, colors, a proper export, and a file I could drop in git.</p><h2 id="Subnets-Preview-web"><a href="#Subnets-Preview-web" class="headerlink" title="Subnets Preview (web)"></a>Subnets Preview (web)</h2><p>I built a newer one called <strong><a href="https://subnets-preview.pages.dev/">Subnets Preview</a></strong>. Same split&#x2F;join idea, plus:</p><ul><li>Name and color each subnet  </li><li>Export a PNG for Slack or docs  </li><li>Import&#x2F;export JSON so you can stop and come back  </li><li><strong>Copy Link</strong> sends the whole layout (<code>?c=v1…</code>)</li></ul><h2 id="Open-the-JSON-in-your-editor"><a href="#Open-the-JSON-in-your-editor" class="headerlink" title="Open the JSON in your editor"></a>Open the JSON in your editor</h2><p>I save layouts as JSON in the repo. There’s a small VS Code extension with the same name:</p><ul><li><a href="https://marketplace.visualstudio.com/items?itemName=newbmiao.subnets-preview">VS Marketplace</a> (usual install) or <a href="https://open-vsx.org/extension/newbmiao/subnets-preview">Open VSX</a> if you’re on Cursor  </li><li><strong>Subnet: Preview JSON</strong> from the command palette; on Mac, <strong>Ctrl+Cmd+S</strong>  </li><li>Preview in a side pane, reloads when you save, save back to disk, copy link  </li><li>Reads local JSON only. Nothing uploaded, no telemetry</li></ul><h2 id="Then-wire-it-into-IaC"><a href="#Then-wire-it-into-IaC" class="headerlink" title="Then wire it into IaC"></a>Then wire it into IaC</h2><p>I still decide the split myself—which box is apps, DB, what to leave empty. That’s architecture, not guesswork.</p><p>When it looks right, export JSON or a screenshot and write your Terraform or Bicep from that. JSON is nicer if you’re translating line by line. A PNG is fine when you just need to show the map. Check CIDRs, names, delegation, and NSGs before you open a PR.</p><h2 id="Example"><a href="#Example" class="headerlink" title="Example"></a>Example</h2><p>Sample VNet (apps, DB): <strong><a href="https://subnets-preview.pages.dev/?c=v1.fdBBC4JAEAXg__LOo7mjme1tTY_VIesiHoJEorRQCCL67-GqpShdZz7eG-aFAhJiyaZwPdMyLRBySGZCBiksyyZUkHE8NOwSyvQEglopQwljryIk1Feu07BbeSyytJM8IQV7IJ4TQBishK5yxgvuLepYf3yArclEqN32uYTrOU__JYglg3hBqC5PEAJ_wjA7jdE9CeEOid0mjIwgXG8NEB76fYfvSIH6z5yxjfaUOvnn_J7jztVPT5L3Bw">open it</a></strong></p><p><img decoding="async" loading="lazy" src="/images/devops/subnets-preview/example.webp" alt="Sample VNet layout"></p><p>Handy for whiteboarding and screenshots. Push the final numbers to your wiki or IPAM when you’re done.</p>]]>
    </content>
    <id>https://newbmiao.github.io/devops-subnets-preview-tool.html</id>
    <link href="https://newbmiao.github.io/devops-subnets-preview-tool.html"/>
    <published>2026-11-20T02:43:15.000Z</published>
    <summary>A small tool for slicing VNet address space before the meeting, not after.</summary>
    <title>Subnets Preview — plan and split VNet subnets in the browser</title>
    <updated>2026-11-20T07:47:44.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="devops" scheme="https://newbmiao.github.io/categories/devops/"/>
    <category term="terraform" scheme="https://newbmiao.github.io/tags/terraform/"/>
    <content>
      <![CDATA[<p>Something I’ve picked up in ops: <strong>some tech you never learn—and that’s fine.</strong></p><p>Terraform policy used to mean Sentinel or OPA. Different languages, different mental models.</p><p>This year HashiCorp shipped <strong>tfpolicy</strong> to GA. If you already write HCL, the bar to entry is a lot lower.</p><span id="more"></span><h2 id="What-tfpolicy-actually-gates"><a href="#What-tfpolicy-actually-gates" class="headerlink" title="What tfpolicy actually gates"></a>What tfpolicy actually gates</h2><p>It works at three layers: <strong>Provider</strong>, <strong>Module</strong>, and <strong>Resource</strong>. Terraform hands you the context—you’re not reverse-engineering plan JSON by hand.</p><!-- mermaid-export: tfpolicy-phases --><pre class="mermaid">graph LR  subgraph Setup    PP["Provider Policy<br/>source, version"]    MP["Module Policy<br/>source, version"]  end  subgraph Plan    RPp["Resource Policy<br/>attrs in plan"]  end  subgraph Apply    RPa["Resource Policy<br/>attrs after apply"]  end  MP --> RPp --> RPa</pre><table><thead><tr><th>Checks</th><th>Examples</th></tr></thead><tbody><tr><td>Provider source &amp; version</td><td>Pin or allow-list providers</td></tr><tr><td>Module source</td><td>Only org-published or local modules</td></tr><tr><td>Resource attrs</td><td>No anonymous public storage, etc.</td></tr></tbody></table><p><strong>Setup</strong> can fail before providers download. <strong>Plan</strong> and <strong>Apply</strong> each get their own shot at resource rules.</p><p>With Rego I lived in plan export land—walk <code>resource_changes</code>, glue policy to JSON, debug through another layer. tfpolicy at least doesn’t make you a JSON parser first.</p><h2 id="Low-friction-start-official-libs-Agent-Skills"><a href="#Low-friction-start-official-libs-Agent-Skills" class="headerlink" title="Low-friction start: official libs + Agent Skills"></a>Low-friction start: official libs + Agent Skills</h2><p>HashiCorp also pushed <a href="https://github.com/hashicorp/agent-skills/tree/main/plugins/terraform/skills">Terraform Agent Skills</a>. Writing rules got cheaper. (AI tokens: yeah, not my bill.)</p><p>The <strong>terraform-policy</strong> skill can:</p><ul><li>Draft <code>.policy.hcl</code> from a plain-English ask</li><li>Write and tune <code>.policytest.hcl</code></li><li>Migrate Sentinel → Terraform Policy</li><li>Move whole policy repos</li></ul><p>Heavier lifting splits into <strong>tfpolicy-author</strong> and <strong>tfpolicy-test</strong>.</p><p>Describe what you want and hand it to the agent. For example:</p><blockquote><p>Write an Azure policy: Storage Accounts must block anonymous public access, with positive and negative policy tests.</p></blockquote><p>You still run <code>tfpolicy validate</code> and <code>tfpolicy test</code> on whatever comes back.</p><p>What to block and who approves exceptions—that’s still on you.</p><p>You don’t have to start from zero. The <a href="https://github.com/hashicorp/prewritten-terraform-policy-library">Pre-written Terraform Policy Library</a> has a pile of ready-made rules:</p><table><thead><tr><th>Cloud</th><th>Policies</th></tr></thead><tbody><tr><td>AWS</td><td>423</td></tr><tr><td>Azure</td><td>82</td></tr><tr><td>GCP</td><td>68</td></tr></tbody></table><p>The Azure set tracks CIS Microsoft Azure Foundations 6.0.0—storage, SQL, Key Vault, networking, IAM, the usual suspects.</p><p>Run the official pack first, add custom rules where you need them. (Other clouds: you’re mostly on your own—fair warning.)</p><p>Convenient now. Painful to remember when OPA was the default. Two war stories:</p><h2 id="Pain-1-policy-queue-ate-my-pipeline"><a href="#Pain-1-policy-queue-ate-my-pipeline" class="headerlink" title="Pain 1: policy queue ate my pipeline"></a>Pain 1: policy queue ate my pipeline</h2><p>On Terraform Cloud, more workspaces means more plans—and then <strong>Policy Evaluation</strong> in line.</p><p>Busy day, a bunch of repos firing at once. Plan’s done; Bitbucket still waits. Everyone’s stuck behind the OPA queue.</p><p>You open TFC later and half of them already finished—they just never made it back to Bitbucket in time.</p><p>Now you can run tfpolicy in CI without waiting on TFC’s policy step for everything:</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">tfpolicy validate --policies=policies/</span><br><span class="line">tfpolicy <span class="built_in">test</span> --policies=policies/</span><br></pre></td></tr></table></figure><h2 id="Pain-2-blocking-a-provider-source-meant-chewing-plan-JSON"><a href="#Pain-2-blocking-a-provider-source-meant-chewing-plan-JSON" class="headerlink" title="Pain 2: blocking a provider source meant chewing plan JSON"></a>Pain 2: blocking a provider source meant chewing plan JSON</h2><p>Alicloud had two provider addresses for a while: old <code>hashicorp/alicloud</code>, current <code>aliyun/alicloud</code>. Skip the block and Terraform defaults to the legacy one.</p><p>Mix sources and <code>required_providers</code> fights you. Plans spam deprecation warnings; from China the registry pain is its own thing.</p><p>OPA meant digging <code>resource_changes</code> and <code>configuration.provider_config</code>. Rego can do it—eventually.</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><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">package terraform</span><br><span class="line"></span><br><span class="line">import rego.v1</span><br><span class="line"></span><br><span class="line">deny contains msg if &#123;</span><br><span class="line">    some resource in input.resource_changes</span><br><span class="line">    resource.provider_name == &quot;registry.terraform.io/hashicorp/alicloud&quot;</span><br><span class="line">    msg = sprintf(&quot;Resource &#x27;%s&#x27; uses invalid provider.&quot;, [resource.address])</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">deny contains msg if &#123;</span><br><span class="line">    some i</span><br><span class="line">    input.configuration.provider_config[i].full_name ==</span><br><span class="line">        &quot;registry.terraform.io/hashicorp/alicloud&quot;</span><br><span class="line">    msg = sprintf(&quot;Provider config &#x27;%s&#x27; uses invalid provider.&quot;, [i])</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Same rule in tfpolicy: watch provider metadata. <strong>Setup</strong> goes red before you waste a plan.</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><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">policy &#123;</span><br><span class="line">  required_providers &#123;</span><br><span class="line">    alicloud = &#123;</span><br><span class="line">      source = &quot;aliyun/alicloud&quot;</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">provider_policy &quot;alicloud&quot; &quot;approved_source&quot; &#123;</span><br><span class="line">  enforce &#123;</span><br><span class="line">    condition     = meta.source == &quot;registry.terraform.io/aliyun/alicloud&quot;</span><br><span class="line">    error_message = &quot;Only aliyun/alicloud is allowed. Migrate off hashicorp/alicloud.&quot;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>So: learn tfpolicy early if you care, or… maybe you never needed to learn the old stack at all.</p><hr><p><strong>Links</strong></p><ul><li><a href="https://www.hashicorp.com/en/blog/introducing-tfpolicy-a-declarative-policy-workflow-built-for-terraform">Introducing tfpolicy</a></li><li><a href="https://github.com/hashicorp/agent-skills/tree/main/plugins/terraform/skills">Terraform Agent Skills</a></li><li><a href="https://github.com/hashicorp/prewritten-terraform-policy-library">Pre-written Terraform Policy Library</a></li><li><a href="https://developer.hashicorp.com/terraform/policy">Terraform Policy Documentation</a></li></ul>]]>
    </content>
    <id>https://newbmiao.github.io/terraform-with-tfpolicy.html</id>
    <link href="https://newbmiao.github.io/terraform-with-tfpolicy.html"/>
    <published>2026-11-17T06:25:44.000Z</published>
    <summary>tfpolicy GA, Agent Skills, and why I’m glad I’m not writing Rego for plan JSON anymore.</summary>
    <title>Terraform tfpolicy vs Sentinel and OPA for plan-time policy checks</title>
    <updated>2026-11-20T05:15:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="devops" scheme="https://newbmiao.github.io/categories/devops/"/>
    <category term="terraform" scheme="https://newbmiao.github.io/tags/terraform/"/>
    <content>
      <![CDATA[<blockquote><p>Nothing is fixed. It depends when and where.</p></blockquote><p>I’ve watched DevOps engineers <strong>hate</strong> on Terraform and I’ve watched others treat it like scripture.</p><p>Debating an IaC tool without context is pointless—like arguing whether coffee is good based on someone else’s hangover.</p><p>Still, a Reddit thread on clickops vs IaC nudged me to write down how I think about Terraform <strong>as an ops person</strong> right now.</p><p>I first touched Terraform on an AWS project in 2019. Declaring infra in code felt like cheating in the best way.</p><p>I was mostly dev then, but everything after that gravitated toward Terraform—Aliyun, GCP, Azure, the whole tour.</p><p>Before the nice parts, here’s what I keep hearing from people actually running platforms.</p><span id="more"></span><h2 id="“Just-click-it-in-the-console”"><a href="#“Just-click-it-in-the-console”" class="headerlink" title="“Just click it in the console”"></a>“Just click it in the console”</h2><p>Clickops is still the default everywhere. Console UI, done.</p><p>You want me to learn HCL, wire CI, and babysit modules for the same outcome?</p><p>Even if I bite that bullet—who gets the time back? How much of that work <strong>reuses</strong> on the next project?</p><p>“Efficiency” is a hard sell when the saved hours aren’t mine. Fair point.</p><h2 id="“The-cloud’s-Terraform-story-is-half-baked”"><a href="#“The-cloud’s-Terraform-story-is-half-baked”" class="headerlink" title="“The cloud’s Terraform story is half-baked”"></a>“The cloud’s Terraform story is half-baked”</h2><p>Don’t tell me you’ve never tried IaC on a newer cloud whose API feels like a first draft. Is the provider team even on speaking terms with the product team?</p><p>You start proud with resources in code. Provider bumps a version and suddenly you’re debugging upstream, opening tickets, watching issue threads.</p><p>Half the resource types aren’t in the provider anyway. So you maintain a runbook: what’s code, what’s manual, what’s “manual until the provider catches up”—and the docs lag reality by a quarter.</p><p>Some clouds at least give you an escape hatch (REST API provider, generic whatever). Others? Good luck.</p><h2 id="“The-pile-never-shrinks”"><a href="#“The-pile-never-shrinks”" class="headerlink" title="“The pile never shrinks”"></a>“The pile never shrinks”</h2><p>I’ve run pipelines with <strong>thousands</strong> of resources. Modules let app teams add more. They rarely volunteer to <strong>remove</strong> stuff.</p><p>The state file keeps growing. Plans get slower. Splitting state helps a symptom, not the culture.</p><p>Modules are work. Provider bugs become multi-resource incidents. Terraform didn’t magically make <strong>governance</strong> someone else’s problem.</p><h2 id="“I’m-the-only-one-using-it”"><a href="#“I’m-the-only-one-using-it”" class="headerlink" title="“I’m the only one using it”"></a>“I’m the only one using it”</h2><p>Worst case: you’re all-in on Terraform; everyone else clicks or runs one-off scripts they like better.</p><p>You preach modules. They nod. They keep doing what works for them.</p><p>Drift is the punchline. Someone edits “your” resource in the console. State lies. You find out in a 2 a.m. diff. Can’t really blame only them—you both live in the same account.</p><h2 id="“Why-not-let-AI-click-for-me-”"><a href="#“Why-not-let-AI-click-for-me-”" class="headerlink" title="“Why not let AI click for me?”"></a>“Why not let AI click for me?”</h2><p>We’re in the era where a model can spit out Terraform—or <strong>call the cloud APIs and CLIs directly</strong>.</p><p>Feels instant. No console, sometimes no pipeline.</p><p>Worried it’ll go rogue? Have it write a small script instead. Still automation.</p><p>Platform-wide reuse, guardrails, audit trail—“we’ll add that when we need it.” Maybe. Most teams aren’t there yet.</p><blockquote><p>Side note: Predictive text will embarrass you in any language. I once fat-fingered an idiom in a draft title and missed it until the second read. (Guilty.)</p></blockquote><hr><p>If any of this sounds familiar, you already know the punchline.</p><p>Terraform isn’t the problem. <strong>Whether you have the org conditions to run it</strong>—and whether anyone will keep governing it—is.</p><p>If you’re still happily on Terraform today, honestly, congrats. That’s a decent place to be.</p>]]>
    </content>
    <id>https://newbmiao.github.io/does-terraform-matter-to-devops.html</id>
    <link href="https://newbmiao.github.io/does-terraform-matter-to-devops.html"/>
    <published>2026-11-14T02:51:01.000Z</published>
    <summary>Clickops, bad providers, state drift—and when Terraform is still worth it.</summary>
    <title>Is Terraform still worth using for DevOps in 2026?</title>
    <updated>2026-11-20T05:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="devops" scheme="https://newbmiao.github.io/categories/devops/"/>
    <category term="terraform" scheme="https://newbmiao.github.io/tags/terraform/"/>
    <content>
      <![CDATA[<p>I’ve been neck-deep in DevOps lately, and one thing keeps coming back: <strong>Infrastructure as Code reads better when it’s boring.</strong></p><p>Let me show you what I mean—one migration, two ways to wire it.</p><p>Say you’ve got several networks in one account and you want each VPC living in its own account going forward.</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><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"># network.auto.tfvars</span><br><span class="line">vpcs = &#123;</span><br><span class="line">  network1 = &#123;</span><br><span class="line">    name = &quot;vpc-1&quot;</span><br><span class="line">  &#125;</span><br><span class="line">  network2 = &#123;</span><br><span class="line">    name = &quot;vpc-2&quot;</span><br><span class="line">  &#125;</span><br><span class="line">  network3 = &#123;</span><br><span class="line">    name = &quot;vpc-3&quot;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>You’ll reuse a <code>module</code> per account. Fair.</p><p>And no, you can’t dynamically pick a <code>provider</code> at runtime—Terraform doesn’t do that.</p><p>The real question is how you <strong>shard</strong> that <code>vpcs</code> map so each module gets the right slice.</p><p>Two patterns I’ve seen a lot of teams reach for:</p><span id="more"></span><h2 id="Option-1-group-in-code"><a href="#Option-1-group-in-code" class="headerlink" title="Option 1: group in code"></a>Option 1: group in code</h2><p>Tag every VPC with an <code>acct_key</code>, then let locals do the grouping.</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><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></pre></td><td class="code"><pre><span class="line"># network.auto.tfvars</span><br><span class="line">vpcs = &#123;</span><br><span class="line">  network1 = &#123;</span><br><span class="line">    acct_key = &quot;a&quot;</span><br><span class="line">    name     = &quot;vpc-1&quot;</span><br><span class="line">  &#125;</span><br><span class="line">  network2 = &#123;</span><br><span class="line">    acct_key = &quot;a&quot;</span><br><span class="line">    name     = &quot;vpc-2&quot;</span><br><span class="line">  &#125;</span><br><span class="line">  network3 = &#123;</span><br><span class="line">    acct_key = &quot;b&quot;</span><br><span class="line">    name     = &quot;vpc-3&quot;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">## main.tf</span><br><span class="line">locals &#123;</span><br><span class="line">  # group by acct_key</span><br><span class="line">  grouped_networks_as_array = &#123;</span><br><span class="line">    for k, v in var.vpcs :</span><br><span class="line">    v.acct_key =&gt; &#123; &quot;$&#123;k&#125;&quot; = v &#125;...</span><br><span class="line">  &#125;</span><br><span class="line">  grouped_networks_as_object = &#123;</span><br><span class="line">    for k, v in local.grouped_networks_as_array :</span><br><span class="line">    k =&gt; merge(&#123;&#125;, v...)</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">output &quot;group_result&quot; &#123;</span><br><span class="line">  value = local.grouped_networks_as_object</span><br><span class="line">&#125;</span><br><span class="line">provider &quot;external&quot; &#123;</span><br><span class="line">  alias = &quot;acct_a&quot;</span><br><span class="line">&#125;</span><br><span class="line">provider &quot;external&quot; &#123;</span><br><span class="line">  alias = &quot;acct_b&quot;</span><br><span class="line">&#125;</span><br><span class="line">module &quot;acct_a_vpcs_1&quot; &#123;</span><br><span class="line">  source = &quot;./vpc&quot;</span><br><span class="line">  vpcs   = local.grouped_networks_as_object.a</span><br><span class="line">  providers = &#123;</span><br><span class="line">    external = external.acct_a</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line">module &quot;acct_b_vpcs_1&quot; &#123;</span><br><span class="line">  source = &quot;./vpc&quot;</span><br><span class="line">  vpcs   = local.grouped_networks_as_object.b</span><br><span class="line">  providers = &#123;</span><br><span class="line">    external = external.acct_b</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>You need two <code>for</code> expressions because Terraform’s native <code>...</code> merge gives you <strong>arrays</strong> keyed the same way; what you want is one <strong>object</strong> per account so you can still do <code>module.acct_a_vpcs.vpcs.network1</code> on outputs.</p><p>Plan output looks like:</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><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">+ group_result = &#123;</span><br><span class="line">    + a = &#123;</span><br><span class="line">        + network1 = &#123;</span><br><span class="line">            + acct_key = &quot;a&quot;</span><br><span class="line">            + name     = &quot;vpc-1&quot;</span><br><span class="line">        &#125;</span><br><span class="line">        + network2 = &#123;</span><br><span class="line">            + acct_key = &quot;a&quot;</span><br><span class="line">            + name     = &quot;vpc-2&quot;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">    + b = &#123;</span><br><span class="line">        + network3 = &#123;</span><br><span class="line">            + acct_key = &quot;b&quot;</span><br><span class="line">            + name     = &quot;vpc-3&quot;</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>Classic engineer move: config barely changes, locals eat the complexity. Ship it.</p><p>…except there’s a second way.</p><h2 id="Option-2-group-in-config"><a href="#Option-2-group-in-config" class="headerlink" title="Option 2: group in config"></a>Option 2: group in config</h2><p>Structure the vars file the way the accounts actually look.</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><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"># network.auto.tfvars</span><br><span class="line">accounts = &#123;</span><br><span class="line">  acct_a = &#123;</span><br><span class="line">    vpcs = &#123;</span><br><span class="line">      network1 = &#123;</span><br><span class="line">        name = &quot;vpc-1&quot;</span><br><span class="line">      &#125;</span><br><span class="line">      network2 = &#123;</span><br><span class="line">        name = &quot;vpc-2&quot;</span><br><span class="line">      &#125;</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">  acct_b = &#123;</span><br><span class="line">    vpcs = &#123;</span><br><span class="line">      network3 = &#123;</span><br><span class="line">        name = &quot;vpc-3&quot;</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>Wiring is almost insultingly clear:</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><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">module &quot;acct_a_vpcs&quot; &#123;</span><br><span class="line">  source = &quot;./vpc&quot;</span><br><span class="line">  vpcs   = var.accounts.acct_a.vpcs</span><br><span class="line">  providers = &#123;</span><br><span class="line">    external = external.acct_a</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">module &quot;acct_b_vpcs&quot; &#123;</span><br><span class="line">  source = &quot;./vpc&quot;</span><br><span class="line">  vpcs   = var.accounts.acct_b.vpcs</span><br><span class="line">  providers = &#123;</span><br><span class="line">    external = external.acct_b</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Both get the job done. For day-to-day ops I’d take option two every time: less HCL to squint at, grouping lives where humans already think in accounts.</p><p>IaC should be <strong>obvious on a tired Friday</strong>, not a puzzle you cracked once in a PR review.</p><p>Clever locals have their place—like merging module outputs when something cross-account needs a flat map of VPC IDs or route table IDs:</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></pre></td><td class="code"><pre><span class="line">locals &#123;</span><br><span class="line">  combined_acct_vpcs = merge(</span><br><span class="line">    module.acct_a_vpcs.vpcs,</span><br><span class="line">    module.acct_b_vpcs.vpcs</span><br><span class="line">  )</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>That’s the kind of abstraction I’d keep. The rest? I’d rather duplicate a line in tfvars than maintain a grouping algorithm nobody remembers.</p>]]>
    </content>
    <id>https://newbmiao.github.io/iac-loves-simple.html</id>
    <link href="https://newbmiao.github.io/iac-loves-simple.html"/>
    <published>2024-08-17T06:42:25.000Z</published>
    <summary>When splitting VPCs across accounts, boring Terraform beats clever locals.</summary>
    <title>Terraform VPC splits across accounts — simple HCL beats clever locals</title>
    <updated>2026-11-20T05:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="tool" scheme="https://newbmiao.github.io/categories/tool/"/>
    <category term="web3" scheme="https://newbmiao.github.io/tags/web3/"/>
    <content>
      <![CDATA[<p>I ran into Fluence’s FLT-DROP: an airdrop for people who actually shipped Web3 code. When I wrote this it was worth on the order of <strong>$600</strong>.</p><p>Nothing earth-shattering if you live in Web3, but fun for a part-time dabbler — I poked at ICP and put together a small <a href="https://github.com/NewbMiao/dvote">on-chain voting repo</a>, which was enough to count.</p><p>Here is how I claimed it (first real Web3 wallet for me; picking the wrong chain for fees was painful).</p><span id="more"></span><h2 id="Connect-a-wallet"><a href="#Connect-a-wallet" class="headerlink" title="Connect a wallet"></a>Connect a wallet</h2><p>Open <a href="https://claim.fluence.network/">https://claim.fluence.network/</a> and connect a Web3 wallet.</p><p>Browser extension wallets are the easy path. If you are starting fresh, create one and <strong>write down the seed phrase</strong> — it is the root of everything.</p><p>You need enough ETH on mainnet for gas when you claim — think <strong>roughly $2</strong> in ETH at typical prices (often a bit more depending on network fees).</p><p><img decoding="async" loading="lazy" src="/images/web3/connect-wallet.webp" alt="OKX Wallet connect screen"></p><p>I used OKX Wallet because topping up was straightforward for me. It worked end-to-end. If you need an exchange onboarding link: <a href="https://www.cnouyi.studio/join/8589760">OKX sign-up</a> (referral; new users sometimes get promo boxes — your mileage may vary).</p><h2 id="Check-eligibility"><a href="#Check-eligibility" class="headerlink" title="Check eligibility"></a>Check eligibility</h2><p>Enter your GitHub username on the site, or search the published <a href="https://claim.fluence.network/static/media/github-accounts.579a238639e5f9da5fd0.txt">GitHub allowlist</a>.</p><p>If you qualify, the drop was <strong>2500 FLT</strong> when I claimed (started at 5000 FLT and halves every three months).</p><h2 id="Submit-proof"><a href="#Submit-proof" class="headerlink" title="Submit proof"></a>Submit proof</h2><p>Proof runs locally: a command shows you control the GitHub account. It uses your SSH key on disk — standard pattern. Skim the tooling and, if you want background, <a href="https://foresightnews.pro/article/detail/55623">this write-up</a>.</p><h2 id="Claim-the-drop"><a href="#Claim-the-drop" class="headerlink" title="Claim the drop"></a>Claim the drop</h2><p>The claim transaction is sent on <strong>Ethereum mainnet</strong> and credits FLT-DROP to your ETH address.</p><blockquote><p>FLT-DROP is <strong>locked for about two months</strong> before you can convert and trade FLT.</p></blockquote><p>If the wallet is short on ETH, the UI tells you to top up. Gas has been anywhere from about <strong>$2 to $6</strong> for me; my claim was under $2. Pick a quiet gas window if you can.</p><h2 id="Top-up-ETH"><a href="#Top-up-ETH" class="headerlink" title="Top up ETH"></a>Top up ETH</h2><p>The annoying part: an empty ETH wallet. I bought via OKX <strong>C2C quick buy</strong>, then <strong>withdrew</strong> to my wallet address.</p><p>Both steps charge fees — budget so the amount arriving on-chain still covers claim gas.</p><p><img decoding="async" loading="lazy" src="/images/web3/deposit.webp" alt="OKX withdraw screen with minimum amount"></p><blockquote><p>In the screenshot market, withdraw needs at least <strong>0.01054</strong> ETH on the books; after the <strong>0.00054</strong> fee you land <strong>0.01</strong> ETH. The FLT claim does not need all of that, but the exchange minimum still applies — you may need to fund <strong>0.01054</strong> or more.</p></blockquote><p>Withdraw on <strong>ETH-ERC20 (Ethereum mainnet)</strong>. FLT-DROP is claimed on mainnet. (I learned the hard way: I once sent to <strong>X Layer</strong> to save fees, then had to fund <strong>OKB</strong> and bounce funds back through OKX.)</p><h2 id="Done"><a href="#Done" class="headerlink" title="Done"></a>Done</h2><p>After that, the claim went through. Wait out the lock, then see what FLT is worth.</p><blockquote><p>After unlock, convert via the official tool: <a href="https://claim.fluence.network/claim-flt">https://claim.fluence.network/claim-flt</a></p></blockquote><p>Side note: Fluence’s Web3 stack supports <strong>Rust</strong> — you can <a href="https://fluence.dev/docs/build/quickstarts/your_first_function">spin up a cloud function</a> without much ceremony if you want to play with the platform.</p><p><img decoding="async" loading="lazy" src="/images/web3/flt-done.webp" alt="FLT claim success screen"></p>]]>
    </content>
    <id>https://newbmiao.github.io/flt-dev-rewards.html</id>
    <link href="https://newbmiao.github.io/flt-dev-rewards.html"/>
    <published>2024-07-20T00:59:22.000Z</published>
    <summary>GitHub eligibility on claim.fluence.network, proof CLI, ETH mainnet gas, and OKX top-up gotchas.</summary>
    <title>Fluence FLT drop — claim guide for eligible GitHub Web3 devs</title>
    <updated>2026-11-20T13:10:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="arc-swap" scheme="https://newbmiao.github.io/tags/arc-swap/"/>
    <content>
      <![CDATA[<p>In Rust, config that threads read while another thread updates it often shows up as <code>Arc&lt;RwLock&lt;T&gt;&gt;</code>. You can also reach for <code>arc-swap</code>. What’s the difference?</p><p>Typical shape: one thread updates config while others keep reading—they should see the new snapshot without restarting the process.</p><span id="more"></span><h2 id="RwLock"><a href="#RwLock" class="headerlink" title="RwLock"></a>RwLock</h2><p>First implementation with <code>RwLock</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::&#123;Arc, RwLock&#125;;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"><span class="keyword">use</span> std::time::Duration;</span><br><span class="line"></span><br><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> <span class="variable">config</span> = Arc::<span class="title function_ invoke__">new</span>(RwLock::<span class="title function_ invoke__">new</span>(<span class="string">&quot;Initial Config&quot;</span>.<span class="title function_ invoke__">to_string</span>()));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">shared_config</span> = Arc::<span class="title function_ invoke__">clone</span>(&amp;config);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">reader_thread</span> = &#123;</span><br><span class="line">        thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || <span class="keyword">loop</span> &#123;</span><br><span class="line">            <span class="comment">// 1. read config</span></span><br><span class="line">            <span class="keyword">let</span> <span class="variable">current_config</span> = shared_config.<span class="title function_ invoke__">read</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;Reader thread: &#123;&#125;&quot;</span>, *current_config);</span><br><span class="line">            thread::<span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">2</span>));</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">// Update the configuration after 1s</span></span><br><span class="line">    thread::<span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">1</span>));</span><br><span class="line"></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Updating config&quot;</span>);</span><br><span class="line">    <span class="comment">// 2. write config</span></span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">current_config</span> = config.<span class="title function_ invoke__">write</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    *current_config = <span class="string">&quot;Updated Config&quot;</span>.<span class="title function_ invoke__">to_string</span>();</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Updating config done&quot;</span>);</span><br><span class="line">    reader_thread.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Run it and you may see the reader stuck on the old config — and <code>&quot;Updating config done&quot;</code> never prints. Why?</p><p>This is a deliberate footgun: a read guard keeps the lock held. More readers can pile on, but no writer can take the lock until every read guard is dropped.</p><p>Scope the guards so they release before you write:</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="comment">// 1. read config</span></span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">current_config</span> = shared_config.<span class="title function_ invoke__">read</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Reader thread: &#123;&#125;&quot;</span>, *current_config);</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">...</span><br><span class="line"><span class="comment">// 2. write config</span></span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">current_config</span> = config.<span class="title function_ invoke__">write</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    *current_config = <span class="string">&quot;Updated Config&quot;</span>.<span class="title function_ invoke__">to_string</span>();</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Updating config done&quot;</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Then you get what you expect:</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></pre></td><td class="code"><pre><span class="line">Reader thread: Initial Config</span><br><span class="line">Updating config</span><br><span class="line">Updating config done</span><br><span class="line">Reader thread: Updated Config</span><br><span class="line">...</span><br></pre></td></tr></table></figure><h2 id="arc-swap"><a href="#arc-swap" class="headerlink" title="arc-swap"></a>arc-swap</h2><p>With <code>RwLock</code>, you have to think about how long you hold locks. Reads and writes are not one atomic step, so the code is easier to get wrong and deadlock.</p><p><code>arc-swap</code> is aimed at that pain: swap the whole <code>Arc</code> atomically so readers and writers do not fight over a lock guard lifecycle.</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> arc_swap::ArcSwap;</span><br><span class="line"><span class="keyword">use</span> std::sync::Arc;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"><span class="keyword">use</span> std::time::Duration;</span><br><span class="line"></span><br><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> <span class="variable">config</span> = Arc::<span class="title function_ invoke__">new</span>(<span class="string">&quot;Initial Config&quot;</span>.<span class="title function_ invoke__">to_string</span>());</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">shared_config</span> = Arc::<span class="title function_ invoke__">new</span>(ArcSwap::<span class="title function_ invoke__">new</span>(config));</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">reader_thread</span> = &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">shared_config</span> = Arc::<span class="title function_ invoke__">clone</span>(&amp;shared_config);</span><br><span class="line">        thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || <span class="keyword">loop</span> &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">current_config</span> = shared_config.<span class="title function_ invoke__">load</span>();</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;Reader thread: &#123;&#125;&quot;</span>, current_config);</span><br><span class="line">            thread::<span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">1</span>));</span><br><span class="line">        &#125;)</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_secs</span>(<span class="number">2</span>));</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">new_config</span> = Arc::<span class="title function_ invoke__">new</span>(<span class="string">&quot;Updated Config&quot;</span>.<span class="title function_ invoke__">to_string</span>());</span><br><span class="line">    shared_config.<span class="title function_ invoke__">store</span>(new_config);</span><br><span class="line"></span><br><span class="line">    reader_thread.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The flow is more direct. For read-mostly, occasionally-updated data, <code>arc-swap</code> is often worth trying.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-arc-swap.html</id>
    <link href="https://newbmiao.github.io/rust-arc-swap.html"/>
    <published>2024-05-31T10:08:39.000Z</published>
    <summary>Read-heavy config with a background updater — when RwLock deadlocks on held read guards, and how ArcSwap fixes it.</summary>
    <title>arc-swap — atomic Arc swaps vs RwLock for config</title>
    <updated>2026-11-20T12:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="sealed-trait" scheme="https://newbmiao.github.io/tags/sealed-trait/"/>
    <content>
      <![CDATA[<p>The <a href="/rust-sealed-trait.html">first sealed-trait post</a> showed the mechanic in isolation. Here is why it shows up in <a href="https://github.com/ramosbugs/oauth2-rs">oauth2-rs</a>: <strong>endpoint state</strong> in the client API. That design only works if callers cannot add their own state types.</p><span id="more"></span><p>Reuse the previous example, wrapped in <code>mod oauth</code> to mimic a library surface:</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">mod</span> oauth &#123;</span><br><span class="line">    <span class="keyword">use</span> std::marker::PhantomData;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">EndointSet</span> &#123;&#125;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">EndpointNotSet</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">EndpointState</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">impl</span> <span class="title class_">EndpointState</span> <span class="keyword">for</span> <span class="title class_">EndointSet</span> &#123;&#125;</span><br><span class="line">    <span class="keyword">impl</span> <span class="title class_">EndpointState</span> <span class="keyword">for</span> <span class="title class_">EndpointNotSet</span> &#123;&#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_">Client</span>&lt;HasAuthUrl = EndpointNotSet, HasTokenUrl = EndpointNotSet&gt;</span><br><span class="line">    <span class="keyword">where</span></span><br><span class="line">        HasAuthUrl: EndpointState,</span><br><span class="line">        HasTokenUrl: EndpointState,</span><br><span class="line">    &#123;</span><br><span class="line">        auth_url: <span class="type">Option</span>&lt;<span class="type">String</span>&gt;,</span><br><span class="line">        token_url: <span class="type">Option</span>&lt;<span class="type">String</span>&gt;,</span><br><span class="line">        phantom: std::marker::PhantomData&lt;(HasAuthUrl, HasTokenUrl)&gt;,</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">impl</span>&lt;HasAuthUrl: EndpointState, HasTokenUrl: EndpointState&gt; Client&lt;HasAuthUrl, HasTokenUrl&gt; &#123;</span><br><span class="line">        <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">new</span>() <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123;</span><br><span class="line">            Client &#123;</span><br><span class="line">                auth_url: <span class="literal">None</span>,</span><br><span class="line">                token_url: <span class="literal">None</span>,</span><br><span class="line">                phantom: PhantomData,</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">pub</span> <span class="keyword">fn</span> <span class="title function_">set_auth_url</span>(<span class="keyword">self</span>, auth_url: &amp;<span class="type">str</span>) <span class="punctuation">-&gt;</span> Client&lt;EndointSet, HasTokenUrl&gt; &#123;</span><br><span class="line">            Client &#123;</span><br><span class="line">                auth_url: <span class="title function_ invoke__">Some</span>(auth_url.<span class="title function_ invoke__">to_string</span>()),</span><br><span class="line">                token_url: <span class="keyword">self</span>.token_url,</span><br><span class="line">                phantom: PhantomData,</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">pub</span> <span class="keyword">fn</span> <span class="title function_">set_token_url</span>(<span class="keyword">self</span>, token_url: &amp;<span class="type">str</span>) <span class="punctuation">-&gt;</span> Client&lt;HasAuthUrl, EndointSet&gt; &#123;</span><br><span class="line">            Client &#123;</span><br><span class="line">                auth_url: <span class="keyword">self</span>.auth_url,</span><br><span class="line">                token_url: <span class="title function_ invoke__">Some</span>(token_url.<span class="title function_ invoke__">to_string</span>()),</span><br><span class="line">                phantom: PhantomData,</span><br><span class="line">            &#125;</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">impl</span>&lt;HasTokenUrl: EndpointState&gt; Client&lt;EndointSet, HasTokenUrl&gt; &#123;</span><br><span class="line">        <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">get_auth_url</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> &amp;<span class="type">str</span> &#123;</span><br><span class="line">            <span class="keyword">self</span>.auth_url.<span class="title function_ invoke__">as_ref</span>().<span class="title function_ invoke__">unwrap</span>()</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">impl</span>&lt;HasAuthUrl: EndpointState&gt; Client&lt;HasAuthUrl, EndointSet&gt; &#123;</span><br><span class="line">        <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">get_token_url</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> &amp;<span class="type">str</span> &#123;</span><br><span class="line">            <span class="keyword">self</span>.token_url.<span class="title function_ invoke__">as_ref</span>().<span class="title function_ invoke__">unwrap</span>()</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><h2 id="The-hack"><a href="#The-hack" class="headerlink" title="The hack"></a>The hack</h2><p>Without sealing, you never have to call <code>set_token_url</code> yet still invoke <code>get_token_url</code>.</p><p>Define a custom state type with its own <code>get_token_url</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> oauth::*;</span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">HackEndpointSet</span> &#123;&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">EndpointState</span> <span class="keyword">for</span> <span class="title class_">HackEndpointSet</span> &#123;&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">Client</span>&lt;EndointSet, HackEndpointSet&gt; &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">get_token_url</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> &amp;<span class="type">str</span> &#123;</span><br><span class="line">        <span class="string">&quot;Hacked!&quot;</span></span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">let</span> <span class="variable">client</span> =</span><br><span class="line">    Client::&lt;EndointSet, HackEndpointSet&gt;::<span class="title function_ invoke__">new</span>().<span class="title function_ invoke__">set_auth_url</span>(<span class="string">&quot;https://auth.example.com&quot;</span>);</span><br><span class="line"><span class="comment">// .set_token_url(&quot;https://token.example.com&quot;);</span></span><br><span class="line"></span><br><span class="line"><span class="built_in">println!</span>(<span class="string">&quot;Auth URL: &#123;&#125;&quot;</span>, client.<span class="title function_ invoke__">get_auth_url</span>());</span><br><span class="line"><span class="built_in">println!</span>(<span class="string">&quot;Token URL: &#123;&#125;&quot;</span>, client.<span class="title function_ invoke__">get_token_url</span>());</span><br></pre></td></tr></table></figure><h2 id="Sealing-it"><a href="#Sealing-it" class="headerlink" title="Sealing it"></a>Sealing it</h2><p><strong>Sealed traits</strong> block that path:</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">mod</span> oauth &#123;</span><br><span class="line">    <span class="comment">// ...</span></span><br><span class="line">    <span class="comment">// sealed trait</span></span><br><span class="line">    <span class="keyword">mod</span> private &#123;</span><br><span class="line">        <span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">EndpointStateSealed</span> &#123;&#125;</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_">EndpointState</span>: private::EndpointStateSealed &#123;&#125;</span><br><span class="line">    <span class="keyword">impl</span> <span class="title class_">private</span>::EndpointStateSealed <span class="keyword">for</span> <span class="title class_">EndointSet</span> &#123;&#125;</span><br><span class="line">    <span class="keyword">impl</span> <span class="title class_">private</span>::EndpointStateSealed <span class="keyword">for</span> <span class="title class_">EndpointNotSet</span> &#123;&#125;</span><br><span class="line">    <span class="comment">// ...</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p><code>HackEndpointSet</code> can no longer implement <code>EndpointState</code>. The compiler error includes the sealed-trait note:</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></pre></td><td class="code"><pre><span class="line">error[E0277]: the trait bound `HackEndpointSet: EndpointStateSealed` is not satisfied</span><br><span class="line"><span class="meta prompt_">  --&gt; </span><span class="language-bash">src/main.rs:71:28</span></span><br><span class="line">   |</span><br><span class="line">71 |     impl EndpointState for HackEndpointSet &#123;&#125;</span><br><span class="line">   |                            ^^^^^^^^^^^^^^^ the trait `EndpointStateSealed` is not implemented for `HackEndpointSet`</span><br><span class="line">   |</span><br><span class="line">   = help: the following other types implement trait `EndpointStateSealed`:</span><br><span class="line">             oauth::EndointSet</span><br><span class="line">             EndpointNotSet</span><br><span class="line">note: required by a bound in `oauth::EndpointState`</span><br><span class="line"><span class="meta prompt_">  --&gt; </span><span class="language-bash">src/main.rs:12:30</span></span><br><span class="line">   |</span><br><span class="line">12 |     pub trait EndpointState: private::EndpointStateSealed &#123;&#125;</span><br><span class="line">   |                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `EndpointState`</span><br><span class="line">   = note: `EndpointState` is a &quot;sealed trait&quot;, because to implement it you also need to implement `oauth::private::EndpointStateSealed`, which is not accessible; this is usually done to force you to use one of the provided types that already implement it</span><br><span class="line">   = help: the following types implement the trait:</span><br><span class="line">             oauth::EndointSet</span><br><span class="line">             oauth::EndpointNotSet</span><br></pre></td></tr></table></figure><p>Real code in oauth2-rs: <a href="https://github.com/ramosbugs/oauth2-rs/blob/main/src/client.rs">client.rs</a>.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sealed-trait-2.html</id>
    <link href="https://newbmiao.github.io/rust-sealed-trait-2.html"/>
    <published>2024-04-25T01:50:36.000Z</published>
    <summary>How oauth2-rs uses sealing on endpoint state so outsiders cannot fake configured URLs.</summary>
    <title>Sealed traits in oauth2-rs — closing the typestate loophole</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="typestate" scheme="https://newbmiao.github.io/tags/typestate/"/>
    <content>
      <![CDATA[<p><strong>Typestate</strong> encodes lifecycle state in the type system.</p><p>oauth2-rs uses it for a concrete pain point: OAuth2 clients need <code>auth_url</code>, <code>token_url</code>, <code>introspect_url</code>, and friends wired up before auth calls make sense. If <code>token_url</code> is missing, exchanging an authorization code for a token fails at <strong>runtime</strong>.</p><p>Forgot to call <code>set_token_url</code>? You find out when you fetch a token—not when you build the client.</p><p>Typestate pushes that mistake to <strong>compile time</strong>.</p><span id="more"></span><h2 id="Typestate"><a href="#Typestate" class="headerlink" title="Typestate"></a>Typestate</h2><p>State lives in the type. In a strongly typed language, the compiler can reject calls that do not match the current state.</p><p>Two ticket types illustrate the idea:</p><p><code>EmptyTicket</code> can only be created or booked.</p><p><code>book</code> moves you to <code>BookedTicket</code>, where you may <code>use</code> (consume) or <code>cancel</code> back to <code>EmptyTicket</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">struct</span> <span class="title class_">EmptyTicket</span> &#123;&#125;</span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">BookedTicket</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">EmptyTicket</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">new</span>() <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123;</span><br><span class="line">        EmptyTicket &#123;&#125;</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">book</span>(<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> BookedTicket &#123;</span><br><span class="line">        BookedTicket &#123;&#125;</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">impl</span> <span class="title class_">BookedTicket</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">use</span>(<span class="keyword">self</span>) &#123;&#125;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">cancel</span>(<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> EmptyTicket &#123;</span><br><span class="line">        EmptyTicket &#123;&#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="OAuth2-client-simulation"><a href="#OAuth2-client-simulation" class="headerlink" title="OAuth2 client simulation"></a>OAuth2 client simulation</h2><p>How does that map to the missing-URL problem?</p><p>Below is a trimmed stand-in for oauth2-rs.</p><p><code>auth_url</code> and <code>token_url</code> each have an <code>EndpointState</code>.</p><p>Initially both are unset (<code>EndpointNotSet</code>). Calling a setter returns a <code>Client</code> with the corresponding type parameter flipped to <code>EndointSet</code>.</p><p>Methods that need a configured URL are only implemented on <code>Client</code> variants that carry <code>EndointSet</code> in the right slot—so you cannot call token helpers until the type says the token URL is set.</p><p>For example, <code>Client&lt;EndointSet, EndpointNotSet&gt;</code> may use auth-url APIs but not token-url APIs, because the type still says <code>token_url</code> is unset.</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><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><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br><span class="line">70</span><br><span class="line">71</span><br><span class="line">72</span><br><span class="line">73</span><br><span class="line">74</span><br><span class="line">75</span><br><span class="line">76</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::marker::PhantomData;</span><br><span class="line"></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">EndointSet</span> &#123;&#125;</span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">EndpointNotSet</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">trait</span> <span class="title class_">EndpointState</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">EndpointState</span> <span class="keyword">for</span> <span class="title class_">EndointSet</span> &#123;&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">EndpointState</span> <span class="keyword">for</span> <span class="title class_">EndpointNotSet</span> &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">Client</span>&lt;HasAuthUrl = EndpointNotSet, HasTokenUrl = EndpointNotSet&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    HasAuthUrl: EndpointState,</span><br><span class="line">    HasTokenUrl: EndpointState,</span><br><span class="line">&#123;</span><br><span class="line">    auth_url: <span class="type">Option</span>&lt;<span class="type">String</span>&gt;,</span><br><span class="line">    token_url: <span class="type">Option</span>&lt;<span class="type">String</span>&gt;,</span><br><span class="line">    phantom: std::marker::PhantomData&lt;(HasAuthUrl, HasTokenUrl)&gt;,</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">impl</span>&lt;HasAuthUrl, HasTokenUrl&gt; Client&lt;HasAuthUrl, HasTokenUrl&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    HasAuthUrl: EndpointState,</span><br><span class="line">    HasTokenUrl: EndpointState,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">new</span>() <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123;</span><br><span class="line">        Client &#123;</span><br><span class="line">            auth_url: <span class="literal">None</span>,</span><br><span class="line">            token_url: <span class="literal">None</span>,</span><br><span class="line">            phantom: PhantomData,</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">pub</span> <span class="keyword">fn</span> <span class="title function_">set_auth_url</span>(<span class="keyword">self</span>, auth_url: &amp;<span class="type">str</span>) <span class="punctuation">-&gt;</span> Client&lt;EndointSet, HasTokenUrl&gt; &#123;</span><br><span class="line">        Client &#123;</span><br><span class="line">            auth_url: <span class="title function_ invoke__">Some</span>(auth_url.<span class="title function_ invoke__">to_string</span>()),</span><br><span class="line">            token_url: <span class="keyword">self</span>.token_url,</span><br><span class="line">            phantom: PhantomData,</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">pub</span> <span class="keyword">fn</span> <span class="title function_">set_token_url</span>(<span class="keyword">self</span>, token_url: &amp;<span class="type">str</span>) <span class="punctuation">-&gt;</span> Client&lt;HasAuthUrl, EndointSet&gt; &#123;</span><br><span class="line">        Client &#123;</span><br><span class="line">            auth_url: <span class="keyword">self</span>.auth_url,</span><br><span class="line">            token_url: <span class="title function_ invoke__">Some</span>(token_url.<span class="title function_ invoke__">to_string</span>()),</span><br><span class="line">            phantom: PhantomData,</span><br><span class="line">        &#125;</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">impl</span>&lt;HasTokenUrl&gt; Client&lt;EndointSet, HasTokenUrl&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    HasTokenUrl: EndpointState,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">get_auth_url</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> &amp;<span class="type">str</span> &#123;</span><br><span class="line">        <span class="keyword">self</span>.auth_url.<span class="title function_ invoke__">as_ref</span>().<span class="title function_ invoke__">unwrap</span>()</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">impl</span>&lt;HasAuthUrl&gt; Client&lt;HasAuthUrl, EndointSet&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    HasAuthUrl: EndpointState,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">get_token_url</span>(&amp;<span class="keyword">self</span>) <span class="punctuation">-&gt;</span> &amp;<span class="type">str</span> &#123;</span><br><span class="line">        <span class="keyword">self</span>.token_url.<span class="title function_ invoke__">as_ref</span>().<span class="title function_ invoke__">unwrap</span>()</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><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> <span class="variable">client</span> =</span><br><span class="line">        Client::&lt;EndointSet, EndpointNotSet&gt;::<span class="title function_ invoke__">new</span>().<span class="title function_ invoke__">set_auth_url</span>(<span class="string">&quot;https://auth.example.com&quot;</span>);</span><br><span class="line">    <span class="comment">// .set_token_url(&quot;https://token.example.com&quot;);</span></span><br><span class="line">    <span class="comment">// Uncommenting get_token_url below fails: Client type does not match set_token_url&#x27;s state.</span></span><br><span class="line"></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Auth URL: &#123;&#125;&quot;</span>, client.<span class="title function_ invoke__">get_auth_url</span>());</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Token URL: &#123;&#125;&quot;</span>, client.<span class="title function_ invoke__">get_token_url</span>());</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Further-reading"><a href="#Further-reading" class="headerlink" title="Further reading"></a>Further reading</h2><p>The idea goes back a while; Clifford Wolfe’s <a href="https://cliffle.com/blog/rust-typestate">typestate write-up</a> (2019) is still a good read.</p><p>Pair with <a href="/rust-sealed-trait-2.html">sealing endpoint state</a> so callers cannot fake “configured” types.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-typestate-pattern.html</id>
    <link href="https://newbmiao.github.io/rust-typestate-pattern.html"/>
    <published>2024-04-24T06:00:19.000Z</published>
    <summary>Encode auth and token URL configuration in generic state so missing setup fails at compile time.</summary>
    <title>Rust typestate — compile-time checks for OAuth2 client setup</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="sealed-trait" scheme="https://newbmiao.github.io/tags/sealed-trait/"/>
    <content>
      <![CDATA[<p>I was bumping dependencies on an older <a href="https://github.com/NewbMiao/axum-koans/">OAuth2 axum koan</a> project; the newer <a href="https://github.com/ramosbugs/oauth2-rs">oauth2-rs</a> uses <strong>sealed traits</strong> in a way that’s easy to miss if you only read the public API.</p><span id="more"></span><p>Use this pattern when you want your trait to control <strong>who</strong> is allowed to implement it.</p><p>A normal trait is wide open: anyone can add an impl for any type.</p><p>For example, <code>nosealed_trait</code> below can be implemented for both <code>usize</code> and <code>i32</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">mod</span> nosealed_trait &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">MyTrait</span> &#123;</span><br><span class="line">        <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">impl</span> <span class="title class_">nosealed_trait</span>::MyTrait <span class="keyword">for</span> <span class="title class_">usize</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;MyTrait for usize&quot;</span>);</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">impl</span> <span class="title class_">nosealed_trait</span>::MyTrait <span class="keyword">for</span> <span class="title class_">i32</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;MyTrait for i32&quot;</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>What if you only want <code>i32</code>?</p><p>Have your public trait inherit a <strong>non-exported supertrait</strong>, and only implement that supertrait for the types you allow:</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">mod</span> sealed_trait &#123;</span><br><span class="line">    <span class="keyword">mod</span> private &#123;</span><br><span class="line">        <span class="keyword">pub</span> <span class="keyword">trait</span> <span class="title class_">Sealed</span> &#123;&#125;</span><br><span class="line">        <span class="keyword">impl</span> <span class="title class_">Sealed</span> <span class="keyword">for</span> <span class="title class_">i32</span> &#123;&#125;</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_">MySealedTrait</span>: private::Sealed &#123;</span><br><span class="line">        <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>);</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">impl</span> <span class="title class_">sealed_trait</span>::MySealedTrait <span class="keyword">for</span> <span class="title class_">i32</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;MySealedTrait for i32&quot;</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>If a caller tries to implement your trait for a type that is not on the allow list, the compiler stops them:</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">impl</span> <span class="title class_">sealed_trait</span>::MySealedTrait <span class="keyword">for</span> <span class="title class_">usize</span> &#123;</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">my_sealed_method</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;MySealedTrait for usize&quot;</span>);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The error message spells it out in the <code>note</code>:</p><blockquote><p>note: <code>MySealedTrait</code> is a “sealed trait”, because to implement it you also need to implement <code>sealedtrait::private::Sealed</code>, which is not accessible; this is usually done to force you to use one of the provided types that already implement it</p></blockquote><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></pre></td><td class="code"><pre><span class="line">error[E0277]: the trait bound `usize: Sealed` is not satisfied</span><br><span class="line"><span class="meta prompt_">  --&gt; </span><span class="language-bash">src/main.rs:34:37</span></span><br><span class="line">   |</span><br><span class="line">34 | impl sealedtrait::MySealedTrait for usize &#123;</span><br><span class="line">   |                                     ^^^^^ the trait `Sealed` is not implemented for `usize`</span><br><span class="line">   |</span><br><span class="line">   = help: the trait `Sealed` is implemented for `i32`</span><br><span class="line">note: required by a bound in `MySealedTrait`</span><br><span class="line"><span class="meta prompt_">  --&gt; </span><span class="language-bash">src/main.rs:23:30</span></span><br><span class="line">   |</span><br><span class="line">23 |     pub trait MySealedTrait: private::Sealed &#123;</span><br><span class="line">   |                              ^^^^^^^^^^^^^^^ required by this bound in `MySealedTrait`</span><br><span class="line">   = note: `MySealedTrait` is a &quot;sealed trait&quot;, because to implement it you also need to implement `sealedtrait::private::Sealed`, which is not accessible; this is usually done to force you to use one of the provided types that already implement it</span><br><span class="line">   = help: the following type implements the trait:</span><br><span class="line">             i32</span><br></pre></td></tr></table></figure><p>Next: the <a href="/rust-typestate-pattern.html">typestate pattern</a>.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sealed-trait.html</id>
    <link href="https://newbmiao.github.io/rust-sealed-trait.html"/>
    <published>2024-04-22T09:26:42.000Z</published>
    <summary>A private supertrait restricts implementations, with compiler errors when callers overstep.</summary>
    <title>Rust sealed traits — limiting who can implement your trait</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="aws-lambda" scheme="https://newbmiao.github.io/tags/aws-lambda/"/>
    <content>
      <![CDATA[<p><strong>AWS Lambda</strong> is a lightweight compute service: pay for what you use and let AWS handle packaging and scaling.</p><p>Billing tracks duration and memory, which is where <strong>Rust</strong> tends to shine—hence all the serverless handlers written in Rust.</p><p>Below: cargo-lambda for a Rust handler, local watch, and a LocalStack deploy—you don’t need a real AWS account for the sandbox at the end.</p><span id="more"></span><h2 id="cargo-lambda"><a href="#cargo-lambda" class="headerlink" title="cargo-lambda"></a>cargo-lambda</h2><p><a href="https://www.cargo-lambda.info/">cargo-lambda</a> is the usual tool for building Lambda functions (AWS points people at it too).</p><p>Install:</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">brew tap cargo-lambda/cargo-lambda</span><br><span class="line">brew install cargo-lambda</span><br></pre></td></tr></table></figure><p>Scaffold a demo:</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">cargo lambda new lambda-demo</span><br><span class="line"><span class="meta prompt_">&gt; </span><span class="language-bash">Is this <span class="keyword">function</span> an HTTP <span class="keyword">function</span>? Yes</span></span><br></pre></td></tr></table></figure><p>The template pulls in <code>lambda-http</code> and <code>tokio</code> for the runtime.</p><p>Handler sketch—a hello-world HTTP response:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> lambda_http::&#123;run, service_fn, tracing, Body, Error, Request, RequestExt, Response&#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_">function_handler</span>(event: Request) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;Response&lt;Body&gt;, Error&gt; &#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">who</span> = event</span><br><span class="line">        .<span class="title function_ invoke__">query_string_parameters_ref</span>()</span><br><span class="line">        .<span class="title function_ invoke__">and_then</span>(|params| params.<span class="title function_ invoke__">first</span>(<span class="string">&quot;name&quot;</span>))</span><br><span class="line">        .<span class="title function_ invoke__">unwrap_or</span>(<span class="string">&quot;world&quot;</span>);</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">message</span> = <span class="built_in">format!</span>(<span class="string">&quot;Hello &#123;who&#125;, this is an AWS Lambda HTTP request&quot;</span>);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">resp</span> = Response::<span class="title function_ invoke__">builder</span>()</span><br><span class="line">        .<span class="title function_ invoke__">status</span>(<span class="number">200</span>)</span><br><span class="line">        .<span class="title function_ invoke__">header</span>(<span class="string">&quot;content-type&quot;</span>, <span class="string">&quot;text/html&quot;</span>)</span><br><span class="line">        .<span class="title function_ invoke__">body</span>(message.<span class="title function_ invoke__">into</span>())</span><br><span class="line">        .<span class="title function_ invoke__">map_err</span>(<span class="type">Box</span>::new)?;</span><br><span class="line">    <span class="title function_ invoke__">Ok</span>(resp)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">main</span>() <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;(), Error&gt; &#123;</span><br><span class="line">    tracing::<span class="title function_ invoke__">init_default_subscriber</span>();</span><br><span class="line"></span><br><span class="line">    <span class="title function_ invoke__">run</span>(<span class="title function_ invoke__">service_fn</span>(function_handler)).<span class="keyword">await</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Side note: <code>service_fn</code> look familiar? The handler sits on the same <code>Service</code> trait shape as <strong>tower</strong>—because this stack uses <strong>hyper</strong>, the usual bedrock for Rust HTTP.</p><h2 id="Run-locally"><a href="#Run-locally" class="headerlink" title="Run locally"></a>Run locally</h2><p>During development, <code>watch</code> rebuilds on change and serves invocations locally:</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">cargo lambda watch</span><br><span class="line">#  INFO invoke server listening on [::]:<span class="number">9000</span></span><br></pre></td></tr></table></figure><p>Invoke from the CLI:</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">cargo lambda invoke lambda-demo --data-ascii &quot;?name=newbmiao&quot;</span><br></pre></td></tr></table></figure><h2 id="Build-artifact"><a href="#Build-artifact" class="headerlink" title="Build artifact"></a>Build artifact</h2><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">cargo lambda build --release --arm64</span><br></pre></td></tr></table></figure><p>Output lands at <code>./target/lambda/lambda-demo/bootstrap</code> (for a <strong>workspace</strong>, check the workspace root <code>target</code> tree).</p><p>Zip the binary for upload:</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">zip bootstrap.zip bootstrap</span><br></pre></td></tr></table></figure><h2 id="Deploy"><a href="#Deploy" class="headerlink" title="Deploy"></a>Deploy</h2><p>Deployment is straightforward; the friction is often “I do not have AWS credentials.” <strong>LocalStack</strong> emulates AWS on your machine.</p><p><code>docker-compose up</code> for LocalStack:</p><figure class="highlight dockerfile"><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">version: <span class="string">&quot;3.8&quot;</span></span><br><span class="line"></span><br><span class="line">services:</span><br><span class="line">  localstack:</span><br><span class="line">    container_name: <span class="string">&quot;$&#123;LOCALSTACK_DOCKER_NAME:-localstack-main&#125;&quot;</span></span><br><span class="line">    image: localstack/localstack</span><br><span class="line">    ports:</span><br><span class="line">      - <span class="string">&quot;127.0.0.1:4566:4566&quot;</span> <span class="comment"># LocalStack Gateway</span></span><br><span class="line">      - <span class="string">&quot;127.0.0.1:4510-4559:4510-4559&quot;</span> <span class="comment"># external services port range</span></span><br><span class="line">    environment:</span><br><span class="line">      <span class="comment"># LocalStack configuration: https://docs.localstack.cloud/references/configuration/</span></span><br><span class="line">      - DEBUG=$&#123;DEBUG:-<span class="number">0</span>&#125;</span><br><span class="line">    volumes:</span><br><span class="line">      - <span class="string">&quot;$&#123;LOCALSTACK_VOLUME_DIR:-./volume&#125;:/var/lib/localstack&quot;</span></span><br><span class="line">      - <span class="string">&quot;/var/run/docker.sock:/var/run/docker.sock&quot;</span></span><br></pre></td></tr></table></figure><p><strong>Terraform</strong> for the Lambda itself:</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><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"># build</span><br><span class="line">resource &quot;aws_lambda_function&quot; &quot;lambda_demo&quot; &#123;</span><br><span class="line">  filename         = &quot;bootstrap.zip&quot;</span><br><span class="line">  function_name    = &quot;lambda_demo&quot;</span><br><span class="line">  role             = aws_iam_role.iam_for_lambda_tf.arn</span><br><span class="line">  handler          = &quot;bootstrap&quot;</span><br><span class="line">  source_code_hash = filebase64sha256(&quot;bootstrap.zip&quot;)</span><br><span class="line">  runtime          = &quot;provided.al2&quot;</span><br><span class="line">  architectures    = [&quot;arm64&quot;]</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>IAM plus function URL:</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><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></pre></td><td class="code"><pre><span class="line">resource &quot;aws_lambda_function_url&quot; &quot;lambda_demo_url&quot; &#123;</span><br><span class="line">  function_name      = aws_lambda_function.lambda_demo.arn</span><br><span class="line">  authorization_type = &quot;NONE&quot;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">output &quot;function_url&quot; &#123;</span><br><span class="line">  description = &quot;Function URL.&quot;</span><br><span class="line">  value       = aws_lambda_function_url.lambda_demo_url.function_url</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">resource &quot;aws_iam_role&quot; &quot;iam_for_lambda_tf&quot; &#123;</span><br><span class="line">  name = &quot;iam_for_lambda_tf&quot;</span><br><span class="line"></span><br><span class="line">  assume_role_policy = &lt;&lt;EOF</span><br><span class="line">&#123;</span><br><span class="line">  &quot;Version&quot;: &quot;2012-10-17&quot;,</span><br><span class="line">  &quot;Statement&quot;: [</span><br><span class="line">    &#123;</span><br><span class="line">      &quot;Action&quot;: &quot;sts:AssumeRole&quot;,</span><br><span class="line">      &quot;Principal&quot;: &#123;</span><br><span class="line">        &quot;Service&quot;: &quot;lambda.amazonaws.com&quot;</span><br><span class="line">      &#125;,</span><br><span class="line">      &quot;Effect&quot;: &quot;Allow&quot;,</span><br><span class="line">      &quot;Sid&quot;: &quot;&quot;</span><br><span class="line">    &#125;</span><br><span class="line">  ]</span><br><span class="line">&#125;</span><br><span class="line">EOF</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>After <code>terraform apply</code>, grab the URL from outputs, e.g.:</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">...</span><br><span class="line">Apply complete! Resources: 3 added, 0 changed, 0 destroyed.</span><br><span class="line"></span><br><span class="line">Outputs:</span><br><span class="line"></span><br><span class="line">function_url = &quot;http://h6v7ozz6ay3h6apr2hi5edsmnc0wpz80.lambda-url.us-east-1.localhost.localstack.cloud:4566/</span><br></pre></td></tr></table></figure><p>End-to-end sample: <a href="https://github.com/NewbMiao/rust-koan/tree/master/aws-lambda/lambda-demo">lambda-demo</a> (<code>build.sh</code> walks through packaging).</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-lambda.html</id>
    <link href="https://newbmiao.github.io/rust-lambda.html"/>
    <published>2024-03-10T10:44:14.000Z</published>
    <summary>Install cargo-lambda, run an HTTP handler locally, build bootstrap.zip, and deploy with Terraform against LocalStack.</summary>
    <title>AWS Lambda in Rust — cargo-lambda, local watch, and LocalStack deploy</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="tower" scheme="https://newbmiao.github.io/tags/tower/"/>
    <content>
      <![CDATA[<p>When people talk about Rust HTTP middleware, <strong>Tower</strong> comes up fast.</p><p>Tower is protocol-agnostic middleware plumbing; <strong><code>Service</code></strong> and <strong><code>Layer</code></strong> are how you stack Logger, timeout, and handler layers.</p><span id="more"></span><h2 id="A-bare-handler"><a href="#A-bare-handler" class="headerlink" title="A bare handler"></a>A bare handler</h2><p>Start from hyper’s hello-world handler:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> http_body_util::Full;</span><br><span class="line"><span class="keyword">use</span> hyper::&#123;</span><br><span class="line">    body::&#123;Bytes, Incoming&#125;,</span><br><span class="line">    server::conn::http1,</span><br><span class="line">    Request, Response,</span><br><span class="line">&#125;;</span><br><span class="line"><span class="keyword">use</span> hyper_util::rt::TokioIo;</span><br><span class="line"><span class="keyword">use</span> std::&#123;convert::Infallible, net::SocketAddr&#125;;</span><br><span class="line"><span class="keyword">use</span> tokio::net::TcpListener;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">handler</span>(_: Request&lt;Incoming&gt;) <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;Response&lt;Full&lt;Bytes&gt;&gt;, Infallible&gt; &#123;</span><br><span class="line">    <span class="title function_ invoke__">Ok</span>(Response::<span class="title function_ invoke__">new</span>(Full::<span class="title function_ invoke__">new</span>(Bytes::<span class="title function_ invoke__">from</span>(<span class="string">&quot;Hello, World!&quot;</span>))))</span><br><span class="line">&#125;</span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">main</span>() <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;(), <span class="type">Box</span>&lt;<span class="keyword">dyn</span> std::error::Error + <span class="built_in">Send</span> + <span class="built_in">Sync</span>&gt;&gt; &#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">addr</span> = SocketAddr::<span class="title function_ invoke__">from</span>(([<span class="number">127</span>, <span class="number">0</span>, <span class="number">0</span>, <span class="number">1</span>], <span class="number">3000</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">listener</span> = TcpListener::<span class="title function_ invoke__">bind</span>(addr).<span class="keyword">await</span>?;</span><br><span class="line">    <span class="keyword">loop</span> &#123;</span><br><span class="line">        <span class="keyword">let</span> (stream, _) = listener.<span class="title function_ invoke__">accept</span>().<span class="keyword">await</span>?;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">io</span> = TokioIo::<span class="title function_ invoke__">new</span>(stream);</span><br><span class="line">        tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">            <span class="comment">// the handler becomes a Service here</span></span><br><span class="line">            <span class="keyword">let</span> <span class="variable">svc</span> = hyper::service::<span class="title function_ invoke__">service_fn</span>(handler);</span><br><span class="line">            <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Err</span>(err) = http1::Builder::<span class="title function_ invoke__">new</span>().<span class="title function_ invoke__">serve_connection</span>(io, svc).<span class="keyword">await</span> &#123;</span><br><span class="line">                <span class="built_in">eprintln!</span>(<span class="string">&quot;server error: &#123;&#125;&quot;</span>, err);</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><code>service_fn</code> turns the async fn into something that implements <strong><code>Service</code></strong>—what the server actually calls. That’s the hook middleware wraps.</p><blockquote><p>After hyper v1, this <code>Service</code> is not literally tower’s trait, but the shape matches. We’ll contrast the interfaces later.</p></blockquote><p>To add logging and a five-second timeout around the handler:</p><p><img decoding="async" loading="lazy" src="/images/rust/tower-service.webp" alt="tower-service"></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">svc</span> = hyper::service::<span class="title function_ invoke__">service_fn</span>(handler);</span><br><span class="line"><span class="comment">// two layer middlewares</span></span><br><span class="line"><span class="keyword">let</span> <span class="variable">svc</span> = ServiceBuilder::<span class="title function_ invoke__">new</span>()</span><br><span class="line">    .<span class="title function_ invoke__">layer_fn</span>(Logger::new)</span><br><span class="line">    .<span class="title function_ invoke__">layer_fn</span>(|s| Timeout::<span class="title function_ invoke__">new</span>(s, std::time::Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">5</span>)))</span><br><span class="line">    .<span class="title function_ invoke__">service</span>(svc);</span><br><span class="line"><span class="comment">// ignore the adapter below for now — covered later</span></span><br><span class="line"><span class="comment">// let svc = TowerToHyperService::new(svc);</span></span><br></pre></td></tr></table></figure><h2 id="Service-trait"><a href="#Service-trait" class="headerlink" title="Service trait"></a>Service trait</h2><p>Each middleware is another link in a chain: handle side effects, then delegate inward.</p><p>Tower’s <code>Service</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></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 class="comment">// whether a call is allowed now</span></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="comment">// handle the request</span></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><code>poll_ready</code> gates <code>call</code>. <code>call</code> returns a <code>Future</code> so slow work doesn’t block the caller’s ability to accept other requests.</p><p>Why <code>Future</code> instead of <code>async fn</code> in the trait? Historical—async in traits wasn’t stable yet. Since Rust 1.75 you could write:</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">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">async</span> <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="type">Result</span>&lt;<span class="keyword">Self</span>::Response, <span class="keyword">Self</span>::Error&gt;;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="A-Logger-middleware"><a href="#A-Logger-middleware" class="headerlink" title="A Logger middleware"></a>A Logger middleware</h2><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> tower::Service;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[derive(Debug, Clone)]</span></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Logger</span>&lt;S&gt; &#123;</span><br><span class="line">    inner: S,</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">impl</span>&lt;S&gt; Logger&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>(inner: S) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span> &#123;</span><br><span class="line">        Logger &#123; inner &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">type</span> <span class="title class_">Req</span> = hyper::Request&lt;Incoming&gt;;</span><br><span class="line"><span class="keyword">impl</span>&lt;S&gt; Service&lt;Req&gt; <span class="keyword">for</span> <span class="title class_">Logger</span>&lt;S&gt;</span><br><span class="line"><span class="keyword">where</span></span><br><span class="line">    S: Service&lt;Req&gt; + <span class="built_in">Clone</span>,</span><br><span class="line">&#123;</span><br><span class="line">    <span class="comment">// Logger wraps another Service; response/error types pass through</span></span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Response</span> = S::Response;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Error</span> = S::Error;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Future</span> = S::Future;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">poll_ready</span>(</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> 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="type">Result</span>&lt;(), <span class="keyword">Self</span>::Error&gt;&gt; &#123;</span><br><span class="line">        <span class="comment">// no extra readiness logic</span></span><br><span class="line">        <span class="keyword">self</span>.inner.<span class="title function_ invoke__">poll_ready</span>(cx)</span><br><span class="line">    &#125;</span><br><span class="line"></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: Req) <span class="punctuation">-&gt;</span> <span class="keyword">Self</span>::Future &#123;</span><br><span class="line">        <span class="built_in">println!</span>(<span class="string">&quot;processing request: &#123;&#125; &#123;&#125;&quot;</span>, req.<span class="title function_ invoke__">method</span>(), req.<span class="title function_ invoke__">uri</span>().<span class="title function_ invoke__">path</span>());</span><br><span class="line">        <span class="comment">// delegate to the inner Service</span></span><br><span class="line">        <span class="keyword">self</span>.inner.<span class="title function_ invoke__">call</span>(req)</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Wire it manually:</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">svc</span> = Logger::<span class="title function_ invoke__">new</span>(svc);</span><br></pre></td></tr></table></figure><p>Then timeout:</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">svc</span> = Timeout::<span class="title function_ invoke__">new</span>(svc, std::time::Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">5</span>));</span><br></pre></td></tr></table></figure><p>That’s awkward—last wrapped runs first—and not chain-friendly. <strong><code>Layer</code></strong> fixes ordering and ergonomics.</p><h2 id="Layer-trait"><a href="#Layer-trait" class="headerlink" title="Layer trait"></a>Layer trait</h2><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_">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 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></pre></td></tr></table></figure><p>Implement it for <code>Logger</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">impl</span>&lt;S&gt; Layer&lt;S&gt; <span class="keyword">for</span> <span class="title class_">Logger</span>&lt;S&gt; &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Service</span> = Logger&lt;S&gt;;</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 &#123;</span><br><span class="line">        Logger &#123; inner &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Then build in call order:</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">tower::ServiceBuilder::<span class="title function_ invoke__">new</span>()</span><br><span class="line">    .<span class="title function_ invoke__">layer</span>(LoggerLayer)</span><br><span class="line">    .<span class="title function_ invoke__">layer_fn</span>(|s| Timeout::<span class="title function_ invoke__">new</span>(s, std::time::Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">5</span>)))</span><br><span class="line">    .<span class="title function_ invoke__">service</span>(svc);</span><br></pre></td></tr></table></figure><p><code>layer_fn</code> adapts closures into <code>Layer</code>. Middleware runs in the same order you <code>.layer()</code> it.</p><h2 id="hyper’s-Service-trait"><a href="#hyper’s-Service-trait" class="headerlink" title="hyper’s Service trait"></a>hyper’s Service trait</h2><p>Hyper used to depend on tower’s <code>Service</code>. Before v1 stabilized, it switched to its own trait:</p><ul><li>tower wasn’t stable yet</li><li>hyper wanted a thinner surface: drop <code>poll_ready</code>, and take <code>&amp;self</code> in <code>call</code> (shared state via <code>Arc&lt;Mutex&lt;_&gt;&gt;</code> if you need mutation)</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></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_">call</span>(&amp;<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>Reusing tower middleware (e.g. <code>Timeout</code>) against hyper often needs an adapter:</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">svc</span> = TowerToHyperService::<span class="title function_ invoke__">new</span>(svc);</span><br></pre></td></tr></table></figure><p>Frameworks built on hyper—<strong>Axum</strong>, <strong>Actix Web</strong>, and others—also integrate tower, so middleware written once tends to travel.</p><p>Tower’s <code>Service</code>&#x2F;<code>Layer</code> split looks obvious in hindsight; getting <code>Future</code>-returning <code>call</code> right took real design work. Tokio’s write-up is worth it: <a href="https://tokio.rs/blog/2021-05-14-inventing-the-service-trait">Inventing the Service trait</a>.</p><p>For a live build-through: David Pedersen’s <a href="https://www.youtube.com/watch?v=16sU1q8OeeI&t=4227s">Tower deep dive</a> (search “Tower deep dive” on Bilibili if YouTube is blocked).</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-tower-service.html</id>
    <link href="https://newbmiao.github.io/rust-tower-service.html"/>
    <published>2024-02-03T10:25:19.000Z</published>
    <summary>How tower’s Service and Layer traits compose Logger, Timeout, and hyper handlers.</summary>
    <title>Tower Service and Layer — HTTP middleware chains with hyper</title>
    <updated>2026-11-20T12:30:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="tokio" scheme="https://newbmiao.github.io/tags/tokio/"/>
    <category term="tracing" scheme="https://newbmiao.github.io/tags/tracing/"/>
    <content>
      <![CDATA[<p>Rust async is built around <strong>task</strong> scheduling—tasks are the language-level unit the executor moves between.</p><p>Can you <strong>see</strong> that scheduling happen? Yes. Tokio ships <strong>tokio-console</strong>: a live view of tasks, polls, and wakeups that helps when you’re debugging latency or learning how the runtime behaves.</p><span id="more"></span><h2 id="Setup"><a href="#Setup" class="headerlink" title="Setup"></a>Setup</h2><p>Your program reports events through <strong><code>console-subscriber</code></strong>; the <strong><code>tokio-console</code></strong> CLI aggregates and displays them.</p><p>The API is still unstable, so you need a few flags.</p><p>Enable Tokio’s <code>tracing</code> feature and add the subscriber, e.g.:</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">[dependencies]</span><br><span class="line">console-subscriber = <span class="string">&quot;0.2.0&quot;</span></span><br><span class="line">tokio = &#123; version = <span class="string">&quot;1.35.1&quot;</span>, features = [<span class="string">&quot;full&quot;</span>, <span class="string">&quot;tracing&quot;</span>] &#125;</span><br></pre></td></tr></table></figure><p>Initialize in <code>main</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></pre></td><td class="code"><pre><span class="line"><span class="meta">#[tokio::main]</span></span><br><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">    console_subscriber::<span class="title function_ invoke__">init</span>();</span><br><span class="line">    <span class="comment">// ...</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Run with: <code>RUSTFLAGS=&quot;--cfg tokio_unstable&quot; cargo run</code></p><p>Or bake it into <code>.cargo/config.toml</code>:</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">[build]</span></span><br><span class="line"><span class="attr">rustflags</span> = [<span class="string">&quot;--cfg&quot;</span>, <span class="string">&quot;tokio_unstable&quot;</span>]</span><br></pre></td></tr></table></figure><p>Install the viewer with <code>cargo install tokio-console</code>, then run your app and attach the console.</p><h2 id="Instrumenting-the-demo"><a href="#Instrumenting-the-demo" class="headerlink" title="Instrumenting the demo"></a>Instrumenting the demo</h2><p>The demo reuses the two-thread alternating-print <strong><a href="/rust-sync-semaphore.html">Semaphore</a></strong> pattern; tracing hooks are marked in comments:</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::&#123;sync::Arc, time::Duration&#125;;</span><br><span class="line"><span class="keyword">use</span> tokio::&#123;sync::Semaphore, task, time::sleep&#125;;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="comment">// init tracing collection</span></span><br><span class="line">    console_subscriber::<span class="title function_ invoke__">init</span>();</span><br><span class="line">    <span class="comment">// semaphore1 starts with one permit so &quot;1&quot; can print first</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore</span> = Arc::<span class="title function_ invoke__">new</span>(Semaphore::<span class="title function_ invoke__">new</span>(<span class="number">1</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">cnt</span> = <span class="number">3</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore2</span> = semaphore.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="comment">// semaphore_wait starts empty until thread 1 releases</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore_wait</span> = Arc::<span class="title function_ invoke__">new</span>(Semaphore::<span class="title function_ invoke__">new</span>(<span class="number">0</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore_wait2</span> = semaphore_wait.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="comment">// name tasks so they show up in the console (plain tokio::spawn won&#x27;t)</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = task::Builder::<span class="title function_ invoke__">default</span>()</span><br><span class="line">        .<span class="title function_ invoke__">name</span>(<span class="string">&quot;t1&quot;</span>)</span><br><span class="line">        .<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</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>..cnt &#123;</span><br><span class="line">                <span class="keyword">let</span> <span class="variable">permit</span> = semaphore.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">                <span class="built_in">print!</span>(<span class="string">&quot;1 &quot;</span>);</span><br><span class="line">                <span class="comment">// longer sleeps make the timeline easier to read</span></span><br><span class="line">                <span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_secs</span>(i)).<span class="keyword">await</span>;</span><br><span class="line">                permit.<span class="title function_ invoke__">forget</span>();</span><br><span class="line">                semaphore_wait2.<span class="title function_ invoke__">add_permits</span>(<span class="number">1</span>);</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;)</span><br><span class="line">        .<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t2</span> = task::Builder::<span class="title function_ invoke__">default</span>()</span><br><span class="line">        .<span class="title function_ invoke__">name</span>(<span class="string">&quot;t2&quot;</span>)</span><br><span class="line">        .<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</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>..cnt &#123;</span><br><span class="line">                <span class="keyword">let</span> <span class="variable">permit</span> = semaphore_wait.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">                <span class="built_in">print!</span>(<span class="string">&quot;2 &quot;</span>);</span><br><span class="line">                <span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_secs</span>(i)).<span class="keyword">await</span>;</span><br><span class="line">                permit.<span class="title function_ invoke__">forget</span>();</span><br><span class="line">                semaphore2.<span class="title function_ invoke__">add_permits</span>(<span class="number">1</span>);</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;)</span><br><span class="line">        .<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line"></span><br><span class="line">    tokio::try_join!(t1, t2).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="What-you-see"><a href="#What-you-see" class="headerlink" title="What you see"></a>What you see</h2><p>Switch between <strong>task</strong> view (<code>t</code>) and <strong>resource</strong> view (<code>r</code>).</p><h3 id="Tasks"><a href="#Tasks" class="headerlink" title="Tasks"></a>Tasks</h3><p>Per task you get time buckets (<code>Total</code>, <code>Busy</code>, <code>Sched</code>, <code>Idle</code>), poll counts, and state.</p><blockquote><p>For what those timers mean, see <a href="https://hegdenu.net/posts/task-scheduled-time-in-console/">task-scheduled-time-in-console</a>.</p></blockquote><p><img decoding="async" loading="lazy" src="/images/rust/async-task.webp" alt="task"></p><p>Arrow keys move the selection; Enter drills into a row (e.g. <code>task-t2</code>) for waker details and finer-grained timing—handy for spotting stragglers.</p><p><img decoding="async" loading="lazy" src="/images/rust/async-task-detail.webp" alt="task-detail"></p><h3 id="Resources"><a href="#Resources" class="headerlink" title="Resources"></a>Resources</h3><p>The resource view lists which async primitives were exercised.</p><p><img decoding="async" loading="lazy" src="/images/rust/async-resource.webp" alt="resource"></p><p>Expand a row for per-call timing—for example the three <code>semaphore_wait.acquire</code> calls on <code>t2</code>.</p><p><img decoding="async" loading="lazy" src="/images/rust/async-resource-detail.webp" alt="resource-details"></p><p>Full sample: <a href="https://github.com/NewbMiao/rust-koan/tree/master/tokio-play">tokio-play</a></p><p>More examples: <a href="https://github.com/tokio-rs/console/tree/main/console-subscriber/examples">console-subscriber&#x2F;examples</a></p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-tokio-task-tracing.html</id>
    <link href="https://newbmiao.github.io/rust-tokio-task-tracing.html"/>
    <published>2024-01-26T11:02:37.000Z</published>
    <summary>Wire console-subscriber and tokio-console to inspect async tasks, polls, and resource waits.</summary>
    <title>tokio-console — observe Tokio task scheduling and runtime behavior</title>
    <updated>2026-11-20T12:30:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="rayon" scheme="https://newbmiao.github.io/tags/rayon/"/>
    <content>
      <![CDATA[<p><strong>Rayon</strong> parallelizes CPU-bound iterators: swap in <code>par_iter</code> (and friends), keep order when Rayon documents it, and let the type system reject data races at compile time.</p><span id="more"></span><h2 id="Serial-to-parallel"><a href="#Serial-to-parallel" class="headerlink" title="Serial to parallel"></a>Serial to parallel</h2><p>A synchronous sum:</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">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">   <span class="keyword">let</span> <span class="variable">sum</span>: <span class="type">i32</span> = (<span class="number">0</span>..<span class="number">100</span>)</span><br><span class="line">        .<span class="title function_ invoke__">into_iter</span>()</span><br><span class="line">        .<span class="title function_ invoke__">map</span>(|i| &#123;</span><br><span class="line">            <span class="comment">// Simulate some computation</span></span><br><span class="line">            <span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_nanos</span>(<span class="number">1</span>));</span><br><span class="line">            i</span><br><span class="line">        &#125;)</span><br><span class="line">        .<span class="title function_ invoke__">sum</span>();</span><br><span class="line">    <span class="built_in">assert_eq!</span>(sum, <span class="number">4950</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Parallel version: <code>into_iter</code> → <code>into_par_iter</code>.</p><p>Rayon parallelizes the work but still produces the same reduction result (order of the range is preserved for this pattern):</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> rayon::prelude::*;</span><br><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> <span class="variable">sum</span>: <span class="type">i32</span> = (<span class="number">0</span>..<span class="number">100</span>)</span><br><span class="line">        .<span class="title function_ invoke__">into_par_iter</span>() <span class="comment">// here</span></span><br><span class="line">        .<span class="title function_ invoke__">map</span>(|i| &#123;</span><br><span class="line">            <span class="comment">// Simulate some computation</span></span><br><span class="line">            <span class="title function_ invoke__">sleep</span>(Duration::<span class="title function_ invoke__">from_nanos</span>(<span class="number">1</span>));</span><br><span class="line">            i</span><br><span class="line">        &#125;)</span><br><span class="line">        .<span class="title function_ invoke__">sum</span>();</span><br><span class="line">    <span class="built_in">assert_eq!</span>(sum, <span class="number">4950</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>On a 10-core M1 Pro, <code>divan</code> showed a clear win for this toy loop:</p><table><thead><tr><th>Benchmark</th><th>Fastest</th><th>Slowest</th><th>Median</th><th>Mean</th><th>Samples</th><th>Iterations</th></tr></thead><tbody><tr><td>iter</td><td>549.2 µs</td><td>1.244 ms</td><td>687.4 µs</td><td>738.5 µs</td><td>100</td><td>100</td></tr><tr><td>par_iter</td><td>195 µs</td><td>488.1 µs</td><td>315.1 µs</td><td>321.9 µs</td><td>100</td><td>100</td></tr></tbody></table><!-- ![bench](images/rust/rayon_par_bench.png) --><h2 id="What’s-under-the-hood"><a href="#What’s-under-the-hood" class="headerlink" title="What’s under the hood"></a>What’s under the hood</h2><p>Rayon backs parallel iterators with a <strong>work-stealing thread pool</strong>. By default the pool size matches logical CPU cores.</p><p>For each parallel job, Rayon splits work into subtasks (roughly sized for the pool) and queues them per thread.</p><p>If some threads are idle while others still have local queues, idle workers <strong>steal</strong> tasks from busy queues so cores stay fed.</p><p>Partial results are merged pairwise until the full answer is ready.</p><p>Splitting plus stealing is the divide-and-conquer bit that makes <code>par_iter</code> feel magical from the call site.</p><h2 id="join"><a href="#join" class="headerlink" title="join"></a>join</h2><p>Lower in the stack, <code>rayon::join</code> runs two closures in parallel and returns both outputs:</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">use</span> rayon::prelude::*;</span><br><span class="line"></span><br><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> <span class="variable">v1</span> = <span class="built_in">vec!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">v2</span> = <span class="built_in">vec!</span>[<span class="number">6</span>, <span class="number">7</span>, <span class="number">8</span>, <span class="number">9</span>, <span class="number">10</span>];</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> (sum1, sum2) = rayon::<span class="title function_ invoke__">join</span>(</span><br><span class="line">        || v1.<span class="title function_ invoke__">par_iter</span>().sum::&lt;<span class="type">i32</span>&gt;(), </span><br><span class="line">        || v2.<span class="title function_ invoke__">par_iter</span>().sum::&lt;<span class="type">i32</span>&gt;()</span><br><span class="line">    );</span><br><span class="line"></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;sum1: &#123;&#125;, sum2: &#123;&#125;&quot;</span>, sum1, sum2);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="par-bridge"><a href="#par-bridge" class="headerlink" title="par_bridge"></a>par_bridge</h2><p><code>par_iter</code> shines on indexed or slice-backed data. For blocking sources—channels, files, network—use <strong><code>par_bridge</code></strong>.</p><p>There’s overhead: items are pulled one at a time and handed to the pool, and <strong>order is not preserved</strong>. Sort or reorder afterward if you care.</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="keyword">use</span> rayon::iter::ParallelBridge;</span><br><span class="line"><span class="keyword">use</span> rayon::prelude::ParallelIterator;</span><br><span class="line"><span class="keyword">use</span> std::sync::mpsc::channel;</span><br><span class="line"></span><br><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> <span class="variable">rx</span> = &#123;</span><br><span class="line">        <span class="keyword">let</span> (tx, rx) = <span class="title function_ invoke__">channel</span>();</span><br><span class="line"></span><br><span class="line">        (<span class="number">1</span>..=<span class="number">3</span>).<span class="title function_ invoke__">into_iter</span>().<span class="title function_ invoke__">for_each</span>(|i| &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">_</span> = tx.<span class="title function_ invoke__">send</span>(i);</span><br><span class="line">        &#125;);</span><br><span class="line"></span><br><span class="line">        rx</span><br><span class="line">    &#125;;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">output</span>: <span class="type">Vec</span>&lt;<span class="type">i32</span>&gt; = rx.<span class="title function_ invoke__">into_iter</span>().<span class="title function_ invoke__">par_bridge</span>().<span class="title function_ invoke__">collect</span>();</span><br><span class="line">    output.<span class="title function_ invoke__">sort_unstable</span>(); <span class="comment">// restore order</span></span><br><span class="line"></span><br><span class="line">    <span class="built_in">assert_eq!</span>(&amp;*output, &amp;[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>]);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Not every <code>for</code> loop deserves Rayon—thread scheduling has cost. For cheap scans, stay serial. For heavier per-item work, <code>into_par_iter</code> is often the fastest one-line change.</p><p>Background: <a href="https://smallcultfollowing.com/babysteps/blog/2015/12/18/rayon-data-parallelism-in-rust/">Rayon: data parallelism in Rust</a></p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-rayon-parallel.html</id>
    <link href="https://newbmiao.github.io/rust-rayon-parallel.html"/>
    <published>2024-01-13T03:43:34.000Z</published>
    <summary>Turn sequential iterators into parallel ones with Rayon’s thread pool and work stealing.</summary>
    <title>Rayon — data parallelism with par_iter and work stealing</title>
    <updated>2026-11-20T12:30:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="future" scheme="https://newbmiao.github.io/tags/future/"/>
    <content>
      <![CDATA[<p>In the <a href="/rust-async-future.html">previous post</a>, a <code>Future</code> runs when you <code>.await</code> it—and that wait blocks the <strong>current task</strong> until that future completes.</p><p>If every async operation had to finish before the next one started, you’d be back to serial code. Here we look at Tokio patterns for real concurrency across multiple futures.</p><span id="more"></span><h2 id="join"><a href="#join" class="headerlink" title="join"></a>join</h2><p>When you want every branch to finish before you continue, run them together and wait for all results. <code>join!</code> does that:</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">async</span> <span class="keyword">fn</span> <span class="title function_">async_fn1</span>() <span class="punctuation">-&gt;</span> <span class="type">u32</span> &#123;</span><br><span class="line">    <span class="number">1</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_">async_fn2</span>() <span class="punctuation">-&gt;</span> <span class="type">u32</span> &#123;</span><br><span class="line">    <span class="number">2</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> (first, second) = tokio::join!(<span class="title function_ invoke__">async_fn1</span>(), <span class="title function_ invoke__">async_fn2</span>());</span><br><span class="line">    <span class="built_in">assert_eq!</span>(first, <span class="number">1</span>);</span><br><span class="line">    <span class="built_in">assert_eq!</span>(second, <span class="number">2</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="try-join"><a href="#try-join" class="headerlink" title="try_join"></a>try_join</h2><p>Branches can return <code>Err</code>. <code>try_join!</code> short-circuits on the first error instead of waiting for the rest:</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">async</span> <span class="keyword">fn</span> <span class="title function_">async_fn1</span>() <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="type">u32</span>, &amp;<span class="symbol">&#x27;static</span> <span class="type">str</span>&gt; &#123;</span><br><span class="line">    <span class="title function_ invoke__">Ok</span>(<span class="number">1</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_">async_fn2</span>() <span class="punctuation">-&gt;</span> <span class="type">Result</span>&lt;<span class="type">u32</span>, &amp;<span class="symbol">&#x27;static</span> <span class="type">str</span>&gt; &#123;</span><br><span class="line">    <span class="title function_ invoke__">Err</span>(<span class="string">&quot;async_fn2 failed&quot;</span>)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="variable">res</span> = tokio::try_join!(<span class="title function_ invoke__">async_fn1</span>(), <span class="title function_ invoke__">async_fn2</span>());</span><br><span class="line"></span><br><span class="line">    <span class="keyword">match</span> res &#123;</span><br><span class="line">        <span class="title function_ invoke__">Ok</span>((first, second)) =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;first = &#123;&#125;, second = &#123;&#125;&quot;</span>, first, second);</span><br><span class="line">        &#125;</span><br><span class="line">        <span class="title function_ invoke__">Err</span>(err) =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;error: &#123;&#125;&quot;</span>, err);</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><h2 id="spawn"><a href="#spawn" class="headerlink" title="spawn"></a>spawn</h2><p><code>join!</code> overlaps futures but still runs them on the <strong>same task</strong>. To give each piece of work its own task, use <code>spawn</code>.</p><p>A spawned task starts immediately in the background—even if you never <code>.await</code> its <code>JoinHandle</code>.</p><p>It’s like thread <code>spawn</code>, but the unit is a <strong>task</strong>, not an OS thread.</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><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> futures::future::join_all;</span><br><span class="line"><span class="keyword">use</span> tokio::&#123;join, task::JoinHandle&#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_">async_op</span>(id: <span class="type">i32</span>) <span class="punctuation">-&gt;</span> <span class="type">String</span> &#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">s</span> = <span class="built_in">format!</span>(<span class="string">&quot;Start task &#123;&#125;&quot;</span>, id);</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;&#125;&quot;</span>, s);</span><br><span class="line">    s</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="variable">ops</span> = <span class="built_in">vec!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>];</span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">tasks</span>: <span class="type">Vec</span>&lt;JoinHandle&lt;<span class="type">String</span>&gt;&gt; = ops</span><br><span class="line">        .<span class="title function_ invoke__">into_iter</span>()</span><br><span class="line">        .<span class="title function_ invoke__">map</span>(|op| tokio::<span class="title function_ invoke__">spawn</span>(<span class="title function_ invoke__">async_op</span>(op)))</span><br><span class="line">        .<span class="title function_ invoke__">collect</span>();</span><br><span class="line"></span><br><span class="line">    <span class="comment">// option 1</span></span><br><span class="line">    <span class="comment">// let outputs = join!(</span></span><br><span class="line">    <span class="comment">//     tasks.pop().unwrap(),</span></span><br><span class="line">    <span class="comment">//     tasks.pop().unwrap(),</span></span><br><span class="line">    <span class="comment">//     tasks.pop().unwrap()</span></span><br><span class="line">    <span class="comment">// );</span></span><br><span class="line"></span><br><span class="line">    <span class="comment">// println!(&quot;&#123;:?&#125;&quot;, outputs);</span></span><br><span class="line">    <span class="comment">// tuple of results:</span></span><br><span class="line">    <span class="comment">// (Ok(&quot;Start task 3&quot;), Ok(&quot;Start task 2&quot;), Ok(&quot;Start task 1&quot;))</span></span><br><span class="line"></span><br><span class="line">    <span class="comment">// option 2</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">outputs</span> = <span class="title function_ invoke__">join_all</span>(tasks).<span class="keyword">await</span>;</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, outputs);</span><br><span class="line">    <span class="comment">// vector of results:</span></span><br><span class="line">    <span class="comment">// [Ok(&quot;Start task 1&quot;), Ok(&quot;Start task 2&quot;), Ok(&quot;Start task 3&quot;)]</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="select"><a href="#select" class="headerlink" title="select"></a>select</h2><p>When the <strong>first</strong> completing branch should win and the others should be dropped (releasing their futures), use <code>select!</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">async_fn1</span>() &#123;&#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_">async_fn2</span>() &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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">    tokio::<span class="built_in">select!</span> &#123;</span><br><span class="line">        _ = <span class="title function_ invoke__">async_fn1</span>() =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;async_fn1() completed first&quot;</span>)</span><br><span class="line">        &#125;</span><br><span class="line">        _ = <span class="title function_ invoke__">async_fn2</span>() =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;async_fn2() completed first&quot;</span>)</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><h3 id="Ordered-polling"><a href="#Ordered-polling" class="headerlink" title="Ordered polling"></a>Ordered polling</h3><p><code>select!</code> does <strong>not</strong> guarantee branch order—it may poll branches in arbitrary order. For deterministic priority, use <code>biased</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></pre></td><td class="code"><pre><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="keyword">mut </span><span class="variable">count</span> = <span class="number">0u8</span>;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">loop</span> &#123;</span><br><span class="line">        tokio::<span class="built_in">select!</span> &#123;</span><br><span class="line">            <span class="comment">// poll in source order</span></span><br><span class="line">            biased;</span><br><span class="line"></span><br><span class="line">            _ = <span class="keyword">async</span> &#123;&#125;, <span class="keyword">if</span> count &lt; <span class="number">1</span> =&gt; &#123;</span><br><span class="line">                count += <span class="number">1</span>;</span><br><span class="line">                <span class="built_in">assert_eq!</span>(count, <span class="number">1</span>);</span><br><span class="line">            &#125;</span><br><span class="line">            _ = <span class="keyword">async</span> &#123;&#125;, <span class="keyword">if</span> count &lt; <span class="number">2</span> =&gt; &#123;</span><br><span class="line">                count += <span class="number">1</span>;</span><br><span class="line">                <span class="built_in">assert_eq!</span>(count, <span class="number">2</span>);</span><br><span class="line">            &#125;</span><br><span class="line"></span><br><span class="line">            <span class="keyword">else</span> =&gt; &#123;</span><br><span class="line">                <span class="keyword">break</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><h3 id="Preconditions"><a href="#Preconditions" class="headerlink" title="Preconditions"></a>Preconditions</h3><p>Branches can use <code>if precondition</code>. When the loop reaches a branch, a true condition runs it; a false one marks the branch <strong>disabled</strong> for that <code>select!</code> round.</p><p>On the next loop iteration, disabled flags reset.</p><p>If every branch is disabled, you need an <code>else</code> branch—or Tokio panics: <code>all branches are disabled and there is no else branch</code>.</p><h3 id="Rewriting-branches"><a href="#Rewriting-branches" class="headerlink" title="Rewriting branches"></a>Rewriting branches</h3><p>You can swap what a pinned branch points at—for example with <code>Pin::set</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><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="keyword">use</span> tokio::select;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">action</span>(input: <span class="type">Option</span>&lt;<span class="type">i32</span>&gt;) <span class="punctuation">-&gt;</span> <span class="type">Option</span>&lt;<span class="type">String</span>&gt; &#123;</span><br><span class="line">    <span class="keyword">match</span> input &#123;</span><br><span class="line">        <span class="title function_ invoke__">Some</span>(input) =&gt; <span class="title function_ invoke__">Some</span>(input.<span class="title function_ invoke__">to_string</span>()),</span><br><span class="line">        <span class="literal">None</span> =&gt; <span class="keyword">return</span> <span class="literal">None</span>,</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> (tx, <span class="keyword">mut</span> rx) = tokio::sync::mpsc::<span class="title function_ invoke__">channel</span>(<span class="number">128</span>);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">done</span> = <span class="literal">false</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">operation</span> = <span class="title function_ invoke__">action</span>(<span class="literal">None</span>);</span><br><span class="line">    tokio::pin!(operation);</span><br><span class="line"></span><br><span class="line">    tokio::<span class="title function_ invoke__">spawn</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">_</span> = tx.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="keyword">await</span>;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">_</span> = tx.<span class="title function_ invoke__">send</span>(<span class="number">3</span>).<span class="keyword">await</span>;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">_</span> = tx.<span class="title function_ invoke__">send</span>(<span class="number">2</span>).<span class="keyword">await</span>;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">loop</span> &#123;</span><br><span class="line">        <span class="built_in">select!</span> &#123;</span><br><span class="line">            res = &amp;<span class="keyword">mut</span> operation, <span class="keyword">if</span> !done =&gt; &#123;</span><br><span class="line">                <span class="built_in">println!</span>(<span class="string">&quot;Got = &#123;:?&#125;&quot;</span>, res);</span><br><span class="line">                done = <span class="literal">true</span>;</span><br><span class="line"></span><br><span class="line">                <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Some</span>(_) = res &#123;</span><br><span class="line">                    <span class="keyword">return</span>;</span><br><span class="line">                &#125;</span><br><span class="line">            &#125;</span><br><span class="line">            <span class="title function_ invoke__">Some</span>(v) = rx.<span class="title function_ invoke__">recv</span>() =&gt; &#123;</span><br><span class="line">                <span class="keyword">if</span> v % <span class="number">2</span> == <span class="number">0</span> &#123;</span><br><span class="line">                    <span class="comment">// `.set` is a method on `Pin`.</span></span><br><span class="line">                    operation.<span class="title function_ invoke__">set</span>(<span class="title function_ invoke__">action</span>(<span class="title function_ invoke__">Some</span>(v)));</span><br><span class="line">                    done = <span class="literal">false</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><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>The <code>if !done</code> guard matters: without it you might poll an already-finished future and hit <code>async fn resumed after completion</code>.</p><h3 id="Cancellation"><a href="#Cancellation" class="headerlink" title="Cancellation"></a>Cancellation</h3><p>When one <code>select!</code> branch completes, the others are <strong>cancelled</strong> via <code>Drop</code>—the runtime stops polling those futures.</p><p>For example, when a <code>oneshot::Receiver</code> is dropped on cancel, the sender sees <code>closed()</code> so it can clean up:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> tokio::sync::oneshot;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> (<span class="keyword">mut</span> tx1, rx1) = oneshot::channel::&lt;<span class="type">u32</span>&gt;();</span><br><span class="line">    <span class="keyword">let</span> (tx2, rx2) = oneshot::<span class="title function_ invoke__">channel</span>();</span><br><span class="line"></span><br><span class="line">    tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">        tokio::<span class="built_in">select!</span> &#123;</span><br><span class="line">            _ = tx1.<span class="title function_ invoke__">closed</span>() =&gt; &#123;</span><br><span class="line">                <span class="comment">// `val = rx1` is canceled</span></span><br><span class="line">                <span class="built_in">println!</span>(<span class="string">&quot;tx1 closed&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">    tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">_</span> = tx2.<span class="title function_ invoke__">send</span>(<span class="string">&quot;two&quot;</span>);</span><br><span class="line">    &#125;);</span><br><span class="line">    tokio::<span class="built_in">select!</span> &#123;</span><br><span class="line">        val = rx1 =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;rx1 completed first with &#123;:?&#125;&quot;</span>, val);</span><br><span class="line"></span><br><span class="line">        &#125;</span><br><span class="line">        val = rx2 =&gt; &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;rx2 completed first with &#123;:?&#125;&quot;</span>, val);</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>]]>
    </content>
    <id>https://newbmiao.github.io/rust-async-multi-future-concurrency.html</id>
    <link href="https://newbmiao.github.io/rust-async-multi-future-concurrency.html"/>
    <published>2024-01-08T06:34:39.000Z</published>
    <summary>join!, try_join!, spawn, and select! patterns for overlapping async work in Tokio.</summary>
    <title>Tokio — join, spawn, and select for concurrent Futures</title>
    <updated>2026-11-20T12:30:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="futures" scheme="https://newbmiao.github.io/tags/futures/"/>
    <content>
      <![CDATA[<p>Rust’s <code>Future</code> is the core abstraction for async programming. What follows is how <code>async</code>&#x2F;<code>await</code>, polling, and the runtime stack fit together.</p><p><code>async</code> gives you cheap, suspendable functions; they only run when you <code>.await</code> them and the executor polls them.</p><p>Compared with one OS thread per bit of concurrency, async tasks are lighter—you can host many concurrent operations without paying for a thread each time.</p><p>A minimal async entry point:</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">async</span> <span class="keyword">fn</span> <span class="title function_">async_fn</span>() &#123;</span><br><span class="line">    <span class="comment">// handle async logic</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="title function_ invoke__">async_fn</span>().<span class="keyword">await</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><span id="more"></span><h2 id="State-machine"><a href="#State-machine" class="headerlink" title="State machine"></a>State machine</h2><p><code>async</code> is mostly compiler sugar: it implements <code>Future</code> for you and stores progress in a state machine.</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">trait</span> <span class="title class_">Future</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Output</span>;</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>: 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">    ) <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><code>poll</code> asks whether the work is done. A task is either <code>Pending</code> (yield control until something can make progress) or <code>Ready</code> (finished). The executor keeps polling until <code>Ready</code>.</p><p>We can see that flow by implementing a small <code>Delay</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::future::Future;</span><br><span class="line"><span class="keyword">use</span> std::pin::Pin;</span><br><span class="line"><span class="keyword">use</span> std::task::&#123;Context, Poll&#125;;</span><br><span class="line"><span class="keyword">use</span> std::time::&#123;Duration, Instant&#125;;</span><br><span class="line"></span><br><span class="line"><span class="keyword">struct</span> <span class="title class_">Delay</span> &#123;</span><br><span class="line">    when: Instant,</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_">Future</span> <span class="keyword">for</span> <span class="title class_">Delay</span> &#123;</span><br><span class="line">    <span class="keyword">type</span> <span class="title class_">Output</span> = &amp;<span class="symbol">&#x27;static</span> <span class="type">str</span>;</span><br><span class="line"></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;&amp;<span class="symbol">&#x27;static</span> <span class="type">str</span>&gt; &#123;</span><br><span class="line">        <span class="keyword">if</span> Instant::<span class="title function_ invoke__">now</span>() &gt;= <span class="keyword">self</span>.when &#123;</span><br><span class="line">            Poll::<span class="title function_ invoke__">Ready</span>(<span class="string">&quot;done&quot;</span>)</span><br><span class="line">        &#125; <span class="keyword">else</span> &#123;</span><br><span class="line">            <span class="comment">// Not ready yet — schedule another wake</span></span><br><span class="line">            cx.<span class="title function_ invoke__">waker</span>().<span class="title function_ invoke__">wake_by_ref</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><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="variable">when</span> = Instant::<span class="title function_ invoke__">now</span>() + Duration::<span class="title function_ invoke__">from_millis</span>(<span class="number">3</span>);</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">future</span> = Delay &#123; when &#125;;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">out</span> = future.<span class="keyword">await</span>;</span><br><span class="line">    <span class="built_in">assert_eq!</span>(out, <span class="string">&quot;done&quot;</span>);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Each <code>poll</code> checks the deadline. If time has passed, return <code>Ready</code>; otherwise schedule another wake and return <code>Pending</code>.</p><p>We have a state machine—who drives it?</p><h2 id="Scheduling"><a href="#Scheduling" class="headerlink" title="Scheduling"></a>Scheduling</h2><p>Rust needs a <strong>runtime</strong> to schedule async <strong>tasks</strong>. The runtime polls futures and advances work.</p><p>When a future returns <code>Pending</code>, the task yields and arranges to be <strong>woken</strong> later.</p><p>Typical path when work completes on the first poll:</p><pre class="mermaid">graph TD    executor --> task    task -- poll --> future    future -- ready --> task</pre><p>When the future is <code>Pending</code>, something must schedule the next wake. The wake may run on a different task than the one that polled last time. The <strong>waker</strong> travels through <code>Context</code> on every <code>poll</code>:</p><pre class="mermaid">graph TD    executor --> task    executor --> waker    executor -.-> task    task -- poll with context (waker) --> future    future -- update --> waker    future -- pending --> task    waker -- wake --> executor</pre><h2 id="Runtime"><a href="#Runtime" class="headerlink" title="Runtime"></a>Runtime</h2><p>Scheduling lives in a runtime. Rust’s standard library does not ship one; most projects use <strong>Tokio</strong>.</p><p><code>#[tokio::main]</code> expands to a multi-thread runtime that blocks until the async <code>main</code> finishes:</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="meta">#[tokio::main]</span></span><br><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 class="built_in">println!</span>(<span class="string">&quot;hello&quot;</span>);</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">// tranform to</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">    tokio::runtime::Builder::<span class="title function_ invoke__">new_multi_thread</span>()</span><br><span class="line">        .<span class="title function_ invoke__">enable_all</span>()</span><br><span class="line">        .<span class="title function_ invoke__">build</span>()</span><br><span class="line">        .<span class="title function_ invoke__">unwrap</span>()</span><br><span class="line">        .<span class="title function_ invoke__">block_on</span>(<span class="keyword">async</span> &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;Hello world&quot;</span>);</span><br><span class="line">        &#125;)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Single-thread flavor:</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="meta">#[tokio::main(flavor = <span class="string">&quot;current_thread&quot;</span>)]</span></span><br><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 class="built_in">println!</span>(<span class="string">&quot;Hello world&quot;</span>);</span><br><span class="line">&#125;</span><br><span class="line"><span class="comment">// tranform to</span></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">    tokio::runtime::Builder::<span class="title function_ invoke__">new_current_thread</span>()</span><br><span class="line">        .<span class="title function_ invoke__">enable_all</span>()</span><br><span class="line">        .<span class="title function_ invoke__">build</span>()</span><br><span class="line">        .<span class="title function_ invoke__">unwrap</span>()</span><br><span class="line">        .<span class="title function_ invoke__">block_on</span>(<span class="keyword">async</span> &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;Hello world&quot;</span>);</span><br><span class="line">        &#125;)</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="async"><a href="#async" class="headerlink" title="async"></a>async</h2><p>You rarely implement <code>Future</code> by hand. <code>async fn</code> is enough—the <code>Delay</code> example collapses to something 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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::Arc;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"><span class="keyword">use</span> std::time::&#123;Duration, Instant&#125;;</span><br><span class="line"><span class="keyword">use</span> tokio::sync::Notify;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">delay</span>(dur: Duration) &#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">when</span> = Instant::<span class="title function_ invoke__">now</span>() + dur;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">notify</span> = Arc::<span class="title function_ invoke__">new</span>(Notify::<span class="title function_ invoke__">new</span>());</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">notify_clone</span> = notify.<span class="title function_ invoke__">clone</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="keyword">let</span> <span class="variable">now</span> = Instant::<span class="title function_ invoke__">now</span>();</span><br><span class="line"></span><br><span class="line">        <span class="keyword">if</span> now &lt; when &#123;</span><br><span class="line">            thread::<span class="title function_ invoke__">sleep</span>(when - now);</span><br><span class="line">        &#125;</span><br><span class="line"></span><br><span class="line">        notify_clone.<span class="title function_ invoke__">notify_one</span>();</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    notify.<span class="title function_ invoke__">notified</span>().<span class="keyword">await</span>;</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="title function_ invoke__">delay</span>(Duration::<span class="title function_ invoke__">from_secs</span>(<span class="number">1</span>)).<span class="keyword">await</span>;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="pin"><a href="#pin" class="headerlink" title="pin"></a>pin</h2><p>Remember <code>Pin&lt;&amp;mut Self&gt;</code> on <code>poll</code>—why pin a 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></pre></td><td class="code"><pre><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">my_async_fn</span>() &#123;</span><br><span class="line">    <span class="comment">// async logic here</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="keyword">mut </span><span class="variable">future</span> = <span class="title function_ invoke__">my_async_fn</span>();</span><br><span class="line">    (&amp;<span class="keyword">mut</span> future).<span class="keyword">await</span>;</span><br><span class="line">    <span class="comment">// error:</span></span><br><span class="line">    <span class="comment">// within `impl Future&lt;Output = ()&gt;`, the trait `Unpin` is not implemented for `[async fn body@src/main.rs:1:24: 3:2]`</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Polling through a stack reference fails unless the future is <code>Unpin</code>.</p><p>A <code>Future</code> from <code>async</code> is a state machine that <strong>moves</strong> while polled. If it held stack references, those addresses would go stale when the state machine moves—classic use-after-move.</p><p><code>Unpin</code> marks types that are safe to move while referenced. Most ordinary types are <code>Unpin</code>. For <code>!Unpin</code> futures, pin them on the stack (<code>pin!</code>) or heap (<code>Box::pin</code>) so the address stays valid until completion:</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="keyword">use</span> tokio::pin;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">fn</span> <span class="title function_">my_async_fn</span>() &#123;</span><br><span class="line">    <span class="comment">// async logic here</span></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="variable">future</span> = <span class="title function_ invoke__">my_async_fn</span>();</span><br><span class="line">    <span class="comment">// option 1</span></span><br><span class="line">    pin!(future);</span><br><span class="line">    (&amp;<span class="keyword">mut</span> future).<span class="keyword">await</span>;</span><br><span class="line"></span><br><span class="line">    <span class="comment">// option 2</span></span><br><span class="line">    <span class="comment">// let pinned_fut = Box::pin(future);</span></span><br><span class="line">    <span class="comment">// pinned_fut.await;</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><hr><p>That’s enough for one sitting. Next up: <a href="/rust-async-multi-future-concurrency.html">running several futures concurrently</a>.</p><p>More on pinning: <a href="https://rust-lang.github.io/async-book/04_pinning/01_chapter.html">Pinning</a></p><p>Tokio’s runtime tour: <a href="https://tokio.rs/tokio/tutorial/async">Async in depth</a></p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-async-future.html</id>
    <link href="https://newbmiao.github.io/rust-async-future.html"/>
    <published>2024-01-05T23:10:51.000Z</published>
    <summary>How Rust models async work with Future, executors, Tokio, and why Pin matters.</summary>
    <title>Rust Future — poll, state machines, Tokio runtime, and Pin</title>
    <updated>2026-11-20T12:30:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="atomic" scheme="https://newbmiao.github.io/tags/atomic/"/>
    <content>
      <![CDATA[<p><code>Mutex</code> and <code>Condvar</code> are higher-level ways to share data between threads in Rust. Lower down the stack you have <strong>atomics</strong> — hardware-backed operations on individual locations.</p><p>Below: <code>Atomic*</code> types and <code>Ordering</code>, mostly through runnable examples.</p><span id="more"></span><p>Why bother with atomics if <code>Mutex</code> already exists? Compare the two.</p><h2 id="Mutex-vs-Atomic"><a href="#Mutex-vs-Atomic" class="headerlink" title="Mutex vs Atomic"></a>Mutex vs Atomic</h2><p><strong>1. How they touch data</strong></p><p><code>Mutex</code> enforces <strong>exclusive access</strong>: many threads may try to write, but only one holds the lock at a time. Everyone else waits until it is released.</p><p><code>Atomic</code> operations are indivisible at the machine level — built on CPU primitives like load, store, compare-and-swap (CAS), and fetch-add. Each operation completes fully or not at all; there is no halfway state where another thread can tear the update apart.</p><p>So atomics lean on non-splittable instructions for <strong>lock-free</strong> access to a single memory location.</p><p><strong>2. Critical sections</strong></p><p>With <code>Mutex</code>, the protected region sits between <code>lock()</code> and <code>unlock()</code>.</p><p>An atomic only guarantees atomicity for <strong>that one address</strong>. If your critical section involves more state, you typically combine load&#x2F;store&#x2F;CAS with a spin loop — the lower-level cousin of a mutex. That shows up when you care about every nanosecond.</p><p>Pseudo-code for a flag-based critical section (the <code>Ordering</code> section below makes this concrete):</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">thread <span class="number">1</span>: </span><br><span class="line">    <span class="comment">// set flag when condition is ready</span></span><br><span class="line">    store/CAS flag: <span class="literal">false</span><span class="punctuation">-&gt;</span><span class="literal">true</span></span><br><span class="line">thread <span class="number">2</span>: </span><br><span class="line">    <span class="comment">// spin until flag is set (like blocking on a lock)</span></span><br><span class="line">    <span class="keyword">while</span> load flag == <span class="literal">false</span> &#123;&#125;;</span><br><span class="line">    <span class="comment">// critical section</span></span><br><span class="line">    ...</span><br></pre></td></tr></table></figure><h2 id="First-look-at-Atomic"><a href="#First-look-at-Atomic" class="headerlink" title="First look at Atomic"></a>First look at Atomic</h2><p>A minimal two-thread 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><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">use</span> std::&#123;</span><br><span class="line">    sync::atomic::&#123;AtomicBool, Ordering&#125;,</span><br><span class="line">    thread,</span><br><span class="line">&#125;;</span><br><span class="line"><span class="keyword">static</span> FLAG: AtomicBool = AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>);</span><br><span class="line"></span><br><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> <span class="variable">a</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        FLAG.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::Relaxed);</span><br><span class="line">    &#125;);</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">b</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        <span class="keyword">if</span> FLAG.<span class="title function_ invoke__">load</span>(Ordering::Relaxed) &#123;</span><br><span class="line">            <span class="built_in">println!</span>(<span class="string">&quot;Relaxed: Flag is set!&quot;</span>);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line">    a.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    b.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Two threads store and load <code>FLAG</code>. The reader prints when it sees <code>true</code>.</p><p>You might run this and <strong>not</strong> see the print. Scheduling could run <code>load</code> before <code>store</code>, and that alone would explain a miss — but that is not the whole story.</p><p>The rest involves <strong>instruction reordering</strong> and atomic <code>Ordering</code>.</p><h2 id="Instruction-reordering"><a href="#Instruction-reordering" class="headerlink" title="Instruction reordering"></a>Instruction reordering</h2><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">fn</span> <span class="title function_">f</span>(a: &amp;<span class="keyword">mut</span> <span class="type">i32</span>, b: &amp;<span class="keyword">mut</span> <span class="type">i32</span>) &#123;</span><br><span class="line">    *a += <span class="number">1</span>;</span><br><span class="line">    *b += <span class="number">1</span>;</span><br><span class="line">    *a += <span class="number">1</span>;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>You write one sequence; the CPU or compiler may execute an equivalent faster one:</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">fn</span> <span class="title function_">f</span>(a: &amp;<span class="keyword">mut</span> <span class="type">i32</span>, b: &amp;<span class="keyword">mut</span> <span class="type">i32</span>) &#123;</span><br><span class="line">    *a += <span class="number">2</span>;</span><br><span class="line">    *b += <span class="number">1</span>;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Why?</p><p><strong>As long as single-thread semantics stay the same, instructions may be reordered for speed</strong> — execution order is not guaranteed to match source order.</p><p>On one thread that is often fine. Across threads, even two atomics in the same thread can be reordered relative to each other, so “I used atomics” does not automatically mean “I fixed the order other threads observe.”</p><p>Example — steps 1 and 2 in thread <code>b</code> are independent, so they may swap:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::&#123;</span><br><span class="line">    sync::atomic::&#123;AtomicI32, Ordering&#125;,</span><br><span class="line">    thread,</span><br><span class="line">&#125;;</span><br><span class="line"></span><br><span class="line"><span class="keyword">static</span> X: AtomicI32 = AtomicI32::<span class="title function_ invoke__">new</span>(<span class="number">0</span>);</span><br><span class="line"><span class="keyword">static</span> Y: AtomicI32 = AtomicI32::<span class="title function_ invoke__">new</span>(<span class="number">0</span>);</span><br><span class="line"></span><br><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> <span class="variable">a</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        <span class="keyword">let</span> <span class="variable">x</span> = X.<span class="title function_ invoke__">load</span>(Ordering::Relaxed);</span><br><span class="line">        Y.<span class="title function_ invoke__">store</span>(x, Ordering::Relaxed);</span><br><span class="line">    &#125;);</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">b</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        <span class="comment">// 1</span></span><br><span class="line">        <span class="keyword">let</span> <span class="variable">y</span> = Y.<span class="title function_ invoke__">load</span>(Ordering::Relaxed);</span><br><span class="line">        <span class="comment">// 2</span></span><br><span class="line">        X.<span class="title function_ invoke__">store</span>(<span class="number">42</span>, Ordering::Relaxed);</span><br><span class="line">    &#125;);</span><br><span class="line">    a.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    b.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    <span class="built_in">assert_eq!</span>(X.<span class="title function_ invoke__">load</span>(Ordering::Relaxed), <span class="number">42</span>);</span><br><span class="line">    <span class="comment">// possible: b&#x27;s 1 and 2 reordered to 2 then 1</span></span><br><span class="line">    <span class="built_in">assert_eq!</span>(Y.<span class="title function_ invoke__">load</span>(Ordering::Relaxed), <span class="number">42</span>); </span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p><code>Ordering</code> constrains <strong>when</strong> an atomic’s effect becomes visible to other threads, so concurrent updates are more predictable.</p><h2 id="Ordering"><a href="#Ordering" class="headerlink" title="Ordering"></a>Ordering</h2><p>Rust’s <code>Ordering</code> aligns with <a href="https://en.cppreference.com/w/cpp/atomic/memory_order">C++20 memory order</a> for the most part. The variants:</p><ul><li><strong>Relaxed</strong></li></ul><p>The weakest guarantee: the operation itself is atomic, but there is <strong>no ordering</strong> promise for how this store&#x2F;load relates to other memory accesses on other threads (as in the reordering example).</p><ul><li><strong>Acquire</strong></li></ul><p>For <strong>loads</strong>. No other reads or writes on this thread may be reordered <strong>before</strong> this load. Release stores to the same location from other threads that happened before you see the loaded value are visible.</p><ul><li><strong>Release</strong></li></ul><p>For <strong>stores</strong>. No other reads or writes on this thread may be reordered <strong>after</strong> this store. Threads that later do an Acquire load on the same location will see this write.</p><p>So pairing Release (writer) with Acquire (reader) is the usual handoff: “data is ready” on the flag, payload writes before the Release, reads after the Acquire.</p><p>See comments in the code for where reordering is forbidden:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::&#123;</span><br><span class="line">    sync::atomic::&#123;AtomicBool, Ordering&#125;,</span><br><span class="line">    thread,</span><br><span class="line">&#125;;</span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">    <span class="comment">// For stricter exploration, consider `loom`</span></span><br><span class="line">    <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..<span class="number">100000</span> &#123;</span><br><span class="line">        <span class="title function_ invoke__">acquire_release</span>()</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">fn</span> <span class="title function_">acquire_release</span>() &#123;</span><br><span class="line">    <span class="keyword">static</span> FLAG: AtomicBool = AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>);</span><br><span class="line">    <span class="keyword">static</span> <span class="keyword">mut</span> DATA: <span class="type">u64</span> = <span class="number">0</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">a</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        <span class="keyword">unsafe</span> &#123; DATA = <span class="number">42</span> &#125;;</span><br><span class="line">        FLAG.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::Release);</span><br><span class="line">        <span class="comment">// no reads/writes reordered after this store</span></span><br><span class="line">    &#125;);</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">b</span> = thread::<span class="title function_ invoke__">spawn</span>(|| &#123;</span><br><span class="line">        <span class="comment">// no reads/writes reordered before this load</span></span><br><span class="line">        <span class="keyword">while</span> !FLAG.<span class="title function_ invoke__">load</span>(Ordering::Acquire) &#123;&#125;</span><br><span class="line">        <span class="built_in">assert_eq!</span>(<span class="keyword">unsafe</span> &#123; DATA &#125;, <span class="number">42</span>);</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    a.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    b.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><ul><li><strong>AcqRel</strong></li></ul><p>For read-modify-write ops: Acquire semantics on the read side, Release on the write side.</p><ul><li><strong>SeqCst</strong></li></ul><p>Acquire&#x2F;Release plus a <strong>single total order</strong> of all SeqCst atomics that every thread agrees on. Interleavings can still vary run to run, but once a particular execution has happened, there is no alternate consistent ordering of those SeqCst operations — as if they ran on one global timeline.</p><p>Strictness ramp: Relaxed → Acquire&#x2F;Release → SeqCst, with cost usually going up as well.</p><p>Building a critical section with explicit orderings:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::atomic::&#123;AtomicBool, Ordering&#125;;</span><br><span class="line"><span class="keyword">use</span> std::sync::Arc;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><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> <span class="variable">lock</span> = Arc::<span class="title function_ invoke__">new</span>(AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">lock_clone_read</span> = lock.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">lock_clone_store</span> = lock.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">    thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">        lock.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::SeqCst);</span><br><span class="line">        <span class="comment">// critical section work</span></span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">while</span> !lock_clone_read.<span class="title function_ invoke__">load</span>(Ordering::Acquire) &#123;&#125;</span><br><span class="line"></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;Critical section!&quot;</span>);</span><br><span class="line"></span><br><span class="line">    lock_clone_store.<span class="title function_ invoke__">store</span>(<span class="literal">false</span>, Ordering::Release);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Seeing-the-difference-in-visibility"><a href="#Seeing-the-difference-in-visibility" class="headerlink" title="Seeing the difference in visibility"></a>Seeing the difference in visibility</h2><p>Does the ordering strength matter in practice? Try <code>Relaxed</code> first:</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::&#123;</span><br><span class="line">    sync::&#123;</span><br><span class="line">        atomic::&#123;AtomicBool, AtomicU64, Ordering&#125;,</span><br><span class="line">        Arc,</span><br><span class="line">    &#125;,</span><br><span class="line">    thread,</span><br><span class="line">&#125;;</span><br><span class="line"></span><br><span class="line"><span class="keyword">static</span> S: AtomicU64 = AtomicU64::<span class="title function_ invoke__">new</span>(<span class="number">0</span>);</span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">relaxed</span>() &#123;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">a</span> = Arc::<span class="title function_ invoke__">new</span>(AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">b</span> = Arc::<span class="title function_ invoke__">new</span>(AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">a_clone</span> = a.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">b_clone</span> = b.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">        a.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::Relaxed);</span><br><span class="line">        <span class="keyword">if</span> !b.<span class="title function_ invoke__">load</span>(Ordering::Relaxed) &#123;</span><br><span class="line">            S.<span class="title function_ invoke__">fetch_add</span>(<span class="number">1</span>, Ordering::Relaxed);</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">let</span> <span class="variable">t2</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">        b_clone.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::Relaxed);</span><br><span class="line">        <span class="keyword">if</span> !a_clone.<span class="title function_ invoke__">load</span>(Ordering::Relaxed) &#123;</span><br><span class="line">            S.<span class="title function_ invoke__">fetch_add</span>(<span class="number">1</span>, Ordering::Relaxed);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    t1.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    t2.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br><span class="line"></span><br><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> <span class="variable">cnt</span> = <span class="number">100000</span>;</span><br><span class="line">    <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">        <span class="title function_ invoke__">relaxed</span>();</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="comment">// result can be greater than 100000</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">s</span> = S.<span class="title function_ invoke__">load</span>(Ordering::SeqCst);</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;s: &#123;&#125;&quot;</span>, s);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p><code>S</code> often ends up <strong>above</strong> 100000. Why?</p><p>Both <code>AtomicBool</code>s start false. Each thread stores its flag true with <code>Relaxed</code>, then loads the other. If the load still sees false, it increments <code>S</code>.</p><p>Possibilities:</p><ol><li><p>Other thread’s instructions reordered  </p><ul><li>Store happens after the load; increment (under Relaxed).</li></ul></li><li><p>No reordering  </p><ul><li>Other thread has not stored yet → increment.  </li><li>Other thread stored but load does not see it yet → increment (Relaxed).  </li><li>Load sees the store → no increment.</li></ul></li></ol><p>Reordering plus weak visibility both push <code>S</code> up. Run 100000 iterations and overshooting 100000 is easy with <code>Relaxed</code>.</p><p>Switch the bool ops to <code>SeqCst</code>: no reordering like above, and a global order on those atomics. If the other thread’s store is before your load in that order, you see it — you do not get both threads thinking the partner is still false. <code>S</code> tops out at 100000.</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">let</span> <span class="variable">t1</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">    a.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::SeqCst);</span><br><span class="line">    <span class="keyword">if</span> !b.<span class="title function_ invoke__">load</span>(Ordering::SeqCst) &#123;</span><br><span class="line">        S.<span class="title function_ invoke__">fetch_add</span>(<span class="number">1</span>, Ordering::Relaxed);</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">let</span> <span class="variable">t2</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">    b_clone.<span class="title function_ invoke__">store</span>(<span class="literal">true</span>, Ordering::SeqCst);</span><br><span class="line">    <span class="keyword">if</span> !a_clone.<span class="title function_ invoke__">load</span>(Ordering::SeqCst) &#123;</span><br><span class="line">        S.<span class="title function_ invoke__">fetch_add</span>(<span class="number">1</span>, Ordering::Relaxed);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;);</span><br></pre></td></tr></table></figure><h2 id="fence"><a href="#fence" class="headerlink" title="fence"></a>fence</h2><p><code>Ordering</code> applies per atomic op. <code>fence</code> adds a <strong>memory barrier</strong> across multiple atomics (and surrounding accesses), blocking certain reorders — another way to stitch a critical section 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></pre></td><td class="code"><pre><span class="line">a.<span class="title function_ invoke__">store</span>(<span class="number">1</span>, Release);</span><br><span class="line"><span class="comment">// equivalent pattern:</span></span><br><span class="line"><span class="title function_ invoke__">fence</span>(Release);</span><br><span class="line">a.<span class="title function_ invoke__">store</span>(<span class="number">1</span>, Relaxed);</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></pre></td><td class="code"><pre><span class="line">a.<span class="title function_ invoke__">load</span>(Acquire);</span><br><span class="line"><span class="comment">// equivalent pattern:</span></span><br><span class="line">a.<span class="title function_ invoke__">load</span>(Relaxed);</span><br><span class="line"><span class="title function_ invoke__">fence</span>(Acquire);</span><br></pre></td></tr></table></figure><p>Fences help when several locations need a coordinated visibility story. You can mix Relaxed ops with a fence instead of tagging every operation AcqRel&#x2F;SeqCst.</p><p>Toy mutex built from CAS + fences:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::atomic::AtomicBool;</span><br><span class="line"><span class="keyword">use</span> std::sync::atomic::fence;</span><br><span class="line"><span class="keyword">use</span> std::sync::atomic::Ordering;</span><br><span class="line"></span><br><span class="line"><span class="keyword">pub</span> <span class="keyword">struct</span> <span class="title class_">Mutex</span> &#123;</span><br><span class="line">    flag: AtomicBool,</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_">Mutex</span> &#123;</span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">new</span>() <span class="punctuation">-&gt;</span> Mutex &#123;</span><br><span class="line">        Mutex &#123;</span><br><span class="line">            flag: AtomicBool::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>),</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">pub</span> <span class="keyword">fn</span> <span class="title function_">lock</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="comment">// Relaxed CAS + Acquire fence to sync with prior Release unlock</span></span><br><span class="line">        <span class="keyword">while</span> <span class="keyword">self</span></span><br><span class="line">            .flag</span><br><span class="line">            .<span class="title function_ invoke__">compare_exchange_weak</span>(<span class="literal">false</span>, <span class="literal">true</span>, Ordering::Relaxed, Ordering::Relaxed)</span><br><span class="line">            .<span class="title function_ invoke__">is_err</span>()</span><br><span class="line">        &#123;&#125;</span><br><span class="line">        <span class="title function_ invoke__">fence</span>(Ordering::Acquire);</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    <span class="keyword">pub</span> <span class="keyword">fn</span> <span class="title function_">unlock</span>(&amp;<span class="keyword">self</span>) &#123;</span><br><span class="line">        <span class="keyword">self</span>.flag.<span class="title function_ invoke__">store</span>(<span class="literal">false</span>, Ordering::Release);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Lazy-initialization"><a href="#Lazy-initialization" class="headerlink" title="Lazy initialization"></a>Lazy initialization</h2><p>Atomics often back <strong>lazy init</strong> of shared static-like data:</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::&#123;</span><br><span class="line">    sync::atomic::&#123;AtomicPtr, Ordering&#125;,</span><br><span class="line">    thread,</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_">Data</span> &#123;&#125;</span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">generate_data</span>() <span class="punctuation">-&gt;</span> Data &#123;</span><br><span class="line">    Data &#123;&#125;</span><br><span class="line">&#125;</span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">get_data</span>() <span class="punctuation">-&gt;</span> &amp;<span class="symbol">&#x27;static</span> Data &#123;</span><br><span class="line">    <span class="keyword">static</span> PTR: AtomicPtr&lt;Data&gt; = AtomicPtr::<span class="title function_ invoke__">new</span>(std::ptr::<span class="title function_ invoke__">null_mut</span>());</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">p</span> = PTR.<span class="title function_ invoke__">load</span>(Ordering::Acquire);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">if</span> p.<span class="title function_ invoke__">is_null</span>() &#123;</span><br><span class="line">        p = <span class="type">Box</span>::<span class="title function_ invoke__">into_raw</span>(<span class="type">Box</span>::<span class="title function_ invoke__">new</span>(<span class="title function_ invoke__">generate_data</span>()));</span><br><span class="line">        <span class="keyword">if</span> <span class="keyword">let</span> <span class="variable">Err</span>(e) = PTR.<span class="title function_ invoke__">compare_exchange</span>(</span><br><span class="line">            std::ptr::<span class="title function_ invoke__">null_mut</span>(),</span><br><span class="line">            p,</span><br><span class="line">            Ordering::Release,</span><br><span class="line">            Ordering::Acquire,</span><br><span class="line">        ) &#123;</span><br><span class="line">            <span class="comment">// Safety: p comes from Box::into_raw right above,</span></span><br><span class="line">            <span class="comment">// and wasn&#x27;t shared with any other thread.</span></span><br><span class="line">            <span class="title function_ invoke__">drop</span>(<span class="keyword">unsafe</span> &#123; <span class="type">Box</span>::<span class="title function_ invoke__">from_raw</span>(p) &#125;);</span><br><span class="line">            p = e;</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">// Safety: p is not null and points to a properly initialized value.</span></span><br><span class="line">    <span class="keyword">unsafe</span> &#123; &amp;*p &#125;</span><br><span class="line">&#125;</span><br><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> <span class="variable">t1</span> = thread::<span class="title function_ invoke__">spawn</span>(|| <span class="title function_ invoke__">get_data</span>());</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t2</span> = thread::<span class="title function_ invoke__">spawn</span>(|| <span class="title function_ invoke__">get_data</span>());</span><br><span class="line">    <span class="keyword">let</span> (ret1, ret2) = (t1.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>(), t2.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">    <span class="built_in">assert_eq!</span>(ret1 <span class="keyword">as</span> *<span class="keyword">const</span> _, ret2 <span class="keyword">as</span> *<span class="keyword">const</span> _);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>In real code you rarely hand-roll this — crates like <a href="https://docs.rs/once_cell/latest/once_cell/#lazy-initialized-global-data">once_cell</a> cover the pattern.</p><hr><p>Atomics are the low-level layer. <code>Ordering</code> ties atomic results to what other threads can observe and pushes back on compiler&#x2F;CPU reordering. You might never ship your own lock-free structure, but knowing this makes library code and the ordering names far easier to read.</p><p>Solid follow-ups:</p><ul><li><a href="https://marabos.nl/atomics/memory-ordering.html">Rust Atomics and Locks: memory ordering</a></li><li><a href="https://www.youtube.com/watch?v=rMGWeSjctlY">Crust of Rust: Atomics and Memory Ordering</a></li></ul>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sync-atomic.html</id>
    <link href="https://newbmiao.github.io/rust-sync-atomic.html"/>
    <published>2023-12-16T08:23:50.000Z</published>
    <summary>Mutex vs lock-free atomics, instruction reordering, Acquire/Release/SeqCst, fences, and lazy init with AtomicPtr.</summary>
    <title>Rust atomics — Atomic types and memory Ordering</title>
    <updated>2026-11-20T12:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="channel" scheme="https://newbmiao.github.io/tags/channel/"/>
    <content>
      <![CDATA[<p>Rust’s <code>sync</code> module exposes <strong>mpsc</strong> (multi-producer, single-consumer) channels—message passing instead of locking shared memory. That’s the style Rob Pike pushed:</p><blockquote><p>Don’t communicate by sharing memory; share memory by communicating. (R. Pike)</p></blockquote><p>Below: bounded <code>sync_channel</code> and the unbounded <code>channel</code>, plus how <code>Send</code>&#x2F;<code>Sync</code> show up on the handles.</p><span id="more"></span><h2 id="Rules"><a href="#Rules" class="headerlink" title="Rules"></a>Rules</h2><p>Most channel designs share the same contract:</p><ul><li>Producers <strong>send</strong>, consumers <strong>recv</strong>, usually FIFO via an internal queue.</li><li>Receivers block when empty until a message arrives or the channel closes.</li><li>A <strong>buffer size</strong> caps in-flight messages.</li><li>When the buffer is full, senders block until something is received.</li></ul><p>So production generally leads consumption, and ordering is first-in-first-out.</p><h2 id="sync-channel-—-buffer-size-0-handshake"><a href="#sync-channel-—-buffer-size-0-handshake" class="headerlink" title="sync_channel — buffer size 0 (handshake)"></a>sync_channel — buffer size 0 (handshake)</h2><p>A buffer of <strong>0</strong> means every <code>send</code> blocks until a matching <code>recv</code>—classic back-pressure, one in flight at a time.</p><p>That’s handy for enforcing order. Two zero-capacity channels can alternate <code>1</code> and <code>2</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::mpsc::sync_channel;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"></span><br><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> (sender, receiver) = <span class="title function_ invoke__">sync_channel</span>(<span class="number">0</span>);</span><br><span class="line">    <span class="keyword">let</span> (sender2, receiver2) = <span class="title function_ invoke__">sync_channel</span>(<span class="number">0</span>);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">cnt</span> = <span class="number">3</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = thread::<span class="title function_ invoke__">spawn</span>(&#123;</span><br><span class="line">        <span class="keyword">move</span> || &#123;</span><br><span class="line">            <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">                <span class="built_in">print!</span>(<span class="string">&quot;1 &quot;</span>);</span><br><span class="line">                <span class="comment">// After printing, tell t2&#x27;s receiver to go</span></span><br><span class="line">                sender.<span class="title function_ invoke__">send</span>(<span class="number">2</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">                <span class="comment">// Block until t2 finishes its print</span></span><br><span class="line">                receiver2.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            &#125;</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">let</span> <span class="variable">t2</span> = thread::<span class="title function_ invoke__">spawn</span>(&#123;</span><br><span class="line">        <span class="keyword">move</span> || &#123;</span><br><span class="line">            <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">                <span class="comment">// Block until t1 has sent after its print</span></span><br><span class="line">                receiver.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">                <span class="built_in">print!</span>(<span class="string">&quot;2 &quot;</span>);</span><br><span class="line">                <span class="comment">// Tell t1 it can print again</span></span><br><span class="line">                sender2.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    t1.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    t2.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Criss-cross <code>send</code>&#x2F;<code>recv</code> on two channels serializes the prints much like alternating lock handoffs.</p><h2 id="sync-channel-—-larger-buffer-mpsc"><a href="#sync-channel-—-larger-buffer-mpsc" class="headerlink" title="sync_channel — larger buffer (mpsc)"></a>sync_channel — larger buffer (mpsc)</h2><p>With a positive buffer, you get real <strong>mpsc</strong>: multiple senders, one receiver, up to <em>N</em> messages queued (often a preallocated slot array).</p><p>When the buffer fills, senders wait. Receivers still block on an empty queue.</p><p>Remember <strong>dropping</strong> the last sender closes the channel so blocked <code>recv</code> can return <code>Err</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::mpsc::sync_channel;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"></span><br><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> (sender, receiver) = <span class="title function_ invoke__">sync_channel</span>(<span class="number">3</span>);</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">sender2</span> = sender.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">sender3</span> = sender.<span class="title function_ invoke__">clone</span>();</span><br><span class="line">    thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || sender.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">    thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || sender2.<span class="title function_ invoke__">clone</span>().<span class="title function_ invoke__">send</span>(<span class="number">2</span>).<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line"></span><br><span class="line">    <span class="title function_ invoke__">drop</span>(sender3); <span class="comment">// Ensures the third recv can complete</span></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, receiver.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, receiver.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>());</span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, receiver.<span class="title function_ invoke__">recv</span>());</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="channel-unbounded"><a href="#channel-unbounded" class="headerlink" title="channel (unbounded)"></a>channel (unbounded)</h2><p>Once <code>sync_channel</code> clicks, <strong><code>channel</code></strong> is the same idea with an effectively unbounded buffer (linked list that grows). Sends don’t block for capacity; only <code>recv</code> blocks when empty.</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">use</span> std::sync::mpsc::&#123;channel, sync_channel&#125;;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"></span><br><span class="line"><span class="keyword">fn</span> <span class="title function_">main</span>() &#123;</span><br><span class="line">    <span class="comment">// let (sender, receiver) = sync_channel(1); // buffer 1 — may not print &quot;send no block&quot;</span></span><br><span class="line">    <span class="keyword">let</span> (sender, receiver) = <span class="title function_ invoke__">channel</span>(); <span class="comment">// unbounded — send returns immediately</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">        sender.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">        sender.<span class="title function_ invoke__">send</span>(<span class="number">2</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">        sender.<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 class="built_in">println!</span>(<span class="string">&quot;send no block&quot;</span>);</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, receiver.<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><p>For non-blocking checks, use <code>try_recv</code>:</p><ul><li><code>TryRecvError::Empty</code> — no message yet, channel still connected.</li><li><code>TryRecvError::Disconnected</code> — all senders gone; no more messages ever.</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::mpsc::&#123;channel, Receiver, RecvError, TryRecvError&#125;;</span><br><span class="line"></span><br><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> (sender, receiver) = <span class="title function_ invoke__">channel</span>();</span><br><span class="line">    <span class="keyword">fn</span> <span class="title function_">try_recv_with_log</span>(receiver: &amp;Receiver&lt;<span class="type">i32</span>&gt;) &#123;</span><br><span class="line">        <span class="keyword">match</span> receiver.<span class="title function_ invoke__">try_recv</span>() &#123;</span><br><span class="line">            <span class="title function_ invoke__">Ok</span>(v) =&gt; <span class="built_in">println!</span>(<span class="string">&quot;&#123;:?&#125;&quot;</span>, v),</span><br><span class="line">            <span class="title function_ invoke__">Err</span>(TryRecvError::Empty) =&gt; <span class="built_in">println!</span>(<span class="string">&quot;error: Empty&quot;</span>),</span><br><span class="line">            <span class="title function_ invoke__">Err</span>(TryRecvError::Disconnected) =&gt; <span class="built_in">println!</span>(<span class="string">&quot;error: Disconnected&quot;</span>),</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="comment">// error: Empty</span></span><br><span class="line">    <span class="title function_ invoke__">try_recv_with_log</span>(&amp;receiver);</span><br><span class="line">    sender.<span class="title function_ invoke__">send</span>(<span class="number">1</span>).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    receiver.<span class="title function_ invoke__">recv</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    <span class="title function_ invoke__">drop</span>(sender);</span><br><span class="line">    <span class="comment">// error: Disconnected</span></span><br><span class="line">    <span class="title function_ invoke__">try_recv_with_log</span>(&amp;receiver);</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><h2 id="Concurrency-safety"><a href="#Concurrency-safety" class="headerlink" title="Concurrency safety"></a>Concurrency safety</h2><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">unsafe</span> <span class="keyword">impl</span>&lt;T: <span class="built_in">Send</span>&gt; <span class="built_in">Send</span> <span class="keyword">for</span> <span class="title class_">Sender</span>&lt;T&gt; &#123;&#125;</span><br><span class="line"><span class="keyword">unsafe</span> <span class="keyword">impl</span>&lt;T: <span class="built_in">Send</span>&gt; <span class="built_in">Sync</span> <span class="keyword">for</span> <span class="title class_">Sender</span>&lt;T&gt; &#123;&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">unsafe</span> <span class="keyword">impl</span>&lt;T: <span class="built_in">Send</span>&gt; <span class="built_in">Send</span> <span class="keyword">for</span> <span class="title class_">Receiver</span>&lt;T&gt; &#123;&#125;</span><br><span class="line"><span class="keyword">impl</span>&lt;T&gt; !<span class="built_in">Sync</span> <span class="keyword">for</span> <span class="title class_">Receiver</span>&lt;T&gt; &#123;&#125;</span><br></pre></td></tr></table></figure><p>How does Rust keep channels sound?</p><p><code>Sender&lt;T&gt;</code> is both <code>Send</code> and <code>Sync</code>: the queue can move across threads and be shared, so multiple threads can <code>send</code> concurrently. <code>T: Send</code> so owned messages cross thread boundaries safely.</p><p><code>Receiver&lt;T&gt;</code> is <code>Send</code> but <strong>not</strong> <code>Sync</code>—only one thread should own the receiver and drain the queue.</p><p>Again, marker traits encode the rules at compile time so you get fearless concurrency without ad-hoc comments.</p><p>More Rust concurrency notes: <a href="/categories/rust/">Rust category</a>.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sync-channel.html</id>
    <link href="https://newbmiao.github.io/rust-sync-channel.html"/>
    <published>2023-12-08T12:55:42.000Z</published>
    <summary>std::sync::mpsc send/recv rules, buffer size zero for back-pressure, and Send/Sync on Sender and Receiver.</summary>
    <title>Rust mpsc — sync_channel buffers and unbounded channel</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="semaphore" scheme="https://newbmiao.github.io/tags/semaphore/"/>
    <content>
      <![CDATA[<p>A <strong>semaphore</strong> caps how many concurrent actors can use a resource.</p><p>Unlike a <strong>mutex</strong> (exclusive access), a semaphore hands out a fixed number of permits. Think of a bucket of tokens: each visitor <strong>acquires</strong> a token; when the bucket is empty, new acquires block until someone <strong>adds</strong> permits or <strong>releases</strong> them.</p><p>Below we use the classic two-thread print puzzle to see how that feels in code.</p><span id="more"></span><blockquote><p>There’s no stable <code>std::sync::Semaphore</code> (<code>std::sync::Semaphore</code> was deprecated in 1.7.0). Examples use <strong>tokio</strong>‘s semaphore.</p></blockquote><p>Add tokio to your crate:</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"># Add tokio to cargo.toml by hand</span><br><span class="line"># Or with cargo-add: cargo add tokio --features sync,macros,rt-multi-thread</span><br><span class="line">[dependencies]</span><br><span class="line">tokio = &#123; version = <span class="string">&quot;1.34.0&quot;</span>, features = [<span class="string">&quot;sync&quot;</span>, <span class="string">&quot;macros&quot;</span>, <span class="string">&quot;rt-multi-thread&quot;</span>] &#125;</span><br><span class="line"></span><br></pre></td></tr></table></figure><h3 id="Naive-version-one-permit"><a href="#Naive-version-one-permit" class="headerlink" title="Naive version: one permit"></a>Naive version: one permit</h3><p>Start with a semaphore that allows one holder. Two tasks acquire, print, and drop the permit:</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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::Arc;</span><br><span class="line"><span class="keyword">use</span> tokio::sync::Semaphore;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="keyword">let</span> <span class="variable">semaphore</span> = Arc::<span class="title function_ invoke__">new</span>(Semaphore::<span class="title function_ invoke__">new</span>(<span class="number">1</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">cnt</span> = <span class="number">3</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore2</span> = semaphore.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">permit</span> = semaphore.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="built_in">print!</span>(<span class="string">&quot;1 &quot;</span>);</span><br><span class="line">            <span class="comment">// Optional — permit returns on drop</span></span><br><span class="line">            <span class="title function_ invoke__">drop</span>(permit); </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">let</span> <span class="variable">t2</span> = tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="comment">// Or use `_` to drop the permit immediately</span></span><br><span class="line">            <span class="keyword">let</span> <span class="variable">_</span> = semaphore2.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>(); </span><br><span class="line">            <span class="built_in">print!</span>(<span class="string">&quot;2 &quot;</span>);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    tokio::try_join!(t1, t2).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Looks fine, but output isn’t guaranteed to be <code>1 2 1 2 1 2</code>.</p><p>We only enforced “one permit at a time,” not <strong>who goes first</strong>. That’s mutual exclusion, not alternation.</p><h3 id="Strict-alternation-two-semaphores"><a href="#Strict-alternation-two-semaphores" class="headerlink" title="Strict alternation: two semaphores"></a>Strict alternation: two semaphores</h3><p>Drive ordering by <strong>moving</strong> permits between two semaphores—<code>add_permits</code> on one side, <code>forget</code> on the other so the permit doesn’t bounce back to the same bucket.</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::Arc;</span><br><span class="line"><span class="keyword">use</span> tokio::sync::Semaphore;</span><br><span class="line"></span><br><span class="line"><span class="meta">#[tokio::main]</span></span><br><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 class="comment">// Bucket 1 starts with one permit so thread 1 can print first</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore</span> = Arc::<span class="title function_ invoke__">new</span>(Semaphore::<span class="title function_ invoke__">new</span>(<span class="number">1</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">cnt</span> = <span class="number">3</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore2</span> = semaphore.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="comment">// Bucket 2 starts empty until thread 1 adds a permit</span></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore_wait</span> = Arc::<span class="title function_ invoke__">new</span>(Semaphore::<span class="title function_ invoke__">new</span>(<span class="number">0</span>));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">semaphore_wait2</span> = semaphore_wait.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">permit</span> = semaphore.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="built_in">print!</span>(<span class="string">&quot;1 &quot;</span>);</span><br><span class="line">            <span class="comment">// Consume permit — don&#x27;t return it to bucket 1</span></span><br><span class="line">            permit.<span class="title function_ invoke__">forget</span>();</span><br><span class="line">            <span class="comment">// Unblock bucket 2 so thread 2 can print</span></span><br><span class="line">            semaphore_wait2.<span class="title function_ invoke__">add_permits</span>(<span class="number">1</span>);</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">let</span> <span class="variable">t2</span> = tokio::<span class="title function_ invoke__">spawn</span>(<span class="keyword">async</span> <span class="keyword">move</span> &#123;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="keyword">let</span> <span class="variable">permit</span> = semaphore_wait.<span class="title function_ invoke__">acquire</span>().<span class="keyword">await</span>.<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="built_in">print!</span>(<span class="string">&quot;2 &quot;</span>);</span><br><span class="line">            <span class="comment">// Consume permit — don&#x27;t return it to bucket 2</span></span><br><span class="line">            permit.<span class="title function_ invoke__">forget</span>();</span><br><span class="line">            <span class="comment">// Unblock bucket 1 for the next 1</span></span><br><span class="line">            semaphore2.<span class="title function_ invoke__">add_permits</span>(<span class="number">1</span>);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line"></span><br><span class="line">    tokio::try_join!(t1, t2).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>Two dynamic permit buckets handshake the turns.</p><p>Compare with the <a href="/rust-sync-condvar-2.html">condvar version</a> to see how each primitive shapes the solution.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sync-semaphore.html</id>
    <link href="https://newbmiao.github.io/rust-sync-semaphore.html"/>
    <published>2023-11-24T10:57:56.000Z</published>
    <summary>Resource limits with permits — naive single-permit semaphores vs a two-bucket handshake for strict ordering.</summary>
    <title>Tokio Semaphore — alternating 1 and 2 with two threads</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="rust" scheme="https://newbmiao.github.io/categories/rust/"/>
    <category term="condvar" scheme="https://newbmiao.github.io/tags/condvar/"/>
    <content>
      <![CDATA[<p>Interview favorite: two concurrent threads must print <code>1</code> and <code>2</code> in strict alternation.</p><p>Plenty of solutions exist. Here we try condvar, building on the <a href="/rust-sync-condvar.html">Condvar</a> post.</p><span id="more"></span><p>Idea: one shared flag in a mutex, with the condvar gating who may proceed.</p><ul><li>Thread 1: print <code>1</code> only when the flag is false, set it true, <code>notify_one</code> so thread 2 can run; otherwise spin in a <code>while</code> loop (blocking path via wait logic in the loop).</li><li>Thread 2: while the flag is false, <code>wait</code>; when true, reset false and print <code>2</code>.</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><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></pre></td><td class="code"><pre><span class="line"><span class="keyword">use</span> std::sync::&#123;Arc, Condvar, Mutex&#125;;</span><br><span class="line"><span class="keyword">use</span> std::thread;</span><br><span class="line"></span><br><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> <span class="variable">pair</span> = Arc::<span class="title function_ invoke__">new</span>((Mutex::<span class="title function_ invoke__">new</span>(<span class="literal">false</span>), Condvar::<span class="title function_ invoke__">new</span>()));</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">cnt</span> = <span class="number">3</span>;</span><br><span class="line">    <span class="keyword">let</span> <span class="variable">pair2</span> = pair.<span class="title function_ invoke__">clone</span>();</span><br><span class="line"></span><br><span class="line">    <span class="keyword">let</span> <span class="variable">t1</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">        <span class="keyword">let</span> &amp;(<span class="keyword">ref</span> lock, <span class="keyword">ref</span> cvar) = &amp;*pair2;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="keyword">while</span> <span class="keyword">let</span> <span class="variable">Ok</span>(<span class="keyword">mut</span> v) = lock.<span class="title function_ invoke__">lock</span>() &#123;</span><br><span class="line">                <span class="comment">// When flag is false, print 1, set true, wake the other thread</span></span><br><span class="line">                <span class="keyword">if</span> !*v &#123;</span><br><span class="line">                    <span class="built_in">print!</span>(<span class="string">&quot;1 &quot;</span>);</span><br><span class="line">                    *v = <span class="literal">true</span>;</span><br><span class="line">                    cvar.<span class="title function_ invoke__">notify_one</span>();</span><br><span class="line">                    <span class="keyword">break</span>;</span><br><span class="line">                &#125; <span class="keyword">else</span> &#123;</span><br><span class="line">                    <span class="comment">// Drop the guard so we don&#x27;t hold the mutex until scope end</span></span><br><span class="line">                    <span class="comment">// If there&#x27;s nothing else to do, scope drop is fine too</span></span><br><span class="line">                    <span class="title function_ invoke__">drop</span>(v);</span><br><span class="line">                    <span class="comment">// [2]</span></span><br><span class="line">                    <span class="comment">// std::thread::sleep(std::time::Duration::from_millis(1));</span></span><br><span class="line">                    <span class="comment">// [1]</span></span><br><span class="line">                    <span class="comment">// print!(&quot; waitting... &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><span class="line">    <span class="keyword">let</span> <span class="variable">t2</span> = thread::<span class="title function_ invoke__">spawn</span>(<span class="keyword">move</span> || &#123;</span><br><span class="line">        <span class="keyword">for</span> <span class="variable">_</span> <span class="keyword">in</span> <span class="number">0</span>..cnt &#123;</span><br><span class="line">            <span class="keyword">let</span> &amp;(<span class="keyword">ref</span> lock, <span class="keyword">ref</span> cvar) = &amp;*pair;</span><br><span class="line">            <span class="keyword">let</span> <span class="keyword">mut </span><span class="variable">v</span> = lock.<span class="title function_ invoke__">lock</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            <span class="comment">// While false, wait until notified and flag becomes true</span></span><br><span class="line">            <span class="keyword">while</span> !*v &#123;</span><br><span class="line">                v = cvar.<span class="title function_ invoke__">wait</span>(v).<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">            &#125;</span><br><span class="line">            <span class="comment">// Reset and print 2</span></span><br><span class="line">            *v = <span class="literal">false</span>;</span><br><span class="line"></span><br><span class="line">            <span class="built_in">print!</span>(<span class="string">&quot;2 &quot;</span>);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;);</span><br><span class="line">    t1.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">    t2.<span class="title function_ invoke__">join</span>().<span class="title function_ invoke__">unwrap</span>();</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>You should see <code>1 2 1 2 1 2 </code>.</p><p>Thread 1’s busy loop still burns CPU. Uncomment the <code>[1]</code> debug print and you’ll see lots of <code>waitting...</code> lines.</p><p>A short <code>sleep</code> at <code>[2]</code> yields the core and cuts down lock thrashing.</p><p>The same puzzle with semaphores is fun too—that’s in <a href="/rust-sync-semaphore.html">Tokio Semaphore — alternating print</a>.</p>]]>
    </content>
    <id>https://newbmiao.github.io/rust-sync-condvar-2.html</id>
    <link href="https://newbmiao.github.io/rust-sync-condvar-2.html"/>
    <published>2023-11-23T15:30:59.000Z</published>
    <summary>Classic interview puzzle — two threads printing 1 and 2 in turn using Mutex and Condvar.</summary>
    <title>Rust Condvar — alternating 1 and 2 with two threads</title>
    <updated>2026-11-19T16:00:00.000Z</updated>
  </entry>
  <entry>
    <author>
      <name>newbmiao</name>
      <email>newbvirgil@gmail.com</email>
    </author>
    <category term="web" scheme="https://newbmiao.github.io/categories/web/"/>
    <category term="blog" scheme="https://newbmiao.github.io/tags/blog/"/>
    <content>
      <![CDATA[<!-- **文章目录** --><!-- [TOC] --><p><strong>声明：博客地址已迁移到 <a href="https://newbmiao.github.io/">https://newbmiao.github.io</a>, 原域名<del>blog.newbmiao.com</del>已不再使用。</strong></p><span id="more"></span><!-- ---文章首发公众号：newbmiao![欢迎关注，获取及时更新内容](images/qrcode/newbmiao.webp) -->]]>
    </content>
    <id>https://newbmiao.github.io/blog-migrate-hostname.html</id>
    <link href="https://newbmiao.github.io/blog-migrate-hostname.html"/>
    <published>2023-11-20T04:49:22.000Z</published>
    <summary>newbmiao.github.io</summary>
    <title>博客地址已迁移到newbmiao.github.io</title>
    <updated>2026-11-20T14:12:24.216Z</updated>
  </entry>
</feed>
