Eli Bendersky's website

Notes on discrete-time Fourier series and transform

2026-09-19T09:39:00-07:00

The following are my notes on discrete-time Fourier series (DTFS), as well as the discrete-time Fourier transform (DTFT). These topics serve as an important theoretical underpinning to the digital processing of signals by computers using the DFT (which will be covered in a future post).

For discrete-time signals, we use the square bracket notation to denote samples: x[n] is the n-th sample of signal x.

We’ll say that a discrete-time (just discrete from this point on, for brevity) signal is periodic with period N if:

\[x[n]=x[n+N]\qquad\forall{n}\]

When talking about continuous-time Fourier series, we started with real trigonometric functions and later moved to complex exponentials. Here, we’ll just go ahead and start directly with (discrete) complex exponentials - converting between the two representations isn’t difficult and can be done as needed (Appendix C in this post demonstrates it).

We’ll be dealing with the following family of signals [1]:

\[\phi_k[n]=e^{ikw_0n}=e^{ik(2\pi/N)n}\qquad \forall k\in\mathbb{Z}\]

These are discrete complex exponentials that are periodic with period N. w_0=\frac{2\pi}{N} is the angular frequency. As discussed in Appendix A, there are only N such distinct signals, since:

\[\phi_k[n]=\phi_{k+N}[n]\qquad\forall{k}\]

Coefficients of discrete-time Fourier series

We’ll want to consider the representation of an arbitrary N-periodic x[n] by a linear combination of \phi_k[n]:

\[x[n]=\sum_{k=\langle N\rangle}a_k\phi_k[n]\]

The notation k=\langle N\rangle means k runs over any sequence of N consecutive integers. Since there are only N distinct signals \phi_k, the order of summation doesn’t matter - as long as all of them are used. So it could go from 0 to N-1, or from 1 to N, or from 2 to N+1, and so on. All of these orders will enumerate all distinct \phi_k.

Going back to our linear combination:

\[x[n]=\sum_{k=\langle N\rangle}a_k\phi_k[n]=\sum_{k=\langle N\rangle}a_ke^{ikw_0n}\]

This is the discrete-time Fourier series (DTFS) representation of x[n] and the coefficients a_k are the Fourier series coefficients. Note that there are no convergence issues as in the continuous case, because we’re dealing with a finite sum.

To find the coefficients a_k, we’ll proceed in a way that’s somewhat similar to the continuous case. Multiply both sides of the equation above by e^{-ir(2\pi/N)n} and sum over N terms:

\[\sum_{n=\langle N\rangle}x[n]e^{-ir(2\pi/N)n}= \sum_{n=\langle N\rangle}\sum_{k=\langle N\rangle}a_ke^{i(k-r)(2\pi/N)n}\]

Interchanging the order of summation on the right-hand side:

\[\sum_{n=\langle N\rangle}x[n]e^{-ir(2\pi/N)n}= \sum_{k=\langle N\rangle}a_k\sum_{n=\langle N\rangle}e^{i(k-r)(2\pi/N)n}\]

By Appendix B, the inner sum on the right-hand side is equal to N when N\mid r-k and to 0 otherwise. Without loss of generality - since we iterate over N consecutive values - let’s just assume this happens in our sum when r=k (and therefore r-k=0, which is an integer multiple of N).

So our equation becomes:

\[\sum_{n=\langle N\rangle}x[n]e^{-ir(2\pi/N)n}=a_r N\]

Or:

\[a_r=\frac{1}{N}\sum_{n=\langle N\rangle}x[n]e^{-ir(2\pi/N)n}\]

To conclude, the Fourier decomposition of a periodic discrete signal x[n] into periodic complex exponentials is:

\[\boxed{ \begin{aligned} x[n]&=\sum_{k=\langle N\rangle}a_k e^{ik(2\pi/N)n}\\ \vspace{2pt}\\ a_k&=\frac{1}{N}\sum_{n=\langle N\rangle}x[n]e^{-ik(2\pi/N)n} \end{aligned} }\]

Example: revisiting the triangular function

Let’s revisit the triangular function t(x) from the post on Fourier series. Here, we’ll be using the following sampled version:

The sampling is done with 12 samples per period of 4. The spacing between two samples is \Delta x=\frac{1}{3}. Another way to express it:

\[t_d[n]=t(n/3)\]

Substituting this into the definition of t(x), we get:

\[t_d[n]= \begin{cases} \frac{n}{3} & 0 \leq n \leq 3 \\ 2-\frac{n}{3} & 3 < n \leq 6 \\ \end{cases}\]

We then do an odd extension [2] to the range n=[6..12), and repeat it with period N=12.

Using considerations similar to the continuous time case, because our function is odd we just need a sine series here:

\[t_d[n]=\sum_{k=1}^{5}b_k sin\frac{k\pi n}{6}\]

The five terms correspond to the five pairs of nonzero-frequency indices; see Appendix C.

And the coefficients are:

\[b_k=\frac{1}{6}\sum_{n=0}^{11}t_d[n]sin\frac{k\pi n}{6}\\\]

We can run this sum over half the period, because the terms at and 12-n are equal (both t_d[n] and the sine change signs). Also, the terms at n=0 and n=6 vanish because t_d[0]=t_d[6]=0:

\[b_k=\frac{1}{3}\sum_{n=1}^{5}t_d[n]sin\frac{k\pi n}{6}\\\]

Looking at the values of t_d:

\[b_1=\frac{1}{3}\left(\frac{1}{3}sin\frac{\pi}{6}+\frac{2}{3}sin\frac{2\pi}{6}+sin\frac{3\pi}{6}+\frac{2}{3}sin\frac{4\pi}{6}+\frac{1}{3}sin\frac{\pi}{6}\right)=\frac{4+2\sqrt{3}}{9}\]

We can similarly calculate all b_k until k=5:

\[\begin{aligned} b_1&=\frac{4+2\sqrt{3}}{9}\\ b_2&=0\\ b_3&=-\frac{1}{9}\\ b_4&=0\\ b_5&=\frac{4-2\sqrt{3}}{9}\\ \end{aligned}\]

The resulting Fourier series is therefore:

\[t_d[n]=\frac{4+2\sqrt{3}}{9}sin\frac{\pi n}{6}-\frac{1}{9}sin\frac{\pi n}{2}+\frac{4-2\sqrt{3}}{9}sin\frac{5\pi n}{6}\]

You can use the following interactive plot to explore this approximation to the discrete triangle function t_d[n]:

Terms in the Fourier series

The dropdown box selects how many of the terms in the series shown above to plot. The orange crosses show where the series’ values at the integer indices are, and the orange line is interpolated to better visualize the sine waves being added. Note that when all the coefficients are used, the DTFS exactly reconstructs the input signal.

Discrete-time Fourier Transform (DTFT)

In the post on the Fourier Transform we’ve seen how non-periodic signals can be represented in the frequency domain by taking the Fourier series and calculating them at the limit L\rightarrow\infty. Here, we’ll do something similar for discrete signals.

Suppose we have a non-periodic discrete signal x[n] of finite duration (it’s zero outside a finite range of indices). Here’s a sample plot:

The bottom half is x_N[n] - a periodic signal, one period (N) of which is equal to x[n]. We choose M large enough that x[n]=0 outside [-M,M] and set N=2M+1.

Since x_N is periodic, we can represent it with DTFS [3]:

\[\begin{aligned} x_N[n]&=\sum_{k=-M}^{M}a_k e^{ik(2\pi/N)n}\\ a_k&=\frac{1}{N}\sum_{n=-M}^{M}x[n]e^{-ik(2\pi/N)n} \end{aligned}\]

We’ll use the notation of angular frequency:

\[\Delta w=\frac{2\pi}{N}\qquad w_k=k\Delta w\]

Then:

\[\begin{aligned} x_N[n]&=\sum_{k=-M}^{M}a_k e^{i w_k n}\\ a_k&=\frac{1}{N}\sum_{n=-M}^{M}x[n]e^{-i w_k n} \end{aligned}\]

Now the critical part; since x[n] is zero outside [-M,M], extending the summation to all integers does not change its value:

\[a_k=\frac{1}{N}\sum_{n=-\infty}^{\infty}x[n]e^{-i w_k n}\]

We’ll define the following continuous function with variable :

\[X(w)=\sum_{n=-\infty}^{\infty}x[n]e^{-i w n}\]

Then at points w_k:

\[a_k=\frac{1}{N}X(w_k)\]

The function X(w) is the discrete-time Fourier transform (DTFT) of x[n]. The inverse DTFT process reconstructs x[n] from X(w), by substituting a_k back into the DTFS:

\[x_N[n]=\sum_{k=-M}^{M}\frac{1}{N}X(w_k) e^{i w_k n}\]

By our definition of \Delta w, we have:

\[\frac{1}{N}=\frac{\Delta w}{2\pi}\]

Therefore:

\[x_N[n]=\frac{1}{2\pi}\sum_{k=-M}^{M}X(w_k) e^{i w_k n}\Delta w\]

Just like in the continuous case, we recognize the sum as a Riemann sum. Let M\rightarrow\infty. The spacing \Delta w tends to zero, and we can rewrite the sum as an integral:

\[x[n]=\lim_{M\rightarrow\infty}x_N[n]=\frac{1}{2\pi}\int_{-\pi}^{\pi}X(w)e^{iwn}dw\]

To conclude, the DTFT and inverse DTFT pair are:

\[\boxed{ \begin{aligned} X(w)&=\sum_{n=-\infty}^{\infty}x[n]e^{-i w n}\\ \vspace{2pt}\\ x[n]&=\frac{1}{2\pi}\int_{-\pi}^{\pi}X(w)e^{iwn}dw \end{aligned} }\]

X(w) is a continuous, periodic function with period 2\pi, because:

\[\begin{aligned} X(w+2\pi)&=\sum_{n=-\infty}^{\infty}x[n]e^{-i (w+2\pi) n}\\ &=\sum_{n=-\infty}^{\infty}x[n]e^{-i w n}e^{-i 2\pi n}\\ &=\sum_{n=-\infty}^{\infty}x[n]e^{-i w n}=X(w)\\ \end{aligned}\]

Therefore, it’s enough to run the integral on any interval of length 2\pi.

The DTFS and DTFT are closely related. Starting with a finite-duration signal x[n], we form a periodic signal by repeating a block of N samples containing it. Its DTFS coefficients are equally spaced, scaled samples of the DTFT:

\[a_k=\frac{1}{N}X\left(\frac{2\pi k}{N}\right)\]

The relation is similar to the one between Fourier series and the Fourier transform in the continuous case.

The DTFT also has useful properties similar to the continuous Fourier transform: linearity, time shifting, the convolution theorem etc, but we won’t spend time on them here.

Appendix A: Discrete-time complex exponentials

Discrete-time complex exponentials have the form e^{iw_0n} where w_0 is the angular frequency. The discrete nature of these functions leads to some interesting outcomes; for example, consider the exponential with angular frequency w_0+2\pi:

\[e^{i(w_0+2\pi)n}=e^{iw_0n}e^{i2\pi n}=e^{iw_0n}\]

Therefore, the exponential at w_0+2\pi is exactly the same as the exponential at w_0. In considering discrete complex exponentials, we need only choose w_0 from a range of length 2\pi.

Another interesting aspect of these functions concerns their periodicity. In order for e^{iw_0n} to be periodic with some positive integer period N, the following must hold:

\[e^{iw_0(n+N)}=e^{iw_0n}\]

In other words:

\[e^{iw_0N}=1\]

So w_0N itself must be an integral multiple of 2\pi. For some integer k:

\[w_0N=k\cdot(2\pi)\Longrightarrow w_0=\frac{k2\pi}{N}\]

For a fixed positive integer N, let’s consider all complex exponentials for which N is a period:

\[\phi_k[n]=e^{ik(2\pi/N)n}\qquad \forall k\in\mathbb{Z}\]

But earlier we’ve said that all complex exponentials with angular frequencies 2\pi apart are identical. This means that the set above consists of only N distinct exponentials. We can choose any starting k and get distinct signals with k, k+1, k+2 and so on until k+N-1. After that, they begin repeating: \phi_N[n]=\phi_0[n] and so on.

All of this is very different from the continuous case, where t is a real number. The signals e^{iw_0t} and e^{i(w_0+2\pi)t} agree only at integer values of t, so they are distinct functions of t\in\mathbb{R}. Consequently, for a fixed positive period , the continuous-time exponentials e^{ik(2\pi/T)t} are distinct for every integer k, giving infinitely many distinct signals.

Appendix B: Sum of consecutive complex exponentials

Let’s consider the following discrete function, defined by a sum:

\[A[k]=\sum_{n=0}^{N-1}e^{i(2\pi/N)kn}\]

We’ll want to consider two cases:

(1) When k is an integer multiple of N: k=rN for some integer r (for example k=0, k=N, k=-2N etc.)

In this case, the sum becomes:

\[A[k]=\sum_{n=0}^{N-1}e^{i(2\pi/N)rNn}=\sum_{n=0}^{N-1}e^{i2\pi rn}\]

Since both r and are integers, the exponent is an integer multiple of 2\pi i, so:

\[A[k]=\sum_{n=0}^{N-1}1=N\]

(2) When k is not an integer multiple of N, let’s do a variable change p=n+1:

\[A[k]=\sum_{p=1}^{N}e^{i(2\pi/N)k(p-1)}\]

We can now use the finite sum formula for a geometric progression with the common ratio r=e^{i(2\pi/N)k}; the sum is:

\[S_N=\frac{1-r^N}{1-r}\]

Note that r\neq 1 because k is not an integer multiple of N. However:

\[r^N=e^{i(2\pi/N)kN}=1\]

Therefore:

\[A[k]=S_N=0\]

While these calculations demonstrate the sums from n=0 to N-1, they work exactly the same for any N consecutive indices, because the summand is periodic in with period N. Therefore:

\[A[k]=\sum_{n=\langle N\rangle}e^{i(2\pi/N)kn}= \begin{cases} N & N\mid k\\ 0 & \text{otherwise} \end{cases}\]

Appendix C: Sine series decomposition of t_d[n]

Using the formula for DTFS developed earlier in the post:

\[\begin{aligned} a_k&=\frac{1}{12}\sum_{n=0}^{11}t_d[n]e^{-ik(\pi/6)n}\\ &=\frac{1}{12}\sum_{n=0}^{11}t_d[n]cos\frac{k\pi n}{6}-i\frac{1}{12}\sum_{n=0}^{11}t_d[n]sin\frac{k\pi n}{6}\\ \end{aligned}\]

Recall that t_d[n] is odd over the full range n=[0..12). Specifically, since the cosine is an even function, we have for any m:

\[\begin{aligned} t_d[12-m]&=-t_d[m]\\ cos\frac{k\pi(12-m)}{6}&=cos(2\pi k -\frac{k\pi m}{6})=cos\frac{k\pi m}{6}\\ \end{aligned}\]

Therefore the cosine terms cancel out throughout the period; term 1 is the same as negative term 11, etc.

We’re left with the sines:

\[a_k=-i\frac{1}{12}\sum_{n=0}^{11}t_d[n]sin\frac{k\pi n}{6}\]

All coefficients are purely imaginary. For convenience, let’s write:

\[\begin{aligned} b_k&=\frac{1}{6}\sum_{n=0}^{11}t_d[n]sin\frac{k\pi n}{6}\\ a_k&=\frac{-i b_k}{2}\\ \end{aligned}\]

Let’s turn back to the Fourier reconstruction formula:

\[t_d[n]=\sum_{k=\langle N\rangle}a_k e^{ik(2\pi/N)n}\]

And pair up exponentials at k with ones at 12-k:

\[e^{i(12-k)\pi n/6}=e^{i2\pi n}e^{-ikn\pi/6}=e^{-ikn\pi/6}\]

Also, since t_d[n] are real, the conjugate of a_k is:

\[a_{12-k}=a_k^*=\frac{ib_k}{2}\]

So adding the paired exponentials with their coefficients and using Euler’s formula:

\[\begin{aligned} a_ke^{i k\pi n/6}+a_{12-k}e^{-i k\pi n/6}&=-\frac{ib_k}{2}e^{i k\pi n/6}+\frac{ib_k}{2}e^{-i k\pi n/6}\\ &=b_k\frac{e^{i k\pi n/6}-e^{-i k\pi n/6}}{2i}\\ &=b_k sin\frac{k\pi n}{6} \end{aligned}\]

Therefore:

\[t_d[n]=\sum_{k=0}^{11}a_k e^{ik(2\pi/N)n}=\sum_{k=1}^{5}b_k sin\frac{k\pi n}{6}\]

We don’t include the terms at k=0 and k=6, because a_0=a_6=0 (sine of an integral multiple of \pi).

[1]	There are a lot of symbols used in this equation. is the "time" index of the signal x[n] - its domain; k enumerates the k-th function \phi_k from a family of functions - each \phi_k[n] is a function of ; N is the period; is the imaginary unit.

[2]	The odd extension may be slightly confusing because we don’t use negative indices. But indices are arbitrary! In our case, within a single period index -n is equivalent to 12-n; if we consider one period around the halfway point of n=6, it’s easy to see that the function is indeed odd.

[3]	Note that we use x[n], not x_N[n] in the summation for a_k. This is because within the chosen range they are equal.

How big are factorials?

2026-08-27T18:52:00-07:00

The other day, I found myself wondering how big 52! (52 factorial) is, and that led me to ponder how these could be estimated without a calculator or a computer.

It turns out there’s some fairly interesting math behind being able to estimate the size (number of digits) of a factorial reasonably accurately. This post will start by stating how to do the estimate, and if you’re curious you can read on for the math background.

Without further ado, the approximation is:

\[\text{number of digits in n!}\approx n\log_{10}\left(\frac{n}{e}\right)+2\]

As an example, let’s use my original question, by estimating this for 52!

Well, 52 divided by e is... 20-ish? And \log_{10}(20) is about 1.3 [1]; therefore our estimate comes out to:

\[\text{number of digits in 52!}\approx 52\cdot 1.3 +2 \approx69\]

The real answer is 68, so this is very close! In estimates like this - when you’re dealing with enormous numbers - being off by a couple of digits usually isn't a big deal.

The Gamma function

The Gamma function for real n>0 is defined [2] as:

\[\Gamma(n)=\int_{0}^{\infty}x^{n-1}e^{-x}dx\]

This integral does not have an analytic expression in the general case, but it does have a very useful property that we can take advantage of. Let’s see what \Gamma(n+1) is:

\[\Gamma(n+1)=\int_{0}^{\infty}x^{n}e^{-x}dx\]

And now use integration by parts with:

\[u=x^n\qquad v=-e^{-x}\]

Then:

\[du=nx^{n-1} dx\qquad dv=e^{-x}dx\]

So:

\[\begin{aligned} \Gamma(n+1)&=\int_{0}^{\infty}x^{n}e^{-x}dx\\ &=\left. -x^n e^{-x}\right|_{0}^{\infty}-\int_{0}^{\infty}-e^{-x}n x^{n-1}dx\\ &=n\int_{0}^{\infty}x^{n-1}e^{-x}dx \end{aligned}\]

But notice that the last integral is just \Gamma(n); therefore, we’ve shown that:

\[\Gamma(n+1)=n\Gamma(n)\]

Let’s also calculate \Gamma(1) - it’s a special case that has an analytical solution:

\[\Gamma(1)=\int_{0}^{\infty}e^{-x}dx=\left. -e^{-x}\right|_{0}^{\infty}=1\]

This helps establish an induction argument:

\[\begin{aligned} \Gamma(2)=1\cdot\Gamma(1)&=1!\\ \Gamma(3)=2\cdot\Gamma(2)&=2!\\ \Gamma(4)=3\cdot\Gamma(3)&=3!\\ \dots\\ \Gamma(n+1)=n\cdot\Gamma(n)&=n! \end{aligned}\]

In other words - the Gamma function is an interpolation of the factorial over all positive reals. Here’s a plot of the Gamma function over a small range; note that the y axis is log-scale because of the function’s fast growth:

Stirling’s approximation

You may have encountered Stirling’s approximation before:

\[n!\approx\sqrt{2\pi n}\cdot\left(\frac{n}{e} \right)^n\]

It’s a great approximation that works reasonably well even for small . This section is a brief overview of how Stirling’s formula is derived from the Gamma function.

Taking:

\[n!=\Gamma(n+1)=\int_{0}^{\infty}x^n e^{-x}dx\]

We’ll start by massaging the integrand a bit:

\[n!=\int_{0}^{\infty}x^n e^{-x}dx=\int_{0}^{\infty}e^{n \ln x} e^{-x}dx\]

And making a change of variables x=ny, which means that dx=ndy:

\[\begin{aligned} n!&=\int_{0}^{\infty}ne^{n\ln(ny) - ny}dy=n\int_{0}^{\infty}e^{n(\ln n+\ln y-y)}dy\\ &=ne^{n\ln n}\int_{0}^{\infty}e^{n(\ln y-y)}dy \end{aligned}\]

These steps make the integral amenable to applying Laplace’s method, which allows us to approximate definite integrals of the form:

\[\int_{a}^{b}e^{nf(x)}dx\]

Where is a twice-differentiable function and some large number. By Laplace’s method, such integrals can be approximated by:

\[\int_{a}^{b}e^{nf(x)}dx\approx\sqrt{\frac{2\pi}{n|f''(x_0)|}}e^{n f(x_0)}\]

Where is the global maximum of .

Let’s see how to apply this method [3] to the latest equation we have for n! (renaming the dummy integration variable back to x):

\[n!=ne^{n\ln n}\int_{0}^{\infty}e^{n(\ln x-x)}dx\]

In our case, f(x)=\ln x - x. It’s easy to show that this function is twice differentiable and has a global maximum at . Moreover:

\[\begin{aligned} f(x_0)&=-1\\ f''(x_0)&=-1\\ \end{aligned}\]

Substituting these into the proper places in Laplace’s approximation, we get:

\[\begin{aligned} n! &\approx ne^{n\ln n}\sqrt{\frac{2\pi}{n}}e^{-n}\\ &\approx \sqrt{2\pi n}\cdot e^{n(\ln n - 1)}\\ &\approx \sqrt{2\pi n}\cdot \left(\frac{n}{e}\right)^n\quad\blacksquare \end{aligned}\]

Number of digits from Stirling’s approximation

We can calculate the number of digits in n! by taking the base-10 logarithm of Stirling’s formula:

\[\begin{aligned} \text{number of digits in n!}&\approx \log_{10} \left(\sqrt{2\pi n}\cdot \left(\frac{n}{e}\right)^n\right)\\ &\approx \log_{10}\left(\sqrt{2\pi n}\right)+ \log_{10}\left(\frac{n}{e}\right)^n\\ &\approx \log_{10}\left(\sqrt{2\pi n}\right)+ n\cdot \log_{10}\left(\frac{n}{e}\right) \end{aligned}\]

Note that the first term is not multiplied by itself; therefore, as grows, it will become less and less noticeable. That said, it still adds a couple of digits - so you should take it into account if you want a more accurate approximation [4]

[1]	Mental tricks for calculating \log_{10} is a different topic, but it really helps to remember that \log_{10}2=0.3, \log_{10}3=0.5, and from here using the various logarithm laws to estimate multiples.

[2]	As a matter of fact, the Gamma function is defined for complex numbers, but for our purpose talking about the reals is sufficient.

[3]	As much as I’d like to dive into why this approximation works, the rabbit hole in this post is already deep enough!

[4]	It adds up to 2 extra digits as long as is less than 1600 or so, and may add more than 2 after that, though no more than 3 until n is 160000. It’s not clear why anyone would like to estimate the number of digits of 1600! (about 4450, in case you were wondering), let alone 160000!

Concurrent Servers: Part 8 - Go

2026-08-22T07:52:00-07:00

This is part 8 in a series of posts on writing concurrent network servers. In this part, we'll switch to Go and see how it tackles the challenges described earlier in the series.

All posts in the series:

Part 1 - Introduction
Part 2 - Threads
Part 3 - Event-driven
Part 4 - libuv
Part 5 - Redis case study
Part 6 - Callbacks, Promises and async/await
Part 7 - Rust
Part 8 - Go (this part)

This post assumes a basic familiarity with the Go programming language.

Sequential state machine server

As before, we'll start with a sequential server for the basic state machine protocol presented in part 1.

This is the main function:

func main() {
  port := "9090"
  if len(os.Args) >= 2 {
    port = os.Args[1]
  }
  log.Println("Serving on port", port)

  listener, err := net.Listen("tcp", ":"+port)
  if err != nil {
    log.Fatal("Error listening:", err)
  }
  defer listener.Close()

  for {
    conn, err := listener.Accept()
    if err != nil {
      log.Printf("Error accepting connection: %v", err)
      continue
    }
    log.Println("connection received from", conn.RemoteAddr())

    if err := server.ServeSerialProtocol(conn); err != nil {
      log.Printf("Error serving %v: %v", conn.RemoteAddr(), err)
    } else {
      log.Println("peer done", conn.RemoteAddr())
    }
  }
}

As in the previous parts, the server is "infinite"; it never stops serving new connections until it's explicitly killed.

This is the function implementing the protocol for a single client; it takes a net.Conn value that represents a socket with a client connected on the other end:

type processingState int

const (
  waitForMsg processingState = iota
  inMsg
)

// ServeSerialProtocol serves our serial protocol to a single TCP connection.
func ServeSerialProtocol(conn net.Conn) error {
  defer conn.Close()

  if _, err := conn.Write([]byte{'*'}); err != nil {
    return err
  }

  var state processingState = waitForMsg
  buf := make([]byte, 1024)
  for {
    n, err := conn.Read(buf)
    for _, b := range buf[:n] {
      switch state {
      case waitForMsg:
        if b == '^' {
          state = inMsg
        }
      case inMsg:
        if b == '$' {
          state = waitForMsg
        } else {
          var bb byte = byte(b) + 1
          if _, err := conn.Write([]byte{bb}); err != nil {
            return err
          }
        }
      }
    }

    // Check error after processing the bytes received along with it.
    if err != nil {
      if errors.Is(err, io.EOF) || errors.Is(err, net.ErrClosed) {
        return nil
      } else {
        return err
      }
    }
  }
}

One goroutine per client

Rather than directly exposing OS threads, the Go runtime implements its own M:N scheduling of lightweight goroutines on top of OS threads. Using goroutines in Go is cheap - both in terms of syntax and developer effort, and in terms of system resources.

Here's a version of our serial protocol server that serves clients concurrently by launching a goroutine for each client. The part of the code that's different from the previous sample is highlighted:

func main() {
  port := "9090"
  if len(os.Args) >= 2 {
    port = os.Args[1]
  }
  log.Println("Serving on port", port)

  listener, err := net.Listen("tcp", ":"+port)
  if err != nil {
    log.Fatal("Error listening:", err)
  }
  defer listener.Close()

  for {
    conn, err := listener.Accept()
    if err != nil {
      log.Printf("Error accepting connection: %v", err)
      continue
    }
    log.Println("connection received from", conn.RemoteAddr())

    go func() {
      if err := server.ServeSerialProtocol(conn); err != nil {
        log.Printf("Error serving %v: %v", conn.RemoteAddr(), err)
      } else {
        log.Println("peer done", conn.RemoteAddr())
      }
    }()
  }
}

The concurrent modification in this case is particularly simple because the server is infinite; there's no point waiting for these goroutines to finish (and hence no need for a sync.WaitGroup). The parameters for server.ServeSerialProtocol are lexically captured from the enclosing scope and its return value is handled by the surrounding closure.

Because goroutines are very cheap, this server is very unlikely to run out of resources due to launching too many goroutines; in fact, it will probably run out of something else - like file descriptors for sockets - first. However, sometimes it's still useful to limit the degree of concurrency - even in Go, and we'll discuss some approaches to do so in the following sections.

Limiting concurrency with a semaphore

Here are some scenarios in which it makes sense to limit the degree of concurrency in Go programs, even though goroutines are cheap to launch and operate:

Tasks may be compute intensive, and the CPU capacity of any server is inherently limited. If too many concurrent goroutines compete for limited CPUs, they will all make very little progress. It may make more sense to have fewer tasks that complete in a reasonable time.
Protecting potentially limited downstream resources, such as concurrent DB connections or other services. For example, if the server has to send requests to other services for each task, and these are rate-limited, concurrency will have to be carefully managed.
Security reasons when work is dictated by clients; malicious clients can overload and crash a service that's too eager to serve, making it unavailable for legitimate clients.

Let's switch to the primality testing server from part 4 for the rest of the post, because it represents a somewhat more realistic workload. As a reminder: the server receives numbers, simulates blocking by sleeping, and returns "prime" or "composite". The unbounded one-goroutine-per-client version looks almost identical to the previous code sample, except that the goroutine invocation calls another function:

go func() {
  if err := server.ServePrimeProtocol(conn); err != nil {
    log.Printf("Error serving %v: %v", conn.RemoteAddr(), err)
  } else {
    log.Println("peer done", conn.RemoteAddr())
  }
}()

Where ServePrimeProtocol is [1]:

// ServePrimeProtocol serves our prime protocol to a single TCP connection.
func ServePrimeProtocol(conn net.Conn) error {
  defer conn.Close()
  buf := make([]byte, 1024)

  for {
    n, readerr := conn.Read(buf)
    if n > 0 {
      // Parse the read buffer to an i64
      num, err := strconv.ParseInt(strings.TrimSpace(string(buf[:n])), 10, 64)
      if err != nil {
        return err
      }

      response := "composite"
      if isPrime(num, true) {
        response = "prime"
      }
      if _, err := conn.Write([]byte(response + "\n")); err != nil {
        return err
      }
    }

    if readerr != nil {
      if errors.Is(readerr, io.EOF) || errors.Is(readerr, net.ErrClosed) {
        return nil
      }
      return readerr
    }
  }
}

// isPrime returns true if n is prime, false otherwise. If delay is true, it
// will sleep for n milliseconds before calculating.
func isPrime(n int64, delay bool) bool {
  if delay {
    time.Sleep(time.Duration(n) * time.Millisecond)
  }

  if n < 2 {
    return false
  }
  if n%2 == 0 {
    return n == 2
  }
  for i := int64(3); i*i <= n; i += 2 {
    if n%i == 0 {
      return false
    }
  }
  return true
}

The simplest way to limit concurrency in Go is by using a counting semaphore, implemented with a channel:

func main() {
  port := "8070"
  if len(os.Args) >= 2 {
    port = os.Args[1]
  }
  log.Println("Serving on port", port)

  listener, err := net.Listen("tcp", ":"+port)
  if err != nil {
    log.Fatal("Error listening:", err)
  }
  defer listener.Close()

  maxConcurrency := runtime.NumCPU()
  sem := make(chan struct{}, maxConcurrency)

  for {
    conn, err := listener.Accept()
    if err != nil {
      log.Printf("Error accepting connection: %v", err)
      continue
    }
    log.Println("connection received from", conn.RemoteAddr())

    // Acquire a token from the semaphore to limit concurrency.
    sem <- struct{}{}

    go func() {
      // Return the token when done serving the connection.
      defer func() { <-sem }()

      if err := server.ServePrimeProtocol(conn); err != nil {
        log.Printf("Error serving %v: %v", conn.RemoteAddr(), err)
      } else {
        log.Println("peer done", conn.RemoteAddr())
      }
    }()
  }
}

The channel sem serves as a semaphore; note that it's a bounded channel with a maximal size. A token is acquired by sending to the channel, and released by receiving from the channel. When the channel is full, the send operation sem <- struct{}{} blocks until a token was removed by some other goroutine [2].

The type of the channel is struct{} which means "empty", or "no data". This is idiomatic in Go for channels that are used solely for their semantics, not to send/receive any actual data.

Worker pool

Since launching goroutines is cheap and limiting concurrency is easy as shown above, the "worker pool" pattern is often unnecessary for scenarios like our server. Still, it has occasional uses (such as when workers have to maintain some non-trivial state across tasks) so it's worth discussing it here.

Here's a variant of our primality testing server that uses a worker pool:

func worker(jobs <-chan net.Conn) {
  for conn := range jobs {
    if err := server.ServePrimeProtocol(conn); err != nil {
      log.Printf("Error serving %v: %v", conn.RemoteAddr(), err)
    } else {
      log.Println("peer done", conn.RemoteAddr())
    }
  }
}

func main() {
  port := "8070"
  if len(os.Args) >= 2 {
    port = os.Args[1]
  }
  log.Println("Serving on port", port)

  listener, err := net.Listen("tcp", ":"+port)
  if err != nil {
    log.Fatal("Error listening:", err)
  }
  defer listener.Close()

  // The channel is unbuffered, so it will block when there are no available
  // workers to accept a new connection.
  jobs := make(chan net.Conn)
  maxConcurrency := runtime.NumCPU()
  for i := 0; i < maxConcurrency; i++ {
    go worker(jobs)
  }

  for {
    conn, err := listener.Accept()
    if err != nil {
      log.Printf("Error accepting connection: %v", err)
      continue
    }
    log.Println("connection received from", conn.RemoteAddr())

    jobs <- conn
  }
}

A fixed number of worker goroutines is launched; these goroutines all receive "jobs" from the same channel. In the Accept loop, each client connection is sent to this channel as a new job and is picked up by the next available worker. As mentioned before, you would typically see a sync.WaitGroup somewhere to ensure clean shutdown of goroutines, but in our case it isn't necessary because we have a server that never exits.

Async?

Do programmers have to resort to async / event-driven programming in Go? In my experience, almost never. Go was designed from the bottom up to be suitable for large-scale concurrency; goroutines are very cheap to create, have a tiny memory footprint and switching happens very quickly, all in user space. Measurements I ran back in 2018 have shown switching times of ~170 ns, as compared to 1-2 microseconds for threads on Linux.

Moreover, Go already uses event-driven loops like epoll underneath for I/O. Goroutines that wait for I/O like sockets are effectively "parked" and consume no resources (beyond their small memory footprint); they are woken up by Go's runtime when their I/O descriptors are ready - this is very similar to how asynchronous programming works!

That said, some people certainly do try to stretch their resources even more with direct asynchronous programming in Go when millions of streams are handled concurrently. All I'll say is that this is very rare, and an overwhelming majority of users never have to do this.

Conclusion

In 2018, I wrote a post named Go hits the concurrency nail right on the head, and after several more years of active coding, I fully stand behind that statement. Go is extremely powerful and ergonomic for concurrent programs; while other environments go to great lengths to implement async-await style event loops in libraries, in Go it's already baked into the core language and runtime. You want event-driven I/O with very lightweight green threads that can also execute blocking tasks without worrying about the function coloring problem? Go has you covered.

Code

All the code for this post is available on GitHub.

[1]

Careful readers will note two issues with this code: (1) the protocol assumes the complete number is read from the socket in a single conn.Read call, and there's no framing - separation between distinct numbers; (2) the prime checking loop uses i*i which may overflow for large numbers.

These issues are consistent across all the versions of the prime server in C, Python, JavaScript and Rust in earlier parts, because my focus was on the simplest possible code to demonstrate a point about concurrency.

[2] Exercise: note that our semaphore protects the entire ServePrimeProtocol, meaning that a malicious (or incompetent) client can connect and idle without sending any requests, thus reducing our concurrent capacity by 1. Adjust the code to move the semaphore around the prime calculation itself, so only this part is bounded.

Concurrent Servers: Part 7 - Rust

2026-08-15T09:41:00-07:00

This is part 7 in a series of posts on writing concurrent network servers. In this part, we discuss how the challenges described in earlier parts are tackled in the Rust programming language.

All posts in the series:

Part 1 - Introduction
Part 2 - Threads
Part 3 - Event-driven
Part 4 - libuv
Part 5 - Redis case study
Part 6 - Callbacks, Promises and async/await
Part 7 - Rust (this part)
Part 8 - Go

Several years have passed since the previous parts were published. I've recently went over them to make sure the information presented is still relevant and all the code samples build and run using modern toolchains. I strongly recommend reviewing the previous parts before reading this one.

This post assumes a basic familiarity with the Rust programming language. It will only explain Rust constructs when we encounter code that wouldn't appear in an introductory book or tutorial.

Setting the baseline - a sequential state machine server

The first few parts in the series focused on a socket server that implements a simple state machine protocol. See part 1 for a complete description of the protocol. Let's start by showing how this protocol is implemented in a basic sequential Rust server:

use async_socket_server::serve_connection;
use std::net::TcpListener;

fn main() -> std::io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "9090".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let listener = TcpListener::bind(addr)?;
    println!("Serving on port {port}");

    loop {
        let (stream, addr) = listener.accept()?;
        println!("connection received from {}", addr);
        if let Err(e) = serve_connection(stream) {
            eprintln!("error serving connection: {}", e);
        } else {
            println!("peer done {addr}");
        }
    }
}

With the function serve_connection defined as:

pub enum ProcessingState {
    WaitForMsg,
    InMsg,
}

pub fn serve_connection(mut stream: TcpStream) -> std::io::Result<()> {
    stream.write_all(b"*")?;

    let mut state = ProcessingState::WaitForMsg;
    let mut buf = [0u8; 1024];
    loop {
        let n = stream.read(&mut buf)?;
        if n == 0 {
            // Connection closed by the client.
            break;
        }

        for byte in &buf[..n] {
            match state {
                ProcessingState::WaitForMsg => {
                    if *byte == b'^' {
                        state = ProcessingState::InMsg;
                    }
                }
                ProcessingState::InMsg => {
                    if *byte == b'$' {
                        state = ProcessingState::WaitForMsg;
                    } else {
                        let newbyte = byte.wrapping_add(1);
                        stream.write_all(&[newbyte])?;
                    }
                }
            }
        }
    }

    Ok(())
}

As a reminder, this server version is sequential because it accepts clients one by one; the main loop blocks on serve_connection until it's done (the client closes the connection), and only then goes back to accept the next client.

One thread per client

Clearly, handling clients one by one won't do. In part 2, we've discussed approaches that use OS threads to handle clients concurrently. Let's start with the unbounded one-thread-per-client solution in Rust:

use async_socket_server::serve_connection;
use std::{net::TcpListener, thread};

fn main() -> std::io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "9090".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let listener = TcpListener::bind(addr)?;
    println!("Serving on port {port}");

    loop {
        let (stream, addr) = listener.accept()?;
        println!("connection received from {}", addr);

        let res = thread::Builder::new().spawn(move || {
            if let Err(e) = serve_connection(stream) {
                eprintln!("error serving connection: {}", e);
            } else {
                println!("peer done {addr}");
            }
        });

        if let Err(e) = res {
            eprintln!("error spawning thread: {}", e);
        }
    }
}

The spawn method returns a Result<JoinHandle<T>>; on success, we allow the handle to be dropped at the end of the loop iteration. In Rust, this detaches the thread; we don't actually wait for it to complete. This is reasonable for our code sample, because the loop is infinite; it never terminates anyway. The potential for runaway threads is just one of the issues with the unbounded threads approach discussed in part 2. The solution is to use a fixed thread pool.

Thread pool

Before diving into the code, a quick note on the design: the thread pool is a fixed set of threads that await "jobs" and handle them to completion. In our case a "job" is serve_connection for a specific client. There are many ways to implement a thread pool; for our use case, I went with a set of threads that all get a shared channel to which the main thread sends jobs. A worker thread picks up the next job from the channel, serves it to completion, and goes back to waiting for the next job. Here's how this looks in code:

struct Job {
    stream: TcpStream,
    addr: SocketAddr,
}

fn worker(receiver: Receiver<Job>) {
    while let Ok(job) = receiver.recv() {
        if let Err(e) = serve_connection(job.stream) {
            eprintln!("error serving connection from {}: {}", job.addr, e);
        } else {
            println!("peer done {}", job.addr);
        }
    }
}

What is Receiver? It's a type from the crossbeam_channel crate:

use crossbeam_channel::{Receiver, bounded};

Rust's builtin channels in std are mpsc - multi producer, single consumer, but what we need for our job queue is a channel that supports multiple consumers (the worker threads). While std does have mpmc, this is an experimental API only available in nightly versions at the time of writing. Therefore, I've opted to include the crossbeam_channel crate that provides well-tested mpmc channels for this sample [1].

And here's the main function:

use async_socket_server::serve_connection;
use crossbeam_channel::{Receiver, bounded};
use std::{
    io,
    net::{SocketAddr, TcpListener, TcpStream},
    thread,
};

const NUM_WORKERS: usize = 256;
const JOB_QUEUE_CAPACITY: usize = NUM_WORKERS;

fn main() -> io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "9090".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let listener = TcpListener::bind(addr)?;
    println!("Serving on port {port}");

    let (tx, rx) = bounded::<Job>(JOB_QUEUE_CAPACITY);
    for _ in 0..NUM_WORKERS {
        let receiver = rx.clone();
        thread::Builder::new().spawn(move || worker(receiver))?;
    }
    drop(rx);

    loop {
        let (stream, addr) = listener.accept()?;
        println!("connection received from {addr}");

        // A full queue blocks this loop, preventing it from accepting more
        // connections until a worker becomes available.
        if tx.send(Job { stream, addr }).is_err() {
            return Err(io::Error::other("all connection workers stopped"));
        }
    }
}

Note that our job channel is bounded - it has a fixed size. This helps naturally implement a backpressure mechanism - if too many clients connect, the following clients will have to wait - the main loop blocks on tx.send and won't accept additional clients on the socket until jobs are cleared from the channel.

Asynchronous, event-driven server

In parts 4, 5 and 6 of the series we've discussed event-driven, or asynchronous servers. Let's see how it's done in Rust. Specifically, part 6 presented a gradation from callbacks to promises to async/await mechanisms; Rust supports all of these and - as you'd expect - modern code is usually written with async/await while hiding all the details of promises (called futures in Rust) underneath.

Without further ado, here's our simple state machine protocol in asynchronous Rust:

use async_socket_server::ProcessingState;
use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "9090".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let listener = TcpListener::bind(addr).await?;
    println!("Serving on port {port}");

    loop {
        let (socket, addr) = listener.accept().await?;
        println!("connection received from {addr:?}");

        tokio::spawn(async move {
            if let Err(e) = serve_connection_async(socket).await {
                eprintln!("error serving connection from {addr:?}: {e}");
            } else {
                println!("peer done {addr:?}");
            }
        });
    }
}

Rust takes an interesting approach to async programming: it supports some of its fundamental building blocks (like futures and the async and await keywords) in the core language, but leaves the actual async engine implementation (the thing that implements the event loop) to external crates. By far the most popular crate for async programming in Rust is is tokio, so that's what we're using here.

After reading the JS code in part 6, the Rust snippet above should appear fairly familiar, except perhaps the explicit tokio task "spawn". Instead of enqueuing a callback on the connection returned by listener.accept, the code spawns a tokio task, which can be seen as a green thread, and hence uses similar terminology [2]. These tasks must not issue blocking calls; therefore, they are supposed to use tokio's I/O utilities instead of the usual, blocking std utilities. In fact, we have to implement an async version of serve_connection to make this work:

async fn serve_connection_async(mut stream: tokio::net::TcpStream) -> std::io::Result<()> {
    stream.write_all(b"*").await?;

    let mut state = ProcessingState::WaitForMsg;
    let mut buf = [0u8; 1024];
    loop {
        let n = stream.read(&mut buf).await?;
        if n == 0 {
            // Connection closed by the client.
            break;
        }

        for byte in &buf[..n] {
            match state {
                ProcessingState::WaitForMsg => {
                    if *byte == b'^' {
                        state = ProcessingState::InMsg;
                    }
                }
                ProcessingState::InMsg => {
                    if *byte == b'$' {
                        state = ProcessingState::WaitForMsg;
                    } else {
                        let newbyte = byte.wrapping_add(1);
                        stream.write_all(&[newbyte]).await?;
                    }
                }
            }
        }
    }

    Ok(())
}

Note how similar this code is to serve_connection from earlier; the only real differences are the await calls on socket reads and writes [3], and the types involved. For example, instead of a std::net::TcpStream used in the synchronous samples, here we're using tokio::net::TcpStream. Tokio has an underlying dependency called mio to handle non-blocking APIs for all kinds of I/O. It wraps OS-specific event loops like epoll to do so efficiently.

Asynchronous primality testing servers

While most of the series has been using a simple state machine server as the driving example, part 6 switched focus to a server for primality testing which simulates long compute tasks. Let's see how this is done in Rust with tokio:

use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "8070".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let listener = TcpListener::bind(addr).await?;
    println!("Serving on port {port}");

    loop {
        let (socket, addr) = listener.accept().await?;
        println!("connection received from {addr:?}");

        tokio::spawn(async move {
            if let Err(e) = serve_client(socket).await {
                eprintln!("error serving connection from {addr:?}: {e}");
            } else {
                println!("peer done {addr:?}");
            }
        });
    }
}

async fn serve_client(mut stream: tokio::net::TcpStream) -> std::io::Result<()> {
    let mut buf = [0u8; 1024];

    loop {
        let n = stream.read(&mut buf).await?;
        if n == 0 {
            // Connection closed by the client.
            return Ok(());
        }

        // Parse read buf into u64.
        let num = std::str::from_utf8(&buf[..n])
            .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?
            .trim()
            .parse::<u64>()
            .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;

        let answer = if isprime(num, true) {
            "prime"
        } else {
            "composite"
        };
        stream
            .write_all((answer.to_string() + "\n").as_bytes())
            .await?;
    }
}

This code is very similar to the previous snippet conceptually; isprime is:

// Check if n is prime, returning a boolean. The delay parameter is optional;
// if true, the function will block for n milliseconds before computing the
// answer. This is useful for simulating a long-running computation.
fn isprime(n: u64, delay: bool) -> bool {
    if delay {
        std::thread::sleep(std::time::Duration::from_millis(n));
    }

    if n < 2 {
        return false;
    }
    if n % 2 == 0 {
        return n == 2;
    }

    let mut r = 3;
    while r * r <= n {
        if n % r == 0 {
            return false;
        }
        r += 2;
    }
    true
}

Note that this sample demonstrates a job that can block (simulated with a sleep in this case). This can be problematic in an async context, as the tokio documentation explains.

One potential solution would be to dispatch a blocking task to a separate thread pool and use tokio channels to communicate with it; this is similar to the approach we've taken in the thread pool sample above.

Part 6 also included a version of this server that caches data on a local Redis instance; the goal was to demonstrate the complexity of event-driven code when additional layers of callbacks are added and how async/await can help mitigate that. Here's our Rust version of this server, using the redis crate (that has a tokio component enabled explicitly to support async calls):

use redis::AsyncTypedCommands;
use redis::aio::MultiplexedConnection;
use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[derive(Clone)]
struct AppState {
    redis_connection: MultiplexedConnection,
}

const REDIS_URL: &str = "redis://127.0.0.1";

#[tokio::main]
async fn main() -> io::Result<()> {
    let port = match std::env::args().nth(1) {
        Some(s) => s,
        None => "8070".to_string(),
    };
    let addr = format!("127.0.0.1:{port}");

    let app_state = AppState {
        redis_connection: {
            redis::Client::open(REDIS_URL)
                .map_err(io::Error::other)?
                .get_multiplexed_async_connection()
                .await
                .map_err(io::Error::other)?
        },
    };

    let listener = TcpListener::bind(addr).await?;
    println!("Serving on port {port}");

    loop {
        let (socket, addr) = listener.accept().await?;
        println!("connection received from {addr:?}");
        let app_state = app_state.clone();

        tokio::spawn(async move {
            if let Err(e) = serve_client(socket, app_state).await {
                eprintln!("error serving connection from {addr:?}: {e}");
            } else {
                println!("peer done {addr:?}");
            }
        });
    }
}

async fn serve_client(
    mut stream: tokio::net::TcpStream,
    mut app_state: AppState,
) -> std::io::Result<()> {
    let mut buf = [0u8; 1024];

    loop {
        let n = stream.read(&mut buf).await?;
        if n == 0 {
            // Connection closed by the client.
            return Ok(());
        }

        // Parse read buf into u64.
        let num = std::str::from_utf8(&buf[..n])
            .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?
            .trim()
            .parse::<u64>()
            .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;

        // Try the redis cache first. If found in cache, send the cached
        // answer.
        let cachekey = format!("primecache:{num}");
        match app_state.redis_connection.get(cachekey.clone()).await {
            Ok(Some(cached)) => {
                stream.write_all((cached.clone() + "\n").as_bytes()).await?;
                println!("cached num {num} is {cached}");
                continue;
            }
            Ok(None) => {
                // Not found in cache, continue to compute.
            }
            Err(error) => {
                return Err(io::Error::other(error));
            }
        }

        let answer = if isprime(num, true) {
            "prime"
        } else {
            "composite"
        };

        // Save answer in cache and send it to the client.
        app_state
            .redis_connection
            .set(cachekey, answer)
            .await
            .map_err(io::Error::other)?;
        stream
            .write_all((answer.to_string() + "\n").as_bytes())
            .await?;
    }
}

Notes:

Because of the function color problem, the redis crate has a connection constructor specifically for async: get_multiplexed_async_connection.
Here we have an example of shared state between tokio tasks - the Redis connection. Note that we don't require any particular synchronization because MultiplexedConnection is Clone; cloning it to different tasks is safe - and in fact that's what we do for each new task. There's no magic here; if you look inside MultiplexedConnection, you'll see that it already has all the synchronization mechanisms implemented internally, as needed.
Due to the magic of async/await, the code in serve_client is nice and linear. We simply await on the Redis call, and once it's back we continue with the rest of the handler. Since we're using an async Redis connection, in case waiting is required, control will be ceded to some other task that's not currently blocked on I/O.

In conclusion, while Rust provides excellent support for async programming, it doesn't solve its inherent issues like function colors and the need for careful separation between blocking and non-blocking tasks. These issues are typically surmountable with some extra care, and async programming with Tokio in Rust is very popular due to its performance benefits.

Code

All the code for this post is available on GitHub.

[1]

Rust makes a conscious design choice to keep its standard library minimal. In part 2, we've used Python's builtin stdlib thread pools; Rust also has several crates that implement thread pools, but I decided against using them because they obscure the underlying working of the code too much. Our sample implements a simple thread pool, but unfortunately still has to reach for an external crate to use a well-supported multi-consumer channel mechanism.

[2] tokio is quite sophisticated; it manages a thread pool with an efficient work-stealing mechanism, onto which new tasks are spawned. Therefore, all shared data must be protected with mutexes or other synchronization primitives, and Rust's traits like Send and Sync play an important role, where applicable.

[3]	Having to code this alternative just for the sake of async invocation is a classical example of the function color problem.

Relative velocity and closing speed

2026-08-03T20:01:00-07:00

In Physics simulations or game engines it’s sometimes useful to determine the speed with which two objects are approaching each other. This post will discuss the concept of closing speed, which is the normal component of the relative velocity of two objects.

Relative velocity and its components

Suppose we have objects A and B [1] with velocity vectors \vec{V_A} and \vec{V_B}. The relative velocity of B w.r.t. A is:

\[\vec{V}_{B|A}=\vec{V}_B-\vec{V}_A\]

Put differently, it’s the velocity of B in A’s frame of reference.

This relative velocity is a vector, and we can split it into orthogonal components. Obviously, the nature of such a split depends on the basis we want to use. We could look at the vector’s x an y components (we’ll be using - two dimensional space, but everything here applies to 3D as well), but for this post we’re interested in something slightly different:

We draw a line connecting the two objects. The component of \vec{V}_{B|A} in the direction of this line is called the normal component of relative velocity, while the component perpendicular to this direction is called the tangential component.

Computing the normal component

How do we find the component of a vector in the direction of a specific line? By using a vector projection!. We’ll represent the line by a vector, and find the projection of \vec{V}_{B|A} onto this vector.

The positions of A and B can also be seen as vectors: \vec{P}_A and \vec{P}_B. The line connecting them can then be expressed as the vector \vec{P}_B-\vec{P}_A:

All we need from this position difference vector is its direction, not its magnitude, however [2]. So we’ll use the unit vector of \vec{P}_B-\vec{P}_A, denoted as:

\[\widehat{P}=\frac{\vec{P}_B-\vec{P}_A}{|\vec{P}_B-\vec{P}_A|}\]

Finally, to find the projection of \vec{V}_{B|A} onto \widehat{P}, we compute [3]:

\[S_c=\vec{V}_{B|A}\cdot\widehat{P}=(\vec{V}_B-\vec{V}_A)\cdot\widehat{P}\]

Where the multiplication operator between the vectors is the dot product. Note that the result of the dot product is a scalar; therefore, the quantity S_c is called the closing speed - it expresses the rate at which the relative distance of the two objects is changing. If it’s positive, the objects are drifting farther apart; if it’s negative, the objects are getting closer together. Therefore the term "closing speed" may be slightly confusing; alternatively, this has been called a "signed separation speed", or "normal relative speed" [4].

The signs in these calculations can be tricky to get right, so we have to be very careful. Let’s see a few examples that will help us make these computations more concrete.

Examples

To build up some intuition and get some practice with the equations, we’ll review the following examples:

Example I: We’ll start by computing the relative position unit vector \widehat{P}:

\[\widehat{P}=\frac{\vec{P}_B-\vec{P}_A}{|\vec{P}_B-\vec{P}_A|}=\frac{\langle 4,0\rangle}{|\langle 4,0 \rangle|}=\langle1,0\rangle\]

Then, the closing speed is:

\[S_c=(\vec{V}_B-\vec{V}_A)\cdot\widehat{P}=\langle -3,0\rangle\cdot\langle1,0\rangle=-3\]

Based on our convention, the negative sign of S_c means that the objects are approaching each other. Due to the simple nature of the example, this result is easy to verify, as it can be immediately guessed just by looking at the diagram.

Example II: Here \widehat{P} is the same as in the previous example. The closing speed is:

\[S_c=(\vec{V}_B-\vec{V}_A)\cdot\widehat{P}=\langle 3,0\rangle\cdot\langle1,0\rangle=3\]

Same magnitude, but different sign from before, because the objects are moving farther apart.

Example III This example is to demonstrate that we get consistent results even if B is to the left of A. Here the relative position unit vector is:

\[\widehat{P}=\frac{\vec{P}_B-\vec{P}_A}{|\vec{P}_B-\vec{P}_A|}=\frac{\langle -2,0\rangle}{|\langle -2,0 \rangle|}=\langle-1,0\rangle\]

And the closing speed:

\[S_c=(\vec{V}_B-\vec{V}_A)\cdot\widehat{P}=\langle 3,0\rangle\cdot\langle -1,0\rangle=-3\]

Which is the same as in example I, as expected. The direction of \widehat{P} flipped, but so did the direction of the relative velocity vector, so the result has the same sign.

Example IV: Finally, an example showing more arbitrary positions and velocities.

\[\widehat{P}=\frac{\vec{P}_B-\vec{P}_A}{|\vec{P}_B-\vec{P}_A|}=\frac{\langle 3,4\rangle}{|\langle 3,4 \rangle|}=\langle0.6,0.8\rangle\]

Then:

\[S_c=(\vec{V}_B-\vec{V}_A)\cdot\widehat{P}=\langle -3,-6\rangle\cdot\langle 0.6,0.8\rangle=-6.6\]

This example is a good opportunity to demonstrate something important about S_c: it’s time-dependent, because positions change with time. Here, -6.6 is the closing speed at the exact moment when A’s and B’s positions and velocities are as stated in the example. In the next time step, the position of A will be \langle2,5\rangle and the position of B will be \langle2,3\rangle, while their velocities remain the same. The S_c then will be quite different. This is a good segue to the next topic - which is a more physical view of closing speed.

Closing speed as a function of time

The computation shown so far represents a static view of the world; perhaps the right word to use is instantaneous. Given the positions and velocities at a given moment, what is the closing speed between the objects at that exact moment?

But there’s no reason to not generalize this using a more standard physical interpretation of velocity.

First, let’s state the position vectors of A and B as a function of time: \vec{P}_A(t) and \vec{P}_B(t). The relative position vector between the objects is also a function of time:

\[\vec{R}(t)=\vec{P}_B(t)-\vec{P}_A(t)\]

Now we’ll define the scalar distance as the magnitude of this vector:

\[r(t)=|\vec{R}(t)|=|\vec{P}_B(t)-\vec{P}_A(t)|\]

We’re interested in \frac{dr(t)}{dt} - the change in this distance over time. Let’s start by breaking R(t) down to its constituents:

\[\begin{aligned} \vec{R}(t)&=\langle x(t),y(t)\rangle \\ r(t)&=\sqrt{x(t)^2+y(t)^2} \end{aligned}\]

By the chain rule [5]:

\[\begin{aligned} \frac{dr(t)}{dt}&=\frac{\frac{d}{dt}(x(t)^2+y(t)^2)}{2\sqrt{x(t)^2+y(t)^2}}\\ &=\frac{2x(t)x'(t)+2y(t)y'(t)}{2\sqrt{x(t)^2+y(t)^2}} =\frac{x(t)x'(t)+y(t)y'(t)}{\sqrt{x(t)^2+y(t)^2}} \end{aligned}\]

Switching back to the vector representation: since \vec{R}(t)=\langle x(t),y(t)\rangle, the numerator of the fraction above is then a dot product between \vec{R}(t) and \vec{R}'(t), we can write this as:

\[\frac{dr(t)}{dt}=\frac{\vec{R}(t)\cdot\vec{R}'(t)}{|\vec{R}(t)|}=\hat{R}(t)\cdot\vec{R}'(t)\]

But \hat{R}(t) is precisely \hat{P} from the earlier section, as a function of time. Moreover:

\[\vec{R}'(t)=\vec{P}'_B(t)-\vec{P}'_A(t)=\vec{V}_B(t)-\vec{V}_A(t)\]

Because velocity is the time derivative of position. Therefore, we end up with the same equation, just as a function of time:

\[\frac{dr(t)}{dt}=\hat{P}(t)\cdot(\vec{V}_B(t)-\vec{V}_A(t))\]

This formulation is more precise because it makes it very obvious that all the quantities we’re dealing with are time dependent.

[1]	Throughout this post, we assume our objects are sufficiently far apart that they can be treated as points (or particles) without any shape, area or volume.

[2]	The velocity components should be the same regardless of how far apart the two objects are.

[3]	In the standard projection formula we’d also divide by the magnitude of \widehat{P}, but in our case it’s a unit vector anyway.

[4]	In some online sources you may see the closing speed described as closing velocity because it has a direction. IMHO this is the wrong framing. Scalars can be signed! The closing speed is certainly a scalar, not a vector.

[5]	The notation x'(t) means \frac{dx(t)}{dt}