David Álvarez Rosa

Tuning a Server for Benchmarking

Thu, 25 Jun 2026 18:02:00 +0100

Optimizing code starts with measuring it, and a measurement is only useful if it is repeatable: a 2% improvement is invisible under 5% of noise. Yet on an untuned machine the same binary can easily run several percent faster or slower between runs. In this post we take a tiny benchmark and tune the machine step by step, re-measuring after every change, until runs become deterministic.¹

A noisy baseline §

Our running example sums an array of doubles, in short bursts. Real services rarely hammer the CPU continuously: they handle a request, sit idle, and wake up for the next one. Each timed iteration here runs a burst of 256 sums after a 2 ms idle gap, with the gap excluded from the measurement²

static auto BM_Sum(benchmark::State& state) -> void {
 alignas(64) static std::array<double, 4096> data;
 std::iota(data.begin(), data.end(), 0.0);
 for (auto _ : state) {
 state.PauseTiming(); // Idle between bursts, like a real service
 std::this_thread::sleep_for(std::chrono::milliseconds(2));
 state.ResumeTiming();
 for (auto i = 0; i < 256; ++i) {
 auto sum = std::accumulate(data.cbegin(), data.cend(), 0.0);
 benchmark::DoNotOptimize(sum);
 }
 }
}

BENCHMARK(BM_Sum);

Compile it in release with all optimizations, -O3, and -march=native -mtune=native -flto -ffast-math. Then run ten repetitions and aggregate them

$ ./benchmark --benchmark_repetitions=10 --benchmark_min_time=200x
BM_Sum_mean 99575 ns
BM_Sum_stddev 2704 ns
BM_Sum_cv 2.72 %

The interesting line is cv, the coefficient of variation: standard deviation divided by mean. Almost 3% of run-to-run noise—any optimization smaller than that is invisible. Let’s bring it down.

Know your hardware §

Before turning any knob, look at what you are tuning. lstopo draws the whole machine in one picture: caches, cores, SMT pairs, and the PCIe devices hanging off them. Start with my laptop

Figure 1: My laptop (Intel Core Ultra 5 135U). Three kinds of cores: two P-cores with two hardware threads each (dotted), eight E-cores in clusters of four sharing an L2, and two low-power E-cores (bottom left) sitting outside the L3 entirely.

Here the choice of core changes what you measure: land on CPU 4 and you get an E-core at lower clocks; on CPU 12 you lose the L3 too. Now compare that against my homelab server

Figure 2: My homelab server (AMD Ryzen 7 PRO 8700GE). Eight identical cores with identical caches; the NVMe drives and the NIC hang off PCIe on the right.

On the server every core is as good as any other: homogeneous machines make better benchmarking boxes. The PCIe side matters once a benchmark touches I/O: it shows which NVMe or NIC you are exercising and, on multi-socket machines, which NUMA node it hangs off.

Pin to a core §

The scheduler is free to migrate the benchmark between cores, and every migration throws away warm caches. On hybrid CPUs it’s worse: performance and efficiency cores run the same code at very different speeds, so results turn bimodal depending on where the process lands. Pin the benchmark to a single core (on hybrid parts, a P-core)

$ taskset -c 2 ./benchmark ...

The mean falls to 55.3 µs and the CV better than halves, to 1.06%. The win is bigger than migration costs alone would suggest: every burst now wakes the same core, so that core’s clock never has time to sag between bursts.³

Lock the CPU frequency §

By default Linux scales the CPU frequency with load, so the benchmark starts on a cold, slow clock and finishes on a hot, fast one. Switch the frequency governor to performance to keep clocks locked high

$ sudo cpupower frequency-set --governor performance

and verify it took effect

$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
performance

Re-measuring gives a mean of 54.9 µs and a CV of 0.79%. The increment looks modest only because pinning already kept our core’s clock warm: on its own, the performance governor takes the unpinned baseline from 99.6 µs straight to 54.5 µs. Either way, no burst ever wakes up on a cold clock again.

Disable hyperthreading §

CPU still shares its execution units and L1/L2 caches with its SMT sibling: anything the scheduler places there perturbs our measurement. Disable SMT entirely

$ echo off | sudo tee /sys/devices/system/cpu/smt/control

The CV drops to 0.26%, three times better: the core now has its execution units and caches all to itself.

Disable turbo boost §

Even with the performance governor, turbo frequencies vary with temperature and power budget: the same run on a warm machine clocks lower than on a cool one. Disable turbo for stable clocks

$ echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost

On this machine nothing changes, since our short bursts never gave the silicon time to boost anyway. On a machine where turbo does engage, expect the mean to climb instead: you are giving up peak performance. That trade is fine, since when optimizing we care about relative numbers, and those are now comparable across runs.⁴

Summary §

Here is the whole journey in one table, each row adding one change on top of all the previous ones. We went from almost 3% of noise down to 0.26%, and got 1.8x faster along the way; differences of half a percent are now real, measurable signal.⁵

Step	Mean	StdDev	CV
Untuned	99.6 µs	2.70 µs	2.72%
+ pinned to one core	55.3 µs	0.59 µs	1.06%
+ performance governor	54.9 µs	0.43 µs	0.79%
+ hyperthreading off	55.3 µs	0.15 µs	0.26%
+ turbo disabled	55.5 µs	0.14 µs	0.26%

On busier machines there is a longer tail of knobs worth trying: disabling address space layout randomization, the NMI watchdog, or transparent huge pages. The bench-remote.sh script applies all. None of it survives a reboot, which is exactly what you want: tune, measure, and reboot back to a normal machine.

Long live reproducible benchmarks!

Note that tuning for benchmarking is not the same as tuning for performance: a benchmark wants the machine repeatable, even at the cost of some peak speed. A production box, however, wants every last bit of speed. ↩︎
PauseTiming / ResumeTiming keep the sleep out of the measured time, and DoNotOptimize keeps the result alive past the optimizer; without it the compiler deletes the entire loop. ↩︎
Pinning puts the benchmark onto the core but does not keep other tasks off it. On a busy box, go further and reserve the core for the benchmark alone, either on the kernel command line (isolcpus=2 nohz_full=2 rcu_nocbs=2) or at runtime with a cpuset cgroup. ↩︎
Low-latency production tuning makes the opposite call and keeps turbo on: there, every nanosecond counts. The most latency-sensitive trading shops go further and run overclocked servers, locked at a fixed all-core frequency above stock—speed and stable clocks, bought with better cooling. ↩︎
Feel free to reproduce on your machine using the benchmark from my CppPlayground repository. ↩︎

Self-Hosting on the Dark Web

Mon, 01 Jun 2026 10:55:00 +0100

This site is now reachable over Tor as a hidden service, at a .onion address that resolves only inside the Tor network.¹ Tor relays and encrypts your traffic as it passes through thousands of volunteer-run servers, so that no single party can link who you are to what you are doing; a hidden service extends that anonymity to the server itself.

It’s built by the nonprofit Tor Project, which advances human rights and freedoms through free software and open networks, so that anyone can use the internet free from tracking, surveillance, and censorship. The network only works because people use it, so consider supporting them or running a relay—your contribution helps millions stay safe and private online every day.

The hidden service §

Install Tor and point a hidden service at a local port. Edit /etc/tor/torrc

HiddenServiceDir /var/lib/tor/blog/
HiddenServicePort 80 127.0.0.1:8080

The directory must be a dedicated, Tor-owned path—not your web root.² Restart Tor and read the address it generates

$ sudo systemctl restart tor@default
$ sudo cat /var/lib/tor/blog/hostname
dhevt6e4rtgbtr3jh53xrpwmgtilkah6nyjujocsspssrsexc7omxhid.onion

Serving the site §

Tor forwards the onion’s port 80 to 127.0.0.1:8080, so the web server just needs to listen there. Add an nginx server block for it—no TLS, no HTTP/2, no QUIC, since Tor speaks plain TCP and provides its own encryption.

server {
 listen 127.0.0.1:8080;
 server_name dhevt6e4rtgbtr3jh53xrpwmgtilkah6nyjujocsspssrsexc7omxhid.onion;

 root /srv/tor.david.alvarezrosa.com;
 index index.html;
 error_page 404 /404/index.html;

 location / {
 try_files $uri $uri/ =404;
 }
}

Reload nginx and the site is live on Tor.

Building for the onion §

A static site bakes its base URL into absolute links, so a clearnet build would point visitors back to the clearnet domain even when served over Tor. The fix is to build a second copy with the onion as its base URL

$ hugo --minify --baseURL="http://dhevt6e4rtgbtr3jh53xrpwmgtilkah6nyjujocsspssrsexc7omxhid.onion/"

The deploy pipeline does this automatically: every push builds the site once per target—clearnet and Tor—and rsyncs each to its own web root, so the two stay in sync without any manual work.³

That’s it. Read this site over Tor at dhevt6e4rtgbtr3jh53xrpwmgtilkah6nyjujocsspssrsexc7omxhid.onion.

Open it in the Tor Browser. There is no certificate authority, no DNS, and no exposed IP—the address is derived directly from a public key, and the connection is end-to-end encrypted by Tor itself. ↩︎
Tor stores the service’s private key and hostname file here and insists on owning it (chmod 700, user debian-tor). Point it at your site files and Tor refuses to start. ↩︎
See First Steps on a New Server for the underlying machine; the full configuration lives in my homelab repository, and the site’s own repository holds the GitHub Actions workflow that builds and deploys the Tor copy. ↩︎

First Steps on a New Server

Sun, 17 May 2026 17:26:00 +0100

Over the last decade I’ve been playing with dozens of servers from multiple providers. These are the steps I’ve been perfecting to get up to speed fast and feel right at home on a new machine. Wrote it down here mostly as a personal reference, but hopefully useful to someone else too.

Hardware, distro, and DNS §

Clean Linux install with one large root partition plus big swap.¹ While I run Arch on my laptop, Debian tends to be a better fit for servers because of its stability and long support window.

Point your domain² to your server’s IP at your DNS provider: an A record for IPv4 and an AAAA record for IPv6. Wait a few minutes, then verify both.

$ dig alvarezrosa.com A +short
213.32.19.229
$ dig alvarezrosa.com AAAA +short
2001:41d0:305:2100::febc

Hardware doesn’t matter: a VPS, a Raspberry Pi, or a dedicated box will do.

$ ssh root@alvarezrosa.com
$ passwd
$ apt update && apt full-upgrade

Create a non-root user with sudo privileges.

$ useradd --create-home --groups sudo david
$ passwd david

Log out, then reconnect as the new user.

$ ssh david@alvarezrosa.com

From here on, stay on this account and use sudo when you need it.

Dotfiles §

I like to set up dotfiles early. Debugging on an unfamiliar shell is its own kind of miserable.³

$ git init
$ git remote add origin https://github.com/david-alvarez-rosa/dotfiles.git
$ git fetch origin
$ git checkout -t origin/main
$ git submodule update --init --recursive
$ git config status.showUntrackedFiles no

Switch to zsh and install starship.⁴

$ sudo apt install zsh starship
$ chsh --shell $(which zsh)

Log out and back in to confirm the shell loads correctly.

SSH keys §

Copy your public key to the server from your local machine.⁵

$ ssh-copy-id david@alvarezrosa.com

Confirm you can get in without a password.

$ ssh david@alvarezrosa.com

If you need root access over SSH, install the key there too.

$ sudo install -d -m 700 /root/.ssh
$ sudo install -m 600 ~/.ssh/authorized_keys /root/.ssh/authorized_keys

Once that’s working, disable password auth at least for root.⁶

Timezone, locale, and hostname §

Set the timezone and verify with date.

$ timedatectl list-timezones
$ sudo timedatectl set-timezone Europe/Madrid
$ date

Then enable en_US.UTF-8 locale and make it the default.

$ sudo vim /etc/locale.gen # Uncomment en_US.UTF-8
$ sudo locale-gen
$ sudo update-locale LANG=en_US.UTF-8

Set a sensible hostname and make sure /etc/hosts matches.

$ sudo hostnamectl set-hostname homelab
$ cat /etc/hosts
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
127.0.1.1 homelab

Firewall §

Deny all inbound traffic and allow only the ports you need.⁷

$ sudo apt install ufw
$ sudo ufw default deny incoming
$ sudo ufw allow 22/tcp
$ sudo ufw enable

Add more rules only as services are exposed.

Automatic security updates §

Security patches shouldn’t depend on remembering to log in every few days.⁸

$ sudo apt install unattended-upgrades apt-listchanges
$ sudo dpkg-reconfigure --priority=low unattended-upgrades

After that, security updates mostly take care of themselves.

Intrusion prevention §

fail2ban watches authentication logs and temporarily blocks IPs that look like they’re brute-forcing your services.

$ sudo apt install fail2ban
$ sudo systemctl enable --now fail2ban

Web server §

Install a web server to verify everything works end to end.⁹

$ sudo apt install nginx
$ sudo systemctl enable --now nginx
$ sudo ufw allow 80/tcp

Open your domain in a browser. You should see the default nginx page. Then enable HTTPS with Let’s Encrypt.¹⁰

$ sudo ufw allow 443/tcp
$ sudo apt install certbot python3-certbot-nginx
$ sudo certbot

Follow the prompts; Certbot rewrites the nginx config and sets up renewal automatically. Confirm your domain loads over HTTPS.

That’s the baseline. From here, the machine is yours—go build on it.

Predicting future partitioning needs is easy for a desktop, but can be difficult for a server. One large root filesystem is easier to manage. ↩︎
This post uses my domain alvarezrosa.com as an example. ↩︎
These commands treat the home directory as a Git repository, which lets you track dotfiles without symlink gymnastics. GitHub access can be configured shortly after this. ↩︎
Oh My Zsh is a common shell add-on, but it isn’t required for the server itself. starship is a fast cross-shell prompt. ↩︎
If you don’t have a key on your local machine yet, generate one first with ssh-keygen. ↩︎
Debian’s default is already PermitRootLogin prohibit-password, which only allows key-based root logins. ↩︎
Make sure SSH is allowed before enabling the firewall, or you will lock yourself out of the machine. ↩︎
Logs for unattended updates live in /var/log/unattended-upgrades/. ↩︎
I’ve been using Apache for quite a few years, but nginx is more lightweight and handles concurrent connections more efficiently. ↩︎
Certbot obtains free TLS certificates, updates the nginx configuration for you, and sets up automatic renewal. ↩︎

Fundamental Theorem of Calculus

Wed, 22 Apr 2026 20:14:00 +0100

Although the notion of area is intuitive, its mathematical treatment requires a rigorous definition. This post introduces the Riemann integral, and proves the fundamental theorem of calculus—a beautiful result that connects integrals and derivatives.

Riemann integral §

Given a bounded¹ function $f\colon[a,b]\to\mathbb{R}$, we can approximate the area under its graph by rectangles. Choose a partition of its domain

\[ \mathcal{P}=\{x_0,x_1,\ldots,x_n\mid a=x_0<x_1<\cdots<x_n=b\}. \]

For each subinterval $[x_{k-1},x_k]$, define the width $\Delta x_k=x_k-x_{k-1}$, and let $m_k$ and $M_k$ denote the infimum and supremum of $f$ on that subinterval. The lower and upper sums are

\[ L(f,\mathcal{P})=\sum_{k=1}^{n}m_k\Delta x_k, \qquad U(f,\mathcal{P})=\sum_{k=1}^{n}M_k\Delta x_k. \]

We define $f$ to be Riemann integrable² on $[a,b]$ iff for every $\varepsilon>0$ there exists a partition $\mathcal{P}$ such that $U(f,\mathcal{P})-L(f,\mathcal{P})<\varepsilon$, in which case

\[ \int_a^b f =\sup_{\mathcal{P}}L(f,\mathcal{P}) =\inf_{\mathcal{P}}U(f,\mathcal{P}). \]

Calculus machinery §

The proof requires the mean value theorem, which in turn rests on Rolle’s theorem and Fermat’s proposition.

Fermat’s Proposition. Let $I\subset\mathbb{R}$ be open and $f\colon I\to\mathbb{R}$ differentiable at $a\in I$. If $f$ has a local extremum at $a$, then $f^{\prime}(a)=0$.

Proof. Assume $f$ has a local maximum³ at $a$. Then there exists $\delta>0$ such that $f(x)-f(a)\le 0$ for all $x\in(a-\delta,a+\delta)$. Therefore

\[ \frac{f(x)-f(a)}{x-a}\ge 0 \quad (x<a), \qquad \frac{f(x)-f(a)}{x-a}\le 0 \quad (x>a). \]

Taking limits, $f^{\prime}_-(a)\ge 0$ and $f^{\prime}_+(a)\le 0$. Since $f$ is differentiable at $a$, $f^{\prime}_-(a)=f^{\prime}_+(a)=f^{\prime}(a)$, hence $f^{\prime}(a)=0$. $\square$

Rolle’s Theorem. If $f\colon[a,b]\to\mathbb{R}$ is continuous on $[a,b]$, differentiable on $(a,b)$, and $f(a)=f(b)$, then there exists $\xi\in(a,b)$ such that $f^{\prime}(\xi)=0$.

Proof. By the extreme value theorem,⁴ $f$ attains its minimum $m$ and maximum $M$ on $[a,b]$. If $m=M$, then $f$ is constant and any $\xi\in(a,b)$ works. Otherwise, since $f(a)=f(b)$, at least one extremum is attained at some $\xi\in(a,b)$; by Fermat, $f^{\prime}(\xi)=0$. $\square$

Mean Value Theorem.⁵ If $f$ is continuous on $[a,b]$ and differentiable on $(a,b)$, then there exists $\xi\in(a,b)$ such that

\[ f^{\prime}(\xi)=\frac{f(b)-f(a)}{b-a}. \]

Proof. Define

\[ g(x)=f(a)+\frac{f(b)-f(a)}{b-a}(x-a), \qquad h(x)=f(x)-g(x). \]

Then $h$ is continuous on $[a,b]$, differentiable on $(a,b)$, and $h(a)=h(b)=0$. By Rolle’s theorem, there exists $\xi\in(a,b)$ with $h^{\prime}(\xi)=0$, which gives

\[ f^{\prime}(\xi)-\frac{f(b)-f(a)}{b-a}=0.\,\square \]

Fundamental theorem of calculus §

We now have everything needed to prove the main result.

Fundamental Theorem of Calculus.⁶ Let $f\colon[a,b]\to\mathbb{R}$ be Riemann integrable, and let $F\colon[a,b]\to\mathbb{R}$ be continuous on $[a,b]$, differentiable on $(a,b)$, and satisfy $F^{\prime}(x)=f(x)$ for all $x\in(a,b)$. Then

\[ \int_a^b f = F(b)-F(a). \]

Proof. Fix a partition $\mathcal{P}=\{x_0,\ldots,x_n\}$. For each $[x_{k-1},x_k]$, the mean value theorem applied to $F$ gives $z_k\in(x_{k-1},x_k)$ such that

\[ F(x_k)-F(x_{k-1})=f(z_k)\,\Delta x_k. \]

Since $m_k\le f(z_k)\le M_k$, we obtain

\[ L(f,\mathcal{P}) \le \sum_{k=1}^{n}\left(F(x_k)-F(x_{k-1})\right) = F(b)-F(a) \le U(f,\mathcal{P}). \]

Taking supremum and infimum over all partitions and using integrability, we get

\[ \int_a^b f=F(b)-F(a).\,\square \]

Thus computing an area reduces to evaluating an antiderivative at two points.⁷ This theorem is fundamental because it unifies differentiation and integration, the two central operations of calculus.

Note that continuity is not required here; boundedness alone ensures the subinterval infima and suprema are finite. ↩︎
Every continuous function on $[a,b]$ is Riemann integrable; so is every monotone function. The exact characterization is Lebesgue’s criterion: $f$ is Riemann integrable iff it is bounded and continuous almost everywhere. ↩︎
The local minimum case is identical, with all inequalities reversed. ↩︎
Topological result: $[a,b]$ is compact (Heine-Borel), the continuous image of a compact set is compact, and compact subsets of $\mathbb{R}$ are closed and bounded, so they contain their $\inf$ and $\sup$, which are finite. ↩︎
Geometrically: there is always a point where the tangent line is parallel to the secant through the endpoints. ↩︎
A broader formulation also includes the statement that $x\mapsto\int_a^x f(t)\,dt$ is an antiderivative of $f$ under suitable regularity assumptions. ↩︎
For example, $\int_0^1 x^2\,dx = F(1)-F(0) = 1/3$ with $F(x)=x^3/3$. No partitions needed. ↩︎

Optimizing a Lock-Free Ring Buffer

Tue, 24 Mar 2026 11:51:00 +0000

A single-producer single-consumer (SPSC) queue is a great example of how far constraints can take a design. In this post, you will learn how to implement a ring buffer from scratch: start with the simplest design, make it thread-safe, and then gradually remove overhead while preserving FIFO behavior and predictable latency. This pattern is widely used to share data between threads in the lowest-latency environments.

What is a ring buffer? §

¹You might have run into the term circular buffer, or perhaps cyclic queue. These are simply other names for a ring buffer: a queue where a producer generates data and inserts it into the buffer, and a consumer later pulls it back out, in first-in-first-out order.

What makes a ring buffer distinctive is how it stores data and the constraints it enforces. It has a fixed capacity; it neither expands nor shrinks. As a result, when the buffer fills up, the producer must either wait until space becomes available or overwrite entries that have not been read yet, depending on what the application expects.

The consumer’s job is straightforward: read items as they arrive. When the ring buffer is empty, the consumer has to block, spin, or move on to other work. Each successful read releases a slot the producer can reuse. In the ideal case, the producer stays just a bit ahead, and the system turns into a quiet game of “catch me if you can,” with minimal waiting on both sides.

Single-threaded ring buffer §

Let’s start with a single-threaded ring buffer, which is just an array² and two indices. We leave one slot permanently unused to distinguish “full” from “empty.” Push writes to head and advances it; pop reads from tail and advances it.

template <typename T, std::size_t N>
class RingBufferV1 {
 std::array<T, N> buffer_;
 std::size_t head_{0};
 std::size_t tail_{0};
};

We can now implement the push (or write) operation³

auto push(const T& value) noexcept -> bool {
 auto new_head = head_ + 1;
 if (new_head == buffer_.size()) [[unlikely]] { // Wrap-around
 new_head = 0;
 }
 if (new_head == tail_) [[unlikely]] { // Full
 return false;
 }
 buffer_[head_] = value;
 head_ = new_head;
 return true;
}

Next we implement the pop (or read) operation⁴

auto pop(T& value) noexcept -> bool {
 if (head_ == tail_) [[unlikely]] { // Empty
 return false;
 }
 value = buffer_[tail_];
 auto next_tail = tail_ + 1;
 if (next_tail == buffer_.size()) [[unlikely]] { // Wrap-around
 next_tail = 0;
 }
 tail_ = next_tail;
 return true;
}

Thread-safe ring buffer §

You probably already noticed that the previous version is not thread-safe. The easiest way to solve this is to add a mutex around push and pop.

template <typename T, std::size_t N>
class RingBufferV2 {
 mutable std::mutex mutex_;

 auto push(const T& value) noexcept -> bool {
 auto lock = std::lock_guard<std::mutex>{mutex_}; // Thread-safe
 // ...
 }

 auto pop(T& value) noexcept -> bool {
 auto lock = std::lock_guard<std::mutex>{mutex_}; // Thread-safe
 // ...
 }
};

It’s correct and often fast enough: around 12M ops/s⁵ on consoomer hardware. However, it pays for mutual exclusion even though the producer and consumer never write the same index. The ownership is asymmetric: the producer is the only writer of head, and the consumer is the only writer of tail. That asymmetry is the lever to remove locks.

Lock-free ring buffer §

We can remove the locks by using atomics instead⁶

template <typename T, std::size_t N>
class RingBufferV3 {
 std::array<T, N> buffer_;
 alignas(std::hardware_destructive_interference_size) std::atomic_size_t head_{0};
 alignas(std::hardware_destructive_interference_size) std::atomic_size_t tail_{0};
};

The push implementation becomes

auto push(const T& value) noexcept -> bool {
 const auto head = head_.load();
 auto next_head = head + 1;
 if (next_head == buffer_.size()) [[unlikely]] {
 next_head = 0;
 }
 if (next_head == tail_.load()) [[unlikely]] {
 return false;
 }
 buffer_[head] = value;
 head_.store(next_head);
 return true;
}

And the pop implementation

auto pop(T& value) noexcept -> bool {
 const auto tail = tail_.load();
 if (tail == head_.load()) [[unlikely]] {
 return false;
 }
 value = buffer_[tail];
 auto next_tail = tail + 1;
 if (next_tail == buffer_.size()) [[unlikely]] {
 next_tail = 0;
 }
 tail_.store(next_tail);
 return true;
}

Simply removing the locks yields 35M ops/s, more than double the throughput of the locked version! You have probably noticed that we are using the default std::memory_order_seq_cst memory order for loading / storing the atomics, which is the slowest. Let’s manually tune the memory order⁷

auto push(const T& value) noexcept -> bool {
 const auto head = head_.load(std::memory_order_relaxed);
 auto next_head = head + 1;
 if (next_head == buffer_.size()) [[unlikely]] {
 next_head = 0;
 }
 if (next_head == tail_.load(std::memory_order_acquire)) [[unlikely]] {
 return false;
 }
 buffer_[head] = value;
 head_.store(next_head, std::memory_order_release);
 return true;
}

auto pop(T& value) noexcept -> bool {
 const auto tail = tail_.load(std::memory_order_relaxed);
 if (tail == head_.load(std::memory_order_acquire)) [[unlikely]] {
 return false;
 }
 value = buffer_[tail];
 auto next_tail = tail + 1;
 if (next_tail == buffer_.size()) [[unlikely]] {
 next_tail = 0;
 }
 tail_.store(next_tail, std::memory_order_release);
 return true;
}

Rerunning the benchmark now gives an astonishing 108M ops/s—3x the previous version and 9x the original locked version. Worth the effort, right?

Further optimization §

We already have a fast ring buffer, but we can push it further. The main slowdown comes from the reader and writer constantly touching each other’s indexes. That makes the CPU bounce cache lines⁸ between cores, which is expensive.

To reduce this, the reader can keep a local cached copy⁹ of the write index, and the writer keeps a local cached copy of the read index. Then they don’t need to re-check the other side on every single operation: only once in a while.

template <typename T, std::size_t N>
class RingBufferV5 {
 std::array<T, N> buffer_;
 alignas(std::hardware_destructive_interference_size) std::atomic_size_t head_{0};
 alignas(std::hardware_destructive_interference_size) std::size_t head_cached_{0};
 alignas(std::hardware_destructive_interference_size) std::atomic_size_t tail_{0};
 alignas(std::hardware_destructive_interference_size) std::size_t tail_cached_{0};
};

The push operation is updated to first consult the cached tail tail_cached_ and if that fails retry after updating the cache

if (next_head == tail_cached_) [[unlikely]] {
 tail_cached_ = tail_.load(std::memory_order_acquire);
 if (next_head == tail_cached_) {
 return false;
 }
}

The pop operation is updated in a similar way to first consult the cached head

if (tail == head_cached_) [[unlikely]] {
 head_cached_ = head_.load(std::memory_order_acquire);
 if (tail == head_cached_) {
 return false;
 }
}

Throughput is now 305M ops/s—nearly 3x faster than the manually tuned lock-free version and 25x faster than the original locking approach.

Summary §

If you want to reproduce these results, run the included benchmark compiled with at least -O3 optimization level.¹⁰ The benchmark pins the producer and consumer threads to dedicated CPU cores to minimize scheduling noise.

Version	Throughput	Notes
1	N/A	Not thread-safe
2	12M ops/s	Mutex / lock
3	35M ops/s	Lock-free (atomics)
4	108M ops/s	Lock-free (atomics) + memory order
5	305M ops/s	Lock-free (atomics) + memory order + index cache

Long live lock-free and wait-free data structures!

Ring buffer with 32 slots. The producer has filled 15 of them, indicated by blue. The consumer is behind the producer, reading data from the slots, freeing them as it does so. A free slot is indicated by orange. ↩︎
By using std::array we are forcing clients to define the buffer size as constexpr. It’s also common to use instead a std::vector to remove that restriction. A further optimization is to constrain the capacity to a power of two, allowing wrap-around via bit masking head & (N - 1) instead of a branch. ↩︎
Note how one item is left unused to indicate that the queue is full. When head_ is one item ahead of tail_, the queue is full. ↩︎
Again note that head_ == tail_ indicates that the queue is empty. ↩︎
Compiled with clang compiler with highest -O3 optimization level, and -march=native -ffast-math. Consumer and producer threads are pinned to dedicated cores (Intel Core Ultra 5 135U). See benchmark. ↩︎
Note that we are manually aligning alignas the atomics to ensure they fall in different cache lines (commonly 64 bytes). This prevents false sharing, hence optimizes CPU cache usage. ↩︎
release ensures prior writes are visible to threads that acquire the same variable. Both sides use relaxed for their own index since no other thread writes to it. ↩︎
It’s useful to observe the number of cache misses with perf stat -e cache-misses; they are greatly reduced in this approach. ↩︎
This advanced optimization was inspired by Erik Rigtorp. For an earlier publication, see: P. P. C. Lee, T. Bu, and G. Chandranmenon, “A lock-free, cache-efficient multi-core synchronization mechanism for line-rate network traffic monitoring,” 2010 IEEE International Symposium on Parallel & Distributed Processing (IPDPS)—doi:10.1109/IPDPS.2010.5470368 (PDF). ↩︎
Alongside -O3, the benchmark was compiled with -march=native and -ffast-math, though these flags shouldn’t make a difference here. ↩︎

Deriving Type Erasure

Tue, 10 Mar 2026 09:46:00 +0000

Ever looked at std::any and wondered what’s going on behind the scenes? Beneath the intimidating interface is a classic technique called type erasure: concrete types hidden behind a small, uniform wrapper.

Starting from familiar tools like virtual functions and templates, we’ll build a minimal std::any. By the end, you’ll have a clear understanding of how type erasure works under the hood.

Polymorphism with interfaces §

The typical way to achieve polymorphism is to define an interface consisting of pure-virtual methods you want to be able to call. Then, for each implementation that you want to use polymorphically, you create a subclass that inherits from the base class and implement those methods.

As an example, let’s implement shape classes that have an area() method. We start with an interface¹ class

class Shape {
public:
 virtual ~Shape() = default;
 virtual auto area() const noexcept -> double = 0;
};

And add a couple of concrete implementations for Square and Circle

class Square : public Shape {
 int side_;
public:
 explicit Square(int side) noexcept : side_{side} {}
 auto area() const noexcept -> double override { return side_ * side_; }
};

class Circle : public Shape {
 int radius_;
public:
 explicit Circle(int radius) noexcept : radius_{radius} {}
 auto area() const noexcept -> double override {
 return std::numbers::pi * radius_ * radius_;
 }
};

Now, we can use these implementations generically, by coding against the interface

auto printArea(const Shape& shape) -> void {
 std::println("Area is {:.2f}", shape.area());
}

Simple enough, right?

Polymorphism with templates §

Inheritance is a good solution to problems that require polymorphism, but sometimes the concrete types you want to handle polymorphically cannot share a common base class.² In that case, if the types provide the same interface, you can use a template to get polymorphism instead

auto printArea(const auto& shape) -> void {
 std::println("Area is {:.2f}", shape.area());
}

You can use this method with Square, Circle, or any type that provides a zero-argument area() returning double. Templates work because the compiler generates a version of the function for each concrete type you use, and the call is valid as long as that generated code would compile³ for the given type.

Unfortunately, template-based polymorphism has two main downsides.

First, templates do not give you one shared runtime base type like Shape. Each instantiation is a distinct type, so there is no common type for a homogeneous container; you cannot store a mix of Square and Circle in one array and handle them uniformly the way you can with a pointer to base technique

auto shapes = std::vector< ??? >{&square, &circle};

The second drawback⁴ is a little more subtle. Anybody who uses the template-based area(const auto&) method must either explicitly specify the concrete type, or be a template itself, to pass along the template type of area().

Deriving std::any §

Imagine Square and Circle are fixed types with no shared base class, and you cannot change them to inherit from one. But you still want to handle them through a single common interface.

One way to do that is to introduce wrappers. Define your own Shape interface, then create wrapper classes that inherit from Shape and contain a Square or Circle; each wrapper implements the virtual methods by simply forwarding calls to the wrapped object

class SquareWrapper : public Shape {
 Square square_;
public:
 explicit SquareWrapper(Square square) noexcept : square_{std::move(square)} {}
 auto area() const noexcept -> double override { return square_.area(); }
};

class CircleWrapper : public Shape {
 Circle circle_;
public:
 explicit CircleWrapper(Circle circle) noexcept : circle_{std::move(circle)} {}
 auto area() const noexcept -> double override { return circle_.area(); }
};

Now we can work directly with instances of Shape

auto printAreas(const std::vector<std::unique_ptr<Shape>>& shapes) -> void {
 for (const auto& shape : shapes) {
 std::println("Area is {:.2f}", shape->area());
 }
}

auto main() -> int {
 auto shapes = std::vector<std::unique_ptr<Shape>>{};
 shapes.emplace_back(std::make_unique<SquareWrapper>(Square{2}));
 shapes.emplace_back(std::make_unique<CircleWrapper>(Circle{1}));
 printAreas(shapes);
}

This approach works, but it has an obvious downside: you need a separate wrapper type (like CircleWrapper) for every concrete type you want to adapt (like Circle), which quickly turns into a pile of boilerplate. Luckily, templates can offload much of that work to the compiler by generating the needed code for each type automatically

template <typename T>
class ShapeWrapper : public Shape {
 T shape_;
public:
 explicit ShapeWrapper(T shape) noexcept : shape_{std::move(shape)} {}
 auto area() const noexcept -> double override { return shape_.area(); }
};

What we built above is the basis of the “type erasure” idiom. All that’s left is to hide all this machinery behind another class, so that callers don’t have to deal with our custom interfaces and templates⁵

class AnyShape {
 class Shape { // The interface
 public:
 virtual ~Shape() = default;
 virtual auto area() const noexcept -> double = 0;
 };

 template <typename T>
 class ShapeWrapper : public Shape { // The wrappers
 T shape_;

 public:
 explicit ShapeWrapper(T shape) noexcept : shape_{std::move(shape)} {}
 auto area() const noexcept -> double override { return shape_.area(); }
 };

 std::unique_ptr<Shape> shape_;

public:
 template <typename T>
 explicit AnyShape(T&& shape)
 : shape_{std::make_unique<ShapeWrapper<T>>(std::forward<T>(shape))} {}

 auto area() const noexcept -> double { return shape_->area(); }
};

It works the same as before, but the wrapper logic is hidden from the consoomer

auto printAreas(const std::vector<AnyShape>& shapes) -> void {
 for (const auto& shape : shapes) {
 std::println("Area is {:.2f}", shape.area());
 }
}

auto main() -> int {
 auto shapes = std::vector<AnyShape>{};
 shapes.emplace_back(Square{2});
 shapes.emplace_back(Circle{1});
 printAreas(shapes);
}

Generic std::any §

Both Shape and ShapeWrapper have accepted standard names: the former is the type-erasure concept⁶ (the interface we program against), and the latter is the model (a templated wrapper that implements the interface and forwards to a concrete type).

Let’s rewrite our original type erasure example to use the standard parlance. Nothing needs to be changed except a few type names

#include <memory>

class Any {
 class Concept {
 public:
 virtual ~Concept() = default;
 virtual auto f() const noexcept -> double = 0;
 };

 template <typename T>
 class Model : public Concept {
 T obj_;
 public:
 explicit Model(T obj) noexcept : obj_{std::move(obj)} {}
 auto f() const noexcept -> double override { return obj_.f(); }
 };

 std::unique_ptr<Concept> obj_;

public:
 template <typename T>
 explicit Any(T&& obj) : obj_{std::make_unique<Model<T>>(std::forward<T>(obj))} {}

 auto f() const noexcept -> double { return obj_->f(); }
};

That’s it! The class Any is a simplified version of std::any,⁷ which is even used in the STL itself (namely, in std::function). But that’s for another post.

Remember that interfaces that are intended to be used through a Base& or Base* must have a virtual destructor, to ensure derived classes are properly destructed (C.127). ↩︎
In some cases, you may not have control of the concrete types (e.g. think STL types like std::string), or it may not even be possible for the concrete type to inherit (e.g. builtins like int). ↩︎
If you tried to pass in a type that doesn’t conform to the ‘interface’ (say, std::string), the compiler would hit an error when you try to compile the method call, complaining that std::string doesn’t have an area method. ↩︎
Since you’re employing polymorphism in the first place, most callers will likely fall into the second group, and will need to be templates themselves too so they can pass the type through. That can quickly spread templates across the codebase, making it harder to read and structure, increasing compile times, and producing larger binaries with slower startup. ↩︎
This implementation always heap-allocates. Production std::any implementations often use small buffer optimization (SBO) techniques to store small objects inline and avoid allocation. ↩︎
The type erasure concept is an OO-style interface (a vtable). It’s unrelated to C++20 concept (compile-time predicates). ↩︎
For a Rust version, see Waifod’s post Polymorphism in C++ and Rust: Type Erasure. ↩︎

Devirtualization and Static Polymorphism

Wed, 25 Feb 2026 09:45:00 +0000

Ever wondered why your “clean” polymorphic design underperforms in benchmarks? Virtual dispatch enables polymorphism, but it comes with hidden overhead: pointer indirection, larger object layouts, and fewer inlining opportunities.

Compilers do their best to devirtualize these calls, but it isn’t always possible. On latency-sensitive paths, it’s beneficial to manually replace dynamic dispatch with static polymorphism, so calls are resolved at compile time and the abstraction has effectively zero runtime cost.

Virtual dispatch §

Runtime polymorphism occurs when a base interface exposes a virtual method that derived classes override. Calls made through a Base& are then dispatched to the appropriate override at runtime. Under the hood, a virtual table (vtable) is created for each class, and a pointer (vptr) to the vtable is added to each instance.

Figure 1: Virtual dispatch diagram. The method foo is declared virtual in Base and overridden in Derived. Both classes get a vtable, and each object gets a vptr pointing to the corresponding vtable.

On a virtual call, the compiler loads the vptr, selects the right slot in the vtable, and performs an indirect call through that function pointer. The drawback is that the extra vptr increases object size, and the indirection through the vtable makes the call hard to predict. This prevents inlining, increases branch mispredictions, and reduces cache efficiency.

The best way to observe this phenomenon is by inspecting the assembly¹ code emitted by the compiler for a minimal example

class Base {
public:
 auto foo() -> int;
};

auto bar(Base* base) -> int {
 return base->foo() + 77;
}

For a non-virtual member function foo like in the example above, the free function bar issues a direct call

bar(Base*):
 sub rsp, 8
 call Base::foo() // Direct call
 add rsp, 8
 add eax, 77
 ret

However, declaring foo as virtual changes bar’s assembly into an indirect, vtable-based call

bar(Base*):
 sub rsp, 8
 mov rax, QWORD PTR [rdi] // vptr (pointer to vtable)
 call [QWORD PTR [rax]] // Virtual call
 add rsp, 8
 add eax, 77
 ret

Devirtualization §

Sometimes the compiler can statically deduce which override a virtual call will hit. In those cases, it devirtualizes the call and emits a direct call instead (skipping the vtable). For example, devirtualization is straightforward² when the runtime type is clearly fixed

struct Base {
 virtual auto foo() -> int = 0;
};

struct Derived : Base {
 auto foo() -> int override { return 77; }
};

auto bar() -> int {
 Derived derived;
 return derived.foo(); // compiler knows this is Derived::foo
}

The compiler is able to devirtualize even through a base pointer, as long as it can track the allocation and prove there is only one possible concrete type. The problem is that with traditional compilation, object files are created per translation unit (TU)—compiled and optimized in isolation. The linker simply stitches those objects together, so cross-TU optimizations are inherently limited. That’s where compiler flags are useful.

-fwhole-program: tells the compiler “this translation unit is the entire program.” If no class derives from Base in this TU, the compiler is free to assume nothing ever does, and can devirtualize calls on Base.
-flto: link-time optimization. Keeps an intermediate representation in the object files and optimizes across all of them at link time, effectively treating multiple source files as a single TU.

On the language side, final is a lightweight way to give the compiler the same guarantee for specific methods

class Base {
public:
 virtual auto foo() -> int;
 virtual auto bar() -> int;
};

class Derived : public Base {
public:
 auto foo() -> int override; // override
 auto bar() -> int final; // final
};

auto test(Derived* derived) -> int {
 return derived->foo() + derived->bar();
}

Here, foo() can still be overridden, so derived->foo() remains a virtual call. However, bar() is marked as final, so the compiler emits a direct call even though it’s declared virtual in the base

test(Derived*):
 push rbx
 sub rsp, 16
 mov rax, QWORD PTR [rdi]
 mov QWORD PTR [rsp+8], rdi
 call [QWORD PTR [rax]] // Virtual call
 mov rdi, QWORD PTR [rsp+8]
 mov ebx, eax
 call Derived::bar() // Direct call
 add rsp, 16
 add eax, ebx
 pop rbx
 ret

Static polymorphism §

When the compiler can’t devirtualize, one option is to use static polymorphism instead. The canonical tool for this is the Curiously Recurring Template Pattern³ (CRTP). With CRTP, the base class is templated on the derived class, and invokes methods on it via static_cast—no virtual keyword involved

template <typename Derived>
class Base {
public:
 auto foo() -> int {
 return 77 + static_cast<Derived*>(this)->bar();
 }
};

class Derived : public Base<Derived> {
public:
 auto bar() -> int {
 return 88;
 }
};

auto test() -> int {
 Derived derived;
 return derived.foo();
}

With -O3 optimization, the compiler inlines everything and constant-folds the result. No vtable, no vptr, no indirection. Fully optimized⁴ call.

test():
 mov eax, 165 // 77 + 88
 ret

Deducing this. C++23’s deducing this keeps the same static-dispatch model but makes it easier to write. Instead of templating the entire class (and writing Base<Derived> everywhere), you template only the member function that needs access to the derived type, and let the compiler deduce self from *this

class Base {
public:
 auto foo(this auto&& self) -> int { return 77 + self.bar(); }
};

class Derived : public Base {
public:
 auto bar() -> int { return 88; }
};

This yields identical optimized code: foo is instantiated as foo<Derived>, and the call to bar is resolved statically and inlined.

Assembly generated with gcc at -O3 on x86-64. Similar results were observed with clang on the same platform. ↩︎
The compiler emits a direct call to Derived::foo (or inlines it), because derived cannot have any other dynamic type. ↩︎
The curiously recurring template pattern is an idiom where a class X derives from a class template instantiated with X itself as a template argument. More generally, this is known as F-bound polymorphism, a form of F-bounded quantification. ↩︎
The trade-off is that each Base<Derived> instantiation is a distinct, unrelated type, so there’s no common runtime base to upcast to. Any shared functionality that operates across different derived types must itself be templated. ↩︎

David Álvarez Rosa

Sat, 24 Jan 2026 12:31:00 +0000

¹Mathematician and engineer based in sunny Dublin, passionate about low-latency, high-performance systems.

Currently working in algorithmic trading at Susquehanna. Previously designed and built systems at Amazon serving 10M+ monthly active customers, developed semantic caching for LLMs at Sopra Steria, and conducted quantitative cybersecurity risk analysis at Deloitte.

Holds a BSc in Mathematics, a BEng in Industrial Engineering, and an MSc in Artificial Intelligence.

Experience §

Software Engineer @ Susquehanna ²
High-frequency options trading. Low-latency market data and trading signals. Mentor and interviewer.

Software Engineer II @ Amazon ³
Designed systems for 10M+ monthly active customers. Contributed to 100+ internal repos. Won org hackathon. Promoted in 18 months (top 5%). Mentored 3. On-call. Interviewer.

Machine Learning Engineer @ Sopra Steria ⁴
Researched, designed, and built a semantic cache for LLMs.

Risk Analyst @ Deloitte ⁵
Quantitative analysis of technological and cybersecurity risks for top-tier banking companies.

Visiting Researcher @ Vector Institute ⁶
Research thesis on multimodal learning (recomprehension.com).

Machine Learning Engineer @ BCN eMotorsport ⁷
Perception at Driverless UPC. Served as LiDAR lead and collaborated on computer vision for a fully autonomous car.

Education §

MSc in Artificial Intelligence ⁸
Official study program focused on AI research and enabling PhD.

MSc in Mathematics
Math-lover part-time student. Dropout (joined Amazon).

Research Thesis ⁹
Research thesis on multimodal learning at University of Toronto.

BSc in Mathematics ¹⁰
Rigorous and proof-oriented degree with a robust mathematical base.

BEng in Industrial Engineering ¹¹
Multidisciplinary and integrative vision of industrial engineering.

Licenses & certifications §

Certificate in Advanced English (C1) — Cambridge University
Machine Learning — Stanford University
Deep Learning — deeplearning.ai
Blockchain & Financial Technology — Hong Kong University
Nova Talent Member — Nova

Volunteering §

Mathematics Tutor
Academic training for the Mathematical Olympiads.

Volunteer @ Banco de Alimentos
Food collection for people in need.

Honors & awards §

Mathematical Olympiad
Silver in local (Pamplona), honors in national (Barcelona).

Physics Olympiad
Gold in local (Pamplona), silver in national (Seville).

Mobility Scholarship — Cellex (CFIS) ¹²
Scholarship to carry out my research thesis at Toronto (€6k).

Tuition and Housing Scholarship — Cellex (CFIS)
University tuition and housing (€19k).

General Scholarship — Government of Spain
Full university tuition plus an annual stipend (€11k).

Languages §

English — Proficient
Spanish — Native
Catalan — Intermediate

Contact §

You can reach me at david@alvarezrosa.com (preferred) or +34 647 13 39 30.

That’s me! March 2022. ↩︎
Jul 2024–Present
Dublin, Ireland ↩︎
Mar 2022–Aug 2024
Madrid, Spain ↩︎
Apr 2024–Jul 2024
Remote ↩︎
Sep 2021–Mar 2022
Madrid, Spain ↩︎
Sep 2020–Jun 2021
Toronto, Canada ↩︎
Sep 2019–Feb 2020
Barcelona, Spain ↩︎
GPA 9.00/10
Honors in 6 subjects ↩︎
GPA 10/10 (A+) ↩︎
GPA 8.12/10 (top 10%)
Honors in 9 subjects ↩︎
GPA 8.03/10 (top 2%)
Honors in 14 subjects ↩︎
Canceled due to Covid-19 ↩︎

About this Site

Fri, 11 May 2018 21:18:00 +0100

After nearly a decade, I’ve rebuilt my personal site from scratch—a blog on software, self-hosting, and lessons learned along the way. This first post is backdated to when I originally launched a site on this domain, back in 2018.

What?—A personal blog. Posts aim to be concise, practical, and rigorous.

Why?—To give back to the libre software community. To keep a record of my learning journey. To deepen my own understanding by writing things down.¹

Who?—See the About page.

Where?—Self-hosted at my mother’s house in northern Spain (ha!), exposed to the Internet through a WireGuard tunnel to a VPS, and served via a global CDN.

When?—Once or twice a month.

How?—Written in Emacs Org-mode, exported to Hugo with a custom theme.²

If you spot an error or have suggestions, I welcome feedback—reach out via the contact link on the About page.

As Einstein put it, “If you can’t explain it simply, you don’t understand it well enough.” Feynman followed the same principle, testing his understanding by teaching from first principles. ↩︎
Inspired by the work of Edward Tufte and Matthew Butterick. ↩︎

Building a Mouse Jiggler

Mon, 01 Jan 0001 00:00:00 +0000

A microcontroller that pretends to be a keyboard and mouse is one of the most useful weekend projects I’ve put together. It can keep a machine awake during a long compile, replay a tedious sequence of shortcuts at the press of a button, or type out whatever you want—all from a board that costs a couple of euros.

I built mine on an RP2040¹—Raspberry Pi’s first in-house silicon, whose native USB controller makes HID emulation possible without any extra hardware. Source and prebuilt firmware are on GitHub.

A single press of the BOOTSEL button starts the automation; another press stops it.

Hardware §

Any RP2040 board works. I picked up a cheap MINI USB RP2040 Development Board Module from AliExpress—dual core, 4 MB flash, around three euros shipped.

Figure 1: The order. €3.86 a board with free shipping—I grabbed seven so a brick or two along the way wouldn’t end the project.

The official Raspberry Pi Pico is the better documented option, but these no-name clones are pin-compatible and the same firmware runs on either.

Flashing the firmware §

While holding the BOOTSEL button, plug the board into your computer. It enumerates as a USB mass storage device. Identify it with lsblk, create a mount point, and mount it.

$ lsblk
$ sudo mkdir /mnt/micro
$ sudo mount /dev/sda1 /mnt/micro

Grab the latest .uf2 from the releases page. Three binaries are published: fake_keyboard for keyboard only, fake_mouse for mouse only, and fake_keyboard_mouse for both. Copy whichever one you want.

$ cp fake_keyboard.uf2 /mnt/micro

The board reboots automatically and re-enumerates as a keyboard, a mouse, or both. Press BOOTSEL to start the automation, press it again to stop.

Building from source §

If you’d rather build it yourself, install the ARM toolchain.²

$ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib # Arch
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi # Debian

Fetch the Pico SDK and picotool submodules.³

$ git submodule update --init --recursive

Build with CMake, pointing PICO_SDK_PATH at the SDK submodule.

$ PICO_SDK_PATH=./lib/pico-sdk cmake -B build -G Ninja
$ cmake --build build

The build emits three .uf2 files under build, matching the binaries on the releases page. Flash one as described above.

$ cp ./build/fake_keyboard.uf2 /mnt/micro

Hello, world §

The fastest way to confirm the board, toolchain, and SDK are all wired up correctly is to flash a minimal program and watch it print over USB serial.

#include <stdio.h>

#include "pico/stdlib.h"

auto main() -> int {
 stdio_init_all();
 while (true) {
 printf("Hello, world!\n");
 sleep_ms(1000);
 }
}

A matching CMakeLists.txt

cmake_minimum_required(VERSION 3.13)

include(./lib/pico-sdk/pico_sdk_init.cmake)
project(HelloWorld C CXX ASM)

set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

pico_sdk_init()

add_executable(hello_world main.cpp)
pico_enable_stdio_usb(hello_world 1)
pico_enable_stdio_uart(hello_world 0)
target_link_libraries(hello_world pico_stdlib)
pico_add_extra_outputs(hello_world)

Build and flash the same way as before.

$ PICO_SDK_PATH=./lib/pico-sdk cmake -B build -G Ninja
$ cmake --build build
$ cp ./build/hello_world.uf2 /mnt/micro

Once it reboots, attach to the serial TTY⁴ and watch the greeting roll in.

$ screen /dev/ttyACM0
Hello, world!
Hello, world!
Hello, world!

If that works, you have everything you need to iterate on your own HID firmware.

Specifications §

The only specs the manufacturer shipped with the board are these photos—no datasheet, no pinout diagram, nothing.⁵

That’s all the moving parts. The repository ships a few example scripts to get you started—swap them out, recompile, and the board will type⁶ or wiggle in whatever pattern you like.

The board. Roughly the size of a thumbnail—the USB-A plug is etched into the PCB instead of soldered on. ↩︎
arm-none-eabi-gcc is the cross-compiler targeting ARM microcontrollers; arm-none-eabi-newlib provides a slim C standard library suited for embedded targets. ↩︎
The Pico SDK ships the C/C++ libraries for RP2040 development; picotool is a command-line utility for inspecting boards and uploading firmware. ↩︎
The board exposes USB CDC as /dev/ttyACM0 on Linux. Exit screen with Ctrl-a k. ↩︎
Welcome to no-name AliExpress electronics. The RP2040 itself is well documented, so in practice the official datasheet is what you’ll lean on. ↩︎
The keyboard variant in action. ↩︎

Exploring CPU Caches

Mon, 01 Jan 0001 00:00:00 +0000

Pending.

Incremental clang-tidy tool

Mon, 01 Jan 0001 00:00:00 +0000

How to incrementally run clang-tidy or cppcheck

Laissez Faire, Laissez Mourir

Mon, 01 Jan 0001 00:00:00 +0000

There is an arrangement in which whoever cannot pay to survive is told, “Die, then.” We live in it. It has been on my mind as the world prepares to mint its first trillionaire. What follows is numbers. They are worse than you think. Elon Musk is worth $834 billion—a fifth of what the bottom half of America, 66 million households, owns combined¹—and his approved pay package runs to one trillion. This is what a trillion looks like.

One trillion dollars. One million specks, one million dollars each—64 specks tall, 15,625 specks wide. A speck is a comfortable retirement; the median family owns a fifth of one. The plate runs ninety-four thousand pixels to the right—some twenty-five metres of paper—and it does end. Counted at one dollar per second: a million dollars takes 11½ days; a billion, 32 years; the full plate, 31,700 years.

Capital compounds; labour does not. At a conservative 5%, $834 billion yields a median household income ($83,730)² every 63 seconds—a forty-year working life every 42 minutes. Once returns exceed any possible spending, a fortune is no longer earned; it accrues.

The taxes bind mostly those who work. The 25 richest Americans added $401 billion to their net worth over 2014–2018 and paid $13.6 billion in income tax—a true rate of 3.4%: Musk 3.27% (zero in 2018), Bezos 0.98%, Buffett 0.10%.³ A wage earner pays 15.3% from the first dollar—7.65% withheld, 7.65% more via the employer, borne by the worker—four and a half times the billionaires’ rate, before income tax even begins.

Jeff Yass, owner of Susquehanna ($65 billion),⁴ paid the 20% long-term rate on trading income ordinarily taxed near 40%—roughly $1 billion saved, disputed in court.⁵ Susquehanna also owns some 15% of ByteDance, TikTok’s parent;⁶ Yass put $100 million into the 2024 election cycle—$16 million linked to anti-Muslim and pro-Israel groups⁷—and days after they met in March 2024, Trump reversed his support for the TikTok ban; the divest-or-ban law, passed anyway, went unenforced. $100 million shielding a $21 billion stake: 210 to 1.

None of this breaks the law, because the law taxes realization, not accrual: never sell; borrow against the shares—loan proceeds are not income; die, and the cost basis resets, erasing the gain for the heirs. Buy, borrow, die. Not a loophole but the design: taxing those gains at death would raise $536 billion over a decade in the US alone.⁸ Tens of millions then pass untaxed to heirs whose classmates’ median family owns $192,900—total.⁹ That is not equality of opportunity.

Neither is it democracy. Globally, 1.6% of adults own 48.1% of all wealth ($226 trillion); the poorest 1.55 billion share under 1%; the 2,891 billionaires alone hold $15.6 trillion—and wealth buys the legislature’s attention.¹⁰ Laissez faire for them; laissez mourir for the rest.

Tax the rich. Tax net worth. Tax inheritance. Suckers!

Federal Reserve, Distributional Financial Accounts: the bottom 50% of US households held $4.1 trillion—2.5% of household net worth—at end-2024. ↩︎
U.S. Census Bureau, Income in the United States: 2024, report P60-286, September 2025. ↩︎
ProPublica, The Secret IRS Files, June 8, 2021. The “true tax rate” compares federal income tax paid with growth in net worth over the same period. ↩︎
Forbes profile, December 2025. ↩︎
ProPublica, How Susquehanna’s Jeff Yass Avoided $1 Billion in Taxes, 2022. The Tax Court dispute was filed in 2020 and remains pending. ↩︎
“A ban on TikTok would be a blow to local billionaire investor and GOP megadonor Jeff Yass,” The Philadelphia Inquirer, March 13, 2024; ABC News, March 2024. ↩︎
OpenSecrets, donor detail, 2024 cycle; E. Clifton, “Billionaire Jeff Yass linked to $16m in donations to anti-Muslim and pro-Israel groups,” The Guardian, April 24, 2024. ↩︎
Congressional Budget Office, Budget Option: Change the Tax Treatment of Capital Gains from Sales of Inherited Assets, December 2024. ↩︎
Federal Reserve Board, Changes in U.S. Family Finances from 2019 to 2022, Survey of Consumer Finances, October 2023. ↩︎
UBS, Global Wealth Report 2025, June 2025; figures as of end-2024. ↩︎

One Hundred Thousand Views

Mon, 01 Jan 0001 00:00:00 +0000

This site just passed one hundred thousand page views.¹ The number itself is vanity, but each count is a person who read something I wrote, often to the end. So, before anything else: thank you.

Two things in the breakdown are worth passing on.

Almost nobody arrives from Google.² Nine in ten of you came from Reddit or Hacker News: the front page, not the search index. So the traffic spikes and never accrues—a post lands, it’s read widely for a day, and between spikes the line lies flat.³ I don’t own this audience so much as rent it, one post at a time.

And the posts that travel are not the posts you read.⁴ The self-hosting posts win the lottery and are read exactly once, the mark of a drive-by from an aggregator. The deep ones—a lock-free ring buffer, the fundamental theorem of calculus, devirtualization—earn seven to nine views apiece and keep earning them long after the spike has died.⁵ You come back to the hard posts. Virality evaporates; depth compounds.

So, again: thank you for reading. If you’d like the next post to find you rather than leaving it to the front page, subscribe to the newsletter or follow along by RSS.⁶ Either way, you become the kind of reader a spike can’t take back.

On to the next hundred thousand.

Counted by my self-hosted Umami instance, which doesn’t see anyone who blocks it—so the real total is higher. The average visit lasts five and a half minutes, and two thirds of readers leave from the page they landed on. ↩︎
Every search engine combined—Google, Bing, DuckDuckGo, Kagi—accounts for under three percent of arrivals. Google by itself barely registers. ↩︎
Hacker News sends about a third of Reddit’s traffic but reads five times as much per head: eleven views per reader against two. Reddit drove roughly eight thousand views, Hacker News fourteen and a half thousand. The most devoted source of all is isocpp.org, whose readers averaged more than four visits each. ↩︎
Views per reader tell the story: the lock-free ring buffer earns 8.7, the fundamental theorem of calculus 7.5, devirtualization 7.2, type erasure 3.3—against 1.6 and 1.4 for the two self-hosting posts. The ring-buffer post has the most views on the whole site despite a fraction of the reach. ↩︎
The referrer log is full of small delights: the C++ community carried the systems posts on its own (isocpp.org, libhunt, Meeting C++); a whole ecosystem of Hacker News clients and RSS readers I’d never heard of; Chinese aggregators like Zhihu and Weibo; and, for the first time, AI assistants citing pages—Claude, ChatGPT, Gemini, Copilot. My favourites are the entries that shouldn’t exist at all: hits from a phone’s offline cache and from a local /Users/.../index.html path—someone who kept a copy. ↩︎
Both are free and there is no catch. The newsletter is plain text—no tracking, no HTML, just the post—and unsubscribing takes one click. ↩︎

Optimizing a Spin-Lock

Mon, 01 Jan 0001 00:00:00 +0000

A spin-lock is a mutex that never sleeps: instead of yielding to the scheduler when the lock is taken, the thread stays on the CPU and keeps retrying—spinning—until it succeeds, avoiding syscalls and context switches for critical sections of a few nanoseconds. In this post we’ll write the basic version, see why it is slow, and fix it step by step until it beats std::mutex by 3.4x under contention.

The benchmark §

Each thread increments a shared counter under the lock—250k increments in total, split evenly across threads. The total work is fixed: with a perfect lock the time stays flat as threads are added, and any growth is pure synchronization overhead. Threads are pinned to their own cores¹

template <typename SpinLock>
auto BM_SpinLock(benchmark::State& state) -> void {
 const auto num_threads = state.range(0);

 auto spin_lock = SpinLock{};
 auto val = std::uint64_t{};
 auto threads = std::vector<std::thread>{};
 threads.reserve(num_threads);

 for (auto _ : state) {
 for (auto i = 0U; i < num_threads; ++i) {
 threads.emplace_back([&, i] {
 pinThread(i);
 for (auto j = 0U; j < 250'000U / num_threads; ++j) {
 spin_lock.lock();
 ++val;
 spin_lock.unlock();
 }
 });
 }
 for (auto& thread : threads) thread.join();
 benchmark::DoNotOptimize(val);
 threads.clear();
 }
}

Every version below exposes lock and unlock. The baseline, SpinLockV0, simply wraps std::mutex

BM_SpinLock<SpinLockV0>/1/real_time 1.62 ms
BM_SpinLock<SpinLockV0>/2/real_time 5.48 ms
BM_SpinLock<SpinLockV0>/4/real_time 6.13 ms

Going from one thread to two more than triples the time, but from two to four it barely moves: a contended std::mutex parks waiters in the kernel and wakes them one at a time, so the damage does not compound. The number to beat: 6.13 ms at four threads.

A basic spin-lock §

The simplest correct spin-lock is an atomic bool and an exchange loop²

class SpinLockV1 {
 std::atomic_bool locked_{false};

public:
 auto lock() noexcept -> void { while (locked_.exchange(true)); }
 auto unlock() noexcept -> void { locked_.store(false); }
};

BM_SpinLock<SpinLockV1>/1/real_time 1.20 ms
BM_SpinLock<SpinLockV1>/2/real_time 10.3 ms
BM_SpinLock<SpinLockV1>/4/real_time 14.5 ms

Uncontended, the spin-lock already wins: 1.20 ms against the mutex’s 1.62 ms—locking is now a single atomic instruction with no library machinery around it. Under contention it is a disaster: 1.9x slower than the mutex at two threads, 2.4x at four—while burning CPU for the entire wait.

The problem is cache coherence. To write to a cache line, a core must first own it exclusively, invalidating every other core’s copy. An atomic exchange is a write even when it fails and merely swaps true over true. So every waiting thread constantly steals the line away from everyone else—including from the lock holder, who needs that same line back just to release the lock. The line ping-pongs between cores, and the one useful increment drowns in coherence traffic.

perf stat -d counts hardware events; compare one thread against four

$ perf stat -d ./benchmark --benchmark_filter='V1>/1' --benchmark_min_time=500x
 128,088,290 branches
 1,896,594 branch-misses # 1.48% of all branches
 645,478,415 L1-dcache-loads
 1,687,482 L1-dcache-load-misses # 0.26% of all accesses

$ perf stat -d ./benchmark --benchmark_filter='V1>/4' --benchmark_min_time=500x
 674,575,244 branches
 105,479,892 branch-misses # 15.64% of all branches
 3,262,419,243 L1-dcache-loads
 293,873,584 L1-dcache-load-misses # 9.05% of all accesses

A 35x jump in cache miss rate on the same nine bytes of data, and one branch in six mispredicted: whether the exchange succeeds is decided by the other cores, and the predictor cannot learn it. perf c2c—perf’s tool for cache-line contention—ranks cache lines by how often a core found them dirty in another core’s cache (a HITM event)

$ perf c2c record -a -- ./benchmark --benchmark_filter='V1>/4'
$ perf c2c report --stdio
=================================================
 Shared Data Cache Line Table
=================================================
Index Address Hitm
 0 0x7fffffffb440 91.49%
 1 0xffff8c025e923700 2.13%

A single cache line—the one holding the lock and the counter—accounts for 91% of all HITM events. Spinning is not free in watts either; the CPU’s own energy meter³ puts a number on the wait

$ perf stat -a -e power/energy-pkg/ ./benchmark --benchmark_filter='V1>/4' --benchmark_min_time=200x
 24.43 Joules power/energy-pkg/

The mutex does the same 200 iterations for 14.9 J.

Active backoff §

The fix is to stop writing while waiting: attempt the exchange once and, if it fails, spin on a plain load—read-only copies of the line can live in every core’s L1, so waiting generates no traffic at all. But when the holder releases, every waiter sees the lock free at the same instant, and the whole herd stampedes for the exchange—one wins, the rest pay the coherence storm anyway. To thin the herd, space out the reads with a small delay loop⁴

class SpinLockV2 {
 std::atomic_bool locked_{false};

public:
 auto lock() noexcept -> void {
 while (true) {
 if (!locked_.exchange(true)) return;
 do {
 for (volatile int i = 0; i < 150; ++i);
 } while (locked_.load());
 }
 }
 auto unlock() noexcept -> void { locked_.store(false); }
};

At two threads the time drops to 4.82 ms—2.1x faster than the basic version and already ahead of the mutex. At four threads, 12.0 ms, most of the gain evaporates: the herd is bigger, and a fixed delay no longer keeps threads apart. The counters expose a hidden cost, too: the cache misses barely improve (8.6% against 9.1%), and the energy gets worse, 29.5 J against 24.4 J—the delay loop is busy-work executed at full speed.

Passive backoff §

The delay loop burns the whole wait executing useless increments. x86 has an instruction for exactly this: pause, exposed as the _mm_pause() intrinsic⁵, which inserts a short delay with the pipeline relaxed

class SpinLockV3 {
 std::atomic_bool locked_{false};

public:
 auto lock() noexcept -> void {
 while (true) {
 if (!locked_.exchange(true)) return;
 do {
 for (auto i = 0; i < 4; ++i) _mm_pause();
 } while (locked_.load());
 }
 }
 auto unlock() noexcept -> void { locked_.store(false); }
};

The four pause calls roughly match the delay of the 150-iteration loop, and the timings land in the same place: 5.02 ms at two threads and 10.9 ms at four. The difference is in what the timings don’t show: perf counts 24x fewer instructions for the same work—the core now spends the wait deliberately doing nothing—and the energy drops from active backoff’s 29.5 J to 17.9 J.

Exponential backoff §

Pausing made the wait cheap, but the timings barely moved—and with a constant delay they cannot: all waiters poll at the same rate, so every release still wakes the whole herd, and the collisions remain. For the waiters to arrive at different times, their delays must differ: let each thread double its delay every time it finds the lock still taken, up to a cap⁶

class SpinLockV4 {
 std::atomic_bool locked_{false};

public:
 auto lock() noexcept -> void {
 auto backoff_iters = 4;
 while (true) {
 if (!locked_.exchange(true)) return;
 do {
 for (auto i = 0; i < backoff_iters; ++i) _mm_pause();
 backoff_iters = std::min(backoff_iters << 1, 1024);
 } while (locked_.load());
 }
 }
 auto unlock() noexcept -> void { locked_.store(false); }
};

The timings collapse: 1.62 ms at two threads and 1.80 ms at four—within 1.5x of the single-threaded time, approaching the flat line of a perfect lock. That is 3.4x faster than std::mutex and 8x faster than the basic spin-lock.

The counters explain the win: at four threads the cache miss rate falls to 1.6%, branch mispredictions to 2.9%, and the energy to 3.8 J, a quarter of the mutex’s 14.9 J—all near their single-threaded levels. That is the signature of threads running one at a time: backoff approximately serializes them. Waiters sit in pause loops of up to 1024 iterations, so the releasing thread usually re-acquires the lock immediately—lock and counter still warm in its L1—and races through its share of increments while everyone else stays out of the way. Serialization is optimal here, since the increments cannot run in parallel anyway.⁷

Summary §

If you want to reproduce these results, the benchmark lives in my CppPlayground repository. Each cell reads time / L1d cache misses, with the winners in bold.

Version	1 thread	2 threads	4 threads
0	1.62 ms / 0.03%	5.48 ms / 1.03%	6.13 ms / 1.60%
1	1.20 ms / 0.26%	10.3 ms / 3.78%	14.5 ms / 9.05%
2	1.25 ms / 0.25%	4.82 ms / 3.08%	12.0 ms / 8.61%
3	1.25 ms / 0.27%	5.02 ms / 2.60%	10.9 ms / 6.14%
4	1.25 ms / 0.28%	1.62 ms / 0.67%	1.80 ms / 1.59%

The journey is the interesting part: the basic spin-lock lost to std::mutex by 2.4x, and three small fixes—each derived from a measurement—turned that into a 3.4x win. In real code, std::mutex remains the right default; reach for a spin-lock when the critical section is tiny, the threads have dedicated cores, and you have measured the difference.

With pthread_setaffinity_np, on a machine tuned for benchmarking (AMD Ryzen 7 PRO 8700GE, 8 cores at 3.65 GHz): performance governor, hyperthreading and turbo boost disabled. ↩︎
exchange atomically writes true and returns the previous value: false means the lock was free and is now ours; true means someone else holds it, and we retry. ↩︎
The RAPL counters, which perf exposes as power/energy-pkg/; reading them requires system-wide mode (-a) and root. ↩︎
volatile keeps the compiler from deleting the empty loop. The 150 iterations are a tunable parameter, experimentally determined. ↩︎
From <immintrin.h>; ARM’s closest equivalent is the yield instruction. ↩︎
Without the cap, threads would end up pausing long after the lock has become free. Both bounds, 4 and 1024, are tunable. ↩︎
It is also maximally unfair: nothing stops one thread from re-acquiring the lock indefinitely while another starves in its backoff loop. Real implementations bound the unfairness, or enforce FIFO order outright with a ticket lock—at a cost in throughput. ↩︎

Reflecting on One Hundred Thousand Reads

Mon, 01 Jan 0001 00:00:00 +0000

This site just passed one hundred thousand reads. It began as a notebook kept in public, read by almost no one, and the idea hasn’t changed: one well-made post a month, not quick writeups—only deep dives into things that genuinely interest me. So to everyone who has read one: thank you; that is what matters, the rest is just numbers.

The numbers are uneven. Visitors tend to stay—five and a half minutes on average—but where they come from is the surprise: Reddit and Hacker News send nearly 90% of readers, every search engine under 5%.

Two sites, most of it. Reddit and Hacker News send nearly nine in ten readers; every search engine put together sends under one in twenty.

reddit69%

hacker news20%

search engines<5%

others6%

And that is fragile. This traffic spikes, then fades—a post hits a front page, pulls a few thousand reads in a day, then goes quiet; the three most-read owe their 40,000-odd reads to a few such days, not steady interest.¹ Search is the opposite: tiny now, but it grows over time, so the deeper posts are being set up to show up there—and each new one is syndicated more widely.

Thank you, again, for reading.

Optimizing a Lock-Free Ring Buffer leads with 16,635 reads, followed by the Fundamental Theorem of Calculus (12,506) and Devirtualization and Static Polymorphism (11,848). ↩︎

Self-Hosting an Email Server

Mon, 01 Jan 0001 00:00:00 +0000

Self-hosting email gives you full control over your communications—no ads, no scanning, no one can lock you out. It’s easier than most people think, and this guide covers everything I do when setting up a new mail server.

You’ll need a server with a clean Linux install¹ and a domain name pointing to your server’s IP.

DNS records §

Create DNS records for your mail server: A and AAAA records for mail.alvarezrosa.com, plus an MX record pointing to it.² Verify propagation

$ dig mail.alvarezrosa.com A +short
213.32.19.229
$ dig mail.alvarezrosa.com AAAA +short
2001:41d0:305:2100::febc
$ dig alvarezrosa.com MX +short
10 mail.alvarezrosa.com.

Update your server’s hostname to match the mail FQDN. Edit /etc/hosts so that hostname -f returns the fully qualified domain name³

127.0.1.1 mail.alvarezrosa.com homelab

Receiving mail §

Install Postfix and open port 25. During installation, select “Internet Site” and enter mail.alvarezrosa.com as the system mail name.

$ sudo apt install postfix
$ sudo ufw allow 25/tcp

Configure Postfix to accept mail for your domain. Edit /etc/postfix/main.cf and add your domain to mydestination

mydestination = $myhostname, mail.alvarezrosa.com, localhost.alvarezrosa.com, localhost, alvarezrosa.com

Restart Postfix and verify it’s listening⁴

$ sudo systemctl restart postfix
$ sudo ss -tlnp | grep :25
LISTEN 0 100 0.0.0.0:25 0.0.0.0:* users:(("master",pid=13124,fd=13))
LISTEN 0 100 [::]:25 [::]:* users:(("master",pid=13124,fd=14))

Send a test email to david@alvarezrosa.com from Gmail, then check it arrived

$ sudo apt install mailutils
$ mail
"/var/mail/david": 1 message 1 new
>N 1 David Álvarez Ros Wed Feb 4 19:39 80/4544 Hello from GMail

Your server can now receive mail from anywhere in the world.

Sending mail §

Configure Postfix to use your domain in outgoing messages. Edit /etc/postfix/main.cf

myhostname = mail.alvarezrosa.com
mydomain = alvarezrosa.com
myorigin = $mydomain

Restart and send a test message

$ sudo systemctl restart postfix
$ echo "Test from my mail server" | mail -s "Hello" recipient@example.com

TODO check this without DMARC policy – If you send to a major provider like Gmail before setting up authentication, your message will likely land in spam or be silently dropped. That’s expected—we’ll fix it in the authentication section.

Client access §

At this point you can send and receive mail, but only from the server’s command line. To use a real email client, you need IMAP for reading and authenticated SMTP for sending.

Install Dovecot to expose mailboxes via IMAP.⁵

$ sudo apt install dovecot-core dovecot-imapd

Obtain a TLS certificate for the mail subdomain⁶

$ sudo certbot certonly -d mail.alvarezrosa.com

Configure Dovecot TLS. Edit /etc/dovecot/conf.d/10-ssl.conf

ssl = required
ssl_server_cert_file = /etc/letsencrypt/live/mail.alvarezrosa.com/fullchain.pem
ssl_server_key_file = /etc/letsencrypt/live/mail.alvarezrosa.com/privkey.pem

Configure Postfix TLS. Add to /etc/postfix/main.cf

smtpd_tls_key_file = /etc/letsencrypt/live/mail.alvarezrosa.com/privkey.pem
smtpd_tls_cert_file = /etc/letsencrypt/live/mail.alvarezrosa.com/fullchain.pem
smtpd_tls_security_level = encrypt

Enable authenticated SMTP submission. Edit /etc/postfix/master.cf and uncomment the submissions section

submissions inet n - y - - smtpd
 -o syslog_name=postfix/submissions
 -o smtpd_tls_wrappermode=yes
 -o smtpd_sasl_auth_enable=yes
 -o smtpd_recipient_restrictions=permit_sasl_authenticated,reject
 -o milter_macro_daemon_name=ORIGINATING

Configure Postfix to use Dovecot for SASL authentication. Add to /etc/postfix/main.cf

smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes

Connect Dovecot authentication to Postfix. This lets Postfix authenticate users against Dovecot. Edit /etc/dovecot/conf.d/10-master.conf and configure the auth service

service auth {
 unix_listener /var/spool/postfix/private/auth {
 mode = 0660
 }
}

Open ports 465 (SMTPS) and 993 (IMAPS)

$ sudo ufw allow 465/tcp
$ sudo ufw allow 993/tcp

Restart services

$ sudo systemctl restart dovecot postfix

Configure your email client: IMAP server mail.alvarezrosa.com port 993, SMTP server mail.alvarezrosa.com port 465, both with SSL/TLS. Use your Linux username and password as credentials.⁷ Verify you can send and receive.

You now have a fully functional email server—you can read and compose mail from any client. The hard part is done.

Authentication §

Your server works, but mail will land in spam without proper authentication. Modern email requires four mechanisms: rDNS, SPF, DKIM, and DMARC. Each one builds trust with receiving servers, proving you are who you claim to be and that your messages haven’t been forged or tampered with.

rDNS. Reverse DNS (also called PTR records) maps your IP back to your domain, proving you control it. Most mail servers reject messages from IPs without proper rDNS. Configure it through your VPS provider’s control panel—map your IPs to mail.alvarezrosa.com and verify

$ dig +short -x 213.32.19.229
mail.alvarezrosa.com.

SPF. SPF (Sender Policy Framework) specifies which servers can send mail for your domain, preventing spammers from forging your address. Create a DNS TXT record on your root domain: v=spf1 mx -all means only servers listed in your MX records can send; reject all others.⁸ Verify the record

$ dig +short TXT alvarezrosa.com
"v=spf1 mx -all"

DKIM. DKIM (DomainKeys Identified Mail) adds a cryptographic signature to outgoing mail. Receivers verify it against a public key in your DNS, proving the message came from your server and wasn’t altered in transit. Install OpenDKIM to sign outgoing messages.

$ sudo apt install opendkim opendkim-tools
$ sudo mkdir -p /etc/opendkim/keys/alvarezrosa.com
$ sudo opendkim-genkey -b 2048 -D /etc/opendkim/keys/alvarezrosa.com -d alvarezrosa.com -s mail
$ sudo chown -R opendkim:opendkim /etc/opendkim/keys
$ sudo chmod 600 /etc/opendkim/keys/alvarezrosa.com/mail.private

The generated file contains your public key. Create a DNS TXT record at mail._domainkey.alvarezrosa.com with its contents

$ sudo cat /etc/opendkim/keys/alvarezrosa.com/mail.txt

Verify the record is published

$ dig +short TXT mail._domainkey.alvarezrosa.com
"v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0B..."

Configure OpenDKIM. Edit /etc/opendkim.conf⁹

Mode sv
Domain alvarezrosa.com
Selector mail
KeyFile /etc/opendkim/keys/alvarezrosa.com/mail.private
Socket inet:12301@localhost
UserID opendkim
PidFile /run/opendkim/opendkim.pid

Hook Postfix to OpenDKIM. Add to /etc/postfix/main.cf

milter_default_action = accept
milter_protocol = 6
smtpd_milters = inet:localhost:12301
non_smtpd_milters = inet:localhost:12301

Restart services

$ sudo systemctl enable --now opendkim
$ sudo systemctl restart postfix

DMARC. DMARC ties SPF and DKIM together, telling receivers what to do when checks fail. Create a DNS TXT record at _dmarc.alvarezrosa.com. The p parameter sets the policy: start with p=none to monitor without affecting delivery, then switch to p=reject once everything works. The rua parameter sends aggregate reports to your email.

v=DMARC1; p=reject; rua=mailto:david@alvarezrosa.com

Verify the record

$ dig +short TXT _dmarc.alvarezrosa.com
"v=DMARC1; p=reject; rua=mailto:david@alvarezrosa.com"

Verification §

Send a test email to Gmail and check the message headers—SPF, DKIM, and DMARC should all show pass. Use mail-tester.com for a comprehensive deliverability check (aim for 10/10) and MX Toolbox to verify your DNS records.

Congratulations—your email server is now fully operational, with proper authentication that major providers will trust. Messages should land in inboxes, not spam folders.

Note that new mail servers often face deliverability issues due to IP reputation. If your mail lands in spam initially, keep sending legitimate emails and request delisting from any blacklists your IP appears on. Building a positive reputation can take weeks.

I use Debian for servers. For initial server setup, see my First Steps on a New Server post. ↩︎
MX records tell other mail servers where to deliver mail. The number 10 is the priority—lower numbers are tried first if you have multiple mail servers. ↩︎
Postfix uses the FQDN to identify itself in SMTP conversations. The short hostname can remain homelab, but hostname -f must return mail.alvarezrosa.com. ↩︎
You can also test the connection with telnet mail.alvarezrosa.com 25—you should see a Postfix greeting. ↩︎
IMAP keeps messages on the server and syncs across devices. I prefer it over POP3, which downloads messages and typically deletes them from the server. ↩︎
Certbot obtains free certificates from Let’s Encrypt and auto-renews them. Email clients require TLS for secure connections. ↩︎
I use mu4e in Emacs. For testing, Thunderbird works well and auto-detects most settings. ↩︎
Use ~all (soft fail) instead of -all (hard fail) during testing. ↩︎
Mode sv tells OpenDKIM to sign outgoing mail and verify incoming signatures. ↩︎

Self-Hosting Behind CGNAT

Mon, 01 Jan 0001 00:00:00 +0000

This site is self-hosted on a server that cannot accept a single inbound connection: the ISP puts it behind CGNAT, so there is no public IP to forward ports on. The fix is a bridge—a bastion with a real public address—and a WireGuard tunnel dialed out from the homelab: clients connect to the bridge, and the bridge forwards everything back through the tunnel.

The plan §

With carrier-grade NAT, the ISP shares one public IPv4 address across many customers: your router’s WAN address is itself private¹—a second NAT, outside your home, that you don’t control. The classic recipe of port forwarding plus dynamic DNS² dies here: forwarding only gets you through the first NAT, and the address DDNS would publish is shared with hundreds of strangers. Inbound connections are simply impossible.

But outbound connections still work fine—so the homelab dials out, opening a WireGuard tunnel to the bridge and keeping it alive. The bridge keeps only WireGuard itself and its own SSH, and forwards every other inbound connection through the tunnel. From the outside, the bridge is the homelab—DNS just points at it.³ Inside the tunnel, the bridge is 10.0.0.1 and the homelab 10.0.0.2.

 client admin
 | |
 | |
+---------------------------------------------------------+
| public Internet |
+---------------------------------------------------------+
 | | |
 | | |
+---------------------+ +--------------+ |
| bridge 10.0.0.1 | | Cloudflare | | homelab's own
| DNAT * -> homelab | +--------------+ | outbound traffic
+---------------------+ ^^ |
 ^^ || |
 || WireGuard || cloudflared |
 || (all ports) || (backup SSH) |
 vv vv |
+---------------------------------------------------------+
| homelab 10.0.0.2 (behind CGNAT) |
+---------------------------------------------------------+
 | ^
 | self-check via bridge---or reboot |
 +-------------------------------------+

Both tunnels are dialed out from the homelab—only outbound works behind CGNAT. The admin SSHes in through the bridge like any other client (port 22 is forwarded with the rest); the homelab’s own outbound traffic never crosses it, only replies to forwarded connections do. The Cloudflare backup tunnel and the watchdog loop are covered at the end.

The tunnel §

On both machines, install WireGuard and generate a keypair; exchange the public keys—the private ones never leave their machine.

The bridge’s entire setup lives in /etc/wireguard/wg0.conf

[Interface]
Address = 10.0.0.1/24
PrivateKey = <bridge-private-key>
ListenPort = 51820
PostUp = ...
PostDown = ...

[Peer]
PublicKey = <homelab-public-key>
AllowedIPs = 10.0.0.2/32

where PostUp enables IP forwarding and installs the five iptables rules that do the forwarding, tying their lifetime to the tunnel’s⁴

sysctl -w net.ipv4.ip_forward=1 net.ipv4.conf.ens3.route_localnet=1
iptables -t nat -A PREROUTING -i ens3 -p udp --dport 51820 -j RETURN
iptables -t nat -A PREROUTING -i ens3 -p tcp --dport 2222 -j RETURN
iptables -t nat -A PREROUTING -i ens3 -j DNAT --to-destination 10.0.0.2
iptables -A FORWARD -i wg0 -o ens3 -s 10.0.0.2 -j ACCEPT
iptables -A FORWARD -i ens3 -o wg0 -d 10.0.0.2 -j ACCEPT

Two RETURN rules keep WireGuard (51820/udp) and the bridge’s own SSH (2222/tcp) local; the catch-all DNAT rewrites everything else—port 22 included—to the homelab’s tunnel address; and two FORWARD accepts let that traffic flow both ways.⁵ Everything happens inside the kernel: netfilter does the rewriting, and no userspace process ever touches a packet.

The bridge’s own sshd listens on 2222 precisely so that port 22 can be forwarded with everything else: ssh alvarezrosa.com lands on the homelab, ssh -p 2222 on the bridge.⁶

The homelab side dials out and answers. Its /etc/wireguard/wg0.conf

[Interface]
Address = 10.0.0.2/24
PrivateKey = <homelab-private-key>
Table = off
PostUp = ...
PostDown = ...

[Peer]
PublicKey = <bridge-public-key>
Endpoint = 213.32.19.229:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

where PostUp sets up policy routing.

ip route add default dev wg0 table 200
ip rule add from 10.0.0.2 table 200
iptables -t mangle -A PREROUTING -i wg0 -m conntrack --ctstate NEW -j CONNMARK --set-mark 0x1
iptables -t mangle -A PREROUTING -m conntrack --ctdir REPLY -j CONNMARK --restore-mark
ip rule add fwmark 0x1 lookup 200 pref 1000

Each line earns its place: AllowedIPs = 0.0.0.0/0 accepts forwarded clients from anywhere on the Internet; Table = off stops wg-quick from hijacking all of the homelab’s traffic through the bridge⁷; the policy routing sends only replies of forwarded connections—packets from 10.0.0.2—back through the tunnel; and PersistentKeepalive keeps the CGNAT’s idle UDP mapping alive, so the bridge can always reach in.

This source-based rule is enough for services that listen on the homelab itself, but it quietly breaks the moment a forwarded service lives behind a second NAT—a Docker container, most commonly. Such a service sits on its own address (say 172.19.0.4), reached by a further DNAT; and the reply’s source is rewritten back to 10.0.0.2 only in POSTROUTING, after the routing decision is made. At routing time the packet still reads from 172.19.0.4, misses the rule, falls through to the main table, and leaks out the WAN interface—straight into the CGNAT, where it dies. The cure is to route by the connection rather than by an address that isn’t settled yet—the last three lines above. The first marks every new connection arriving on wg0; the second restores that mark onto the packets travelling the other way, in PREROUTING, before the routing decision; and the fwmark rule sends whatever carries the mark through the tunnel. Routing by mark instead of by source keeps the real client IP intact—a MASQUERADE on the homelab would have been shorter, but it would rewrite that address away.

Enable the tunnel on both machines with sudo systemctl enable --now wg-quick@wg0 and verify the handshake with sudo wg. Then the real test: from outside, any connection to the bridge’s public IP should land on the homelab. Point your DNS records at the bridge and the homelab is, for all practical purposes, on the public Internet.

The detour adds latency: this bridge sits in France, the homelab in northern Spain, and the tunnel adds ~37 ms of RTT to every connection.⁸ Not a problem in practice: with heavy optimization and a CDN absorbing most requests, this site—served through this very tunnel—is among the fastest on the web.

Plan for failure §

Two single points of failure, and a plan for each.

If the bridge dies, the tunnel dies with it—so keep a way into the homelab that bypasses it entirely. I run a Cloudflare Tunnel: cloudflared uses the same dial-out trick, outbound-only on both ends, so it also works behind CGNAT.⁹ It exposes the homelab’s sshd at a hostname of its own, and a ProxyCommand in the client’s \~/.ssh/config connects through it—whatever happens to the bridge, ssh homelab2 still gets in.

If the homelab dies, no tunnel will save you—the machine to reboot is the one you can’t reach. So it watches itself with a root cron job—0 5 * * * ssh ssh.alvarezrosa.com || reboot—that SSHes to its own public hostname, out through CGNAT to the bridge and back in through the tunnel, the whole chain end to end, and reboots if that fails.¹⁰

That’s the whole trick: one cheap bridge, one tunnel, five iptables rules—and a server behind CGNAT serves the public Internet, this very page included.

Usually in 100.64.0.0/10, the shared address space reserved for CGNAT by RFC 6598. ↩︎
Shaky even without CGNAT: a rotating address is bad for anything reputation-sensitive like mail, and every rotation means downtime while resolvers keep serving the old IP until the TTL expires. ↩︎
The bridge only pushes packets, so the smallest of servers will do. See First Steps on a New Server for the basic setup. ↩︎
PostDown mirrors PostUp, undoing every command. ens3 is the bridge’s public interface—find yours with ip a and adjust. ↩︎
Note there is no MASQUERADE: conntrack reverses the DNAT on the way out, and the homelab routes its replies back through the tunnel. Forwarded services see the real client IP—something proxies and third-party tunnels can’t offer. This holds for services that terminate on the homelab itself; a service behind a second NAT hop—anything in a Docker container, say—needs one more touch on the homelab, noted below. ↩︎
Add Port 2222 to the bridge’s /etc/ssh/sshd_config before bringing the tunnel up—the moment the DNAT rule takes effect, port 22 belongs to the homelab. ↩︎
Without it, wg-quick would install a default route matching AllowedIPs. ↩︎
Amusingly, pinging the bridge’s public IP from the homelab reports ~74 ms—exactly double. The echo request is DNAT’d back through the tunnel to the homelab itself, so every packet crosses the tunnel twice. ↩︎
Tailscale fills the same role. ↩︎
A bridge outage also trips this check and reboots a perfectly healthy homelab—an acceptable false positive, since a reboot is harmless. ↩︎

Translation Look Aside Buffer

Mon, 01 Jan 0001 00:00:00 +0000

Explain what the TLB is, using maybe hrt blog?

David Álvarez Rosa

Tuning a Server for Benchmarking

A noisy baseline §

Know your hardware §

Pin to a core §

Lock the CPU frequency §

Disable hyperthreading §

Disable turbo boost §

Summary §

Self-Hosting on the Dark Web

The hidden service §

Serving the site §

Building for the onion §

First Steps on a New Server

Hardware, distro, and DNS §

First login §

Dotfiles §

SSH keys §

Timezone, locale, and hostname §

Firewall §

Automatic security updates §

Intrusion prevention §

Web server §

Fundamental Theorem of Calculus

Riemann integral §

Calculus machinery §

Fundamental theorem of calculus §

Optimizing a Lock-Free Ring Buffer

What is a ring buffer? §

Single-threaded ring buffer §

Thread-safe ring buffer §

Lock-free ring buffer §

Further optimization §

Summary §

Deriving Type Erasure

Polymorphism with interfaces §

Polymorphism with templates §

Deriving std::any §

Generic std::any §

Devirtualization and Static Polymorphism

Virtual dispatch §

Devirtualization §

Static polymorphism §

David Álvarez Rosa

Experience §

Education §

Licenses & certifications §

Volunteering §

Honors & awards §

Languages §

Contact §

About this Site

Building a Mouse Jiggler

Hardware §

Flashing the firmware §

Building from source §

Hello, world §

Specifications §

Exploring CPU Caches

Incremental clang-tidy tool

Laissez Faire, Laissez Mourir

One Hundred Thousand Views

Optimizing a Spin-Lock

The benchmark §

A basic spin-lock §

Active backoff §

Passive backoff §

Exponential backoff §

Summary §

Reflecting on One Hundred Thousand Reads

Self-Hosting an Email Server

DNS records §

Receiving mail §

Sending mail §

Client access §

Authentication §

Verification §

Self-Hosting Behind CGNAT

The plan §

The tunnel §