James Ma

Dynamic linking with lazy binding

Thu, 05 Feb 2026 00:00:00 +0000

I recently had to debug a dynamic linking issue. This took me down a rabbit hole exploring how dynamic linkers work - in particular, how a dynamic linker resolves an external function at runtime. How it does this is rather peculiar and interesting, so I decided to write down some of the details.

Dynamic linking basics

When your program has a call to an external function in a shared library, for example printf(), the linker needs to somehow resolve the address of that function, since it isn’t contained locally. There are two ways it can accomplish this - statically or dynamically.

Static linking does symbol resolution at compile time, copying all library routines into your executable. This essentially ensures your executable is portable and does not depend on finding libraries on the host system during runtime. However, this wastes a lot of disk space since each program includes an entire copy of every dependency it needs. Imagine if every hello world program on your computer contains an entire copy of libc! Additionally, when a shared library updates, all your programs have to be re-linked against the new version.
Dynamic linking, as its name suggests, accomplishes this dynamically at runtime. At compile time, the linker only inserts some basic information, such as relocation and symbol table information. The rest of the linking is done at runtime. This has the advantage of allowing multiple programs to share the same copy of a shared library by mapping it into their own address space.

Lazy binding

At first glance, this seems simple - just resolve all shared libraries the program needs when it is loaded. One obvious downside is that you end up loading entire shared libraries when most programs will only ever call a few functions.

The solution is a clever approach called lazy binding - a function is only resolved the first time it is called. This allows us to avoid a bunch of unnecessary relocations at load time.

Lazy binding involves two structures known as the GOT (Global Offset Table) and the PLT (Procedure Linkage Table). The GOT is just a table of addresses. The first couple entries store some basic information the dynamic linker needs to resolve functions. After that, there is an entry for every external function that we call, e.g. printf(). Below is what a GOT might look like:

GOT[0]: address of .dynamic
GOT[1]: address of relocation entries
GOT[2]: address of entrypoint for dynamic linker
GOT[3]: address of printf()
...

The PLT, on the other hand, is a table containing sets of instructions. The first entry contains a special set of instructions that jumps to the dynamic linker. Each entry after that specifies instructions for resolving an external function.

PLT[0] (dynamic linker)
   push   0x2fca(%rip)
   jmp    *0x2fcc(%rip)
   nopl   0x0(%rax)

PLT[1] (routine for printf)
   jmp    *0x2fca(%rip)
   push   $0x0
   jmp    0x555555555020

...

The tl;dr is that each time an external function is called, the CPU will jump to its PLT entry, which will jump to its corresponding GOT entry to find an address. For example, when we call printf(), we will jump to PLT[1], which will jump to GOT[3]. The first time the function is called, GOT[3] will jump to the next instruction of PLT[1], allowing PLT[1] to complete resolution of the function address. The linker will then modify GOT[3] to contain the actual resolved address. The next time the function is called, the PLT[1] will again jump to GOT[3] but GOT[3] will now have the address, thus skipping the lookup process. This means there is a runtime cost the first time the function is called, but subsequent invocations will be fast.

Let’s see how this actually works. Note that the following is specific to Linux x86_64 and ELF - if you don’t have this environment you can follow along on https://www.onlinegdb.com.

Consider the following program that calls printf(), a dynamically linked function.

#include <stdio.h>

int main()
{
    printf("Hello, world!\n"); // slow
    printf("Hello, world!\n"); // fast
    return 0;
}

Let’s start gdb and break on main.

$ gdb main
(gdb) break main
Breakpoint 1 at 0x113d: file main.c, line 5.
(gdb) run
Starting program: /home/a.out

Breakpoint 1, main () at main.c:5
5           printf("Hello, world!\n");

Disassembling the main function, we see

(gdb) disas main
Dump of assembler code for function main:
   0x0000555555555139 <+0>:     push   %rbp
   0x000055555555513a <+1>:     mov    %rsp,%rbp
=> 0x000055555555513d <+4>:     lea    0xec0(%rip),%rax        # 0x555555556004
   0x0000555555555144 <+11>:    mov    %rax,%rdi
   0x0000555555555147 <+14>:    call   0x555555555030 <puts@plt>
   0x000055555555514c <+19>:    lea    0xeb1(%rip),%rax        # 0x555555556004
   0x0000555555555153 <+26>:    mov    %rax,%rdi
   0x0000555555555156 <+29>:    call   0x555555555030 <puts@plt>
   0x000055555555515b <+34>:    mov    $0x0,%eax
   0x0000555555555160 <+39>:    pop    %rbp
   0x0000555555555161 <+40>:    ret
End of assembler dump.

First, the compiler noticed that we are printing a constant string so replaced printf() with puts(). Next, we see that instead of calling puts() directly, we call into puts@plt. Let’s examine this routine:

(gdb) disas 'puts@plt'
Dump of assembler code for function puts@plt:
   0x0000555555555030 <+0>:     jmp    *0x2fca(%rip)        # 0x555555558000 <puts@got.plt>
   0x0000555555555036 <+6>:     push   $0x0
   0x000055555555503b <+11>:    jmp    0x555555555020
End of assembler dump.

The first line shows an indirect jump to 0x555555558000, the entry for puts() in the got.plt section, which is the part of the GOT that we care about. Let’s see what this address contains.

(gdb) x/gx 0x555555558000
0x555555558000 <puts@got.plt>:  0x0000555555555036

0x0000555555555036 is simply the next instruction in our PLT! So calling printf() led us to the first instruction in our PLT entry, which jumped to a GOT entry, which led us back to the second instruction in our PLT entry.

Moving on, we push $0x0 onto the stack and jump to 0x555555555020.

(gdb) x/4i 0x555555555020
   0x555555555020:      push   0x2fca(%rip)        # 0x555555557ff0
   0x555555555026:      jmp    *0x2fcc(%rip)        # 0x555555557ff8
   0x55555555502c:      nopl   0x0(%rax)
   0x555555555030 <puts@plt>:
    jmp    *0x2fca(%rip)        # 0x555555558000 <puts@got.plt>

This is actually PLT[0], which is responsible for calling the dynamic linker. We push another argument (0x555555557ff0) onto the stack and do an indirect jump to 0x555555557ff8. If we trace this jump, we arrive at the dynamic linker resolve routine.

(gdb) x/gx 0x555555557ff8
0x555555557ff8: 0x00007ffff7fd8eb0
(gdb) x/gx 0x00007ffff7fd8eb0
0x7ffff7fd8eb0 <_dl_runtime_resolve_xsavec>:    0xe3894853fa1e0ff3

dl_runtime_resolve_xsavec will then use the two stack entries to resolve the actual address of puts().

This seems like a lot of work just to resolve a single function address, but fortunately we only have to do this one time. Let’s step past the first printf statement:

(gdb) n
Hello, world!
6           printf("Hello, world!\n");

Once again, we’ll disassemble the puts@plt entry.

(gdb) disas 'puts@plt'
Dump of assembler code for function puts@plt:
   0x0000555555555030 <+0>:     jmp    *0x2fca(%rip)        # 0x555555558000 <puts@got.plt>
   0x0000555555555036 <+6>:     push   $0x0
   0x000055555555503b <+11>:    jmp    0x555555555020
End of assembler dump.

Just like before, the PLT entry points to a GOT entry. Examining it, we see

(gdb) x/gx 0x555555558000
0x555555558000 <puts@got.plt>:  0x00007ffff6f09910

This is different from what we got before! Recall that the last time around, it was pointing to the second instruction in our PLT entry, a.k.a the jump instruction stored at 0x0000555555555036. But now it directly points to the function address! So the after the dynamic linker resolved the address, it modifies the GOT entry to point to the resolved address of puts().

Let’s verify by trying to call it.

The puts() function takes in a const char* and has return type of void, so we can cast the address to a function pointer of type void(*)(const char*) and try to call it.

(gdb) call ((void(*)(const char*))0x00007ffff6f09910)("Hello, world!\n")
Hello, world!

Success! We’ve found the address of puts() through the GOT and successfully called it.

This whole process seems quite intricate but is a rather neat little trick to ensure we only attempt to resolve a function when it is called and that we only do so the first time. I hope this helped demystify some of the magic dynamic linkers do behind the scenes.

References

Computer Systems A Programmer’s Perspective 3rd Edition—Randal Bryant & David Hallaron
GOT and PLT for pwning
Global Offset Table (GOT) and Procedure Linkage Table (PLT) - bin 0x12

Regular expression matching

Wed, 10 Dec 2025 00:00:00 +0000

This is a writeup of Leetcode 10. Regular Expression Matching.

My motivation for writing this is twofold. The first is that most of the submitted solutions on Leetcode try to be too clever and succinct without giving many examples. Second, this problem is actually quite relevant to my day-to-day work, as I use regular expressions quite often, so I thought it might be worthwhile to slightly understand how they work under the hood.

The problem is as follows: Given an input string s and pattern p, return true if they match. p is a regex pattern and can include the following:

. matches any single character
* matches zero or more of the preceding element

For example: "ab.*" matches "abx"

This is a classic dynamic programming problem where each subresult depends on the previous subresult. The general idea is that we create a 2d matrix dp where dp[i][j] represents whether or not substring s[:i] (end index is exclusive) matches subpattern p[:j]. Since we have a base case of ("", ""), our matrix has dimensions (s.size() + 1, p.size() + 1). We then fill in the matrix iteratively, after which the final result is dp[s.size()][p.size()].

Base case

To start, notice the trivial case where the empty string matches the empty pattern.

   "" a *
"" t
a
b

To fill in the first row, we need to check whether each subpattern match the empty string. This is true only when the current character is "*" and if the previous subpattern also matches. For example, below we encounter a "*", but the subpattern "a" does not match.

   "" a *
"" t  f f 
a
b

Conversely, in this example, all the subpatterns match.

   "" * *
"" t  t t 
a
b

To fill in the first column, we can check if each prefix of s matches the empty pattern. This is true only with the empty string, so the rest of the first column should all be false.

   "" a *
"" t  f f 
a  f
b  f

Recursive case

At each iteration dp[i][j], we look at string s[i - 1] and pattern p[j - 1]. (The -1 is because the dp matrix is one size larger in both dimensions due to the base case ("", "")). There are two possibilities.

The first possibility is that we encounter an exact match or a ".". This case should be true if and only if the previous substring also matches the previous subpattern, i.e. dp[i - 1][j - 1].

For example, here we see pattern "." matches string "c".

p: a b .
       |
       j

s: a b c
       |
       i

So we look one step back - pattern "ab" also matches string "ab", so dp[i][j] is true.

p: a b .
     |
     j

s: a b c
     |
     i

Here’s a counterexample - we get a match, but dp[i-1][j-1] does not hold, so dp[i][j] is false.

p: a b .
       |
       j

s: a x c
       |
       i

In code,

if (s[i - 1] == p[j - 1] || p[j - 1] == '.') {
    dp[i][j] = dp[i - 1][j - 1]
}

The second possibility is that we encounter "*". Since the wildcard "*"matches zero or more characters, we can handle three cases separately: no match, exactly one match, or 2+ matches.

First, "*" can act as an empty set, i.e. we can choose to not match anything.

Consider the following example:

p: a b x *
         |
         j

s: a b
     |
     i

In this case we simply move pointer j back by 2 to skip over the "x*", i.e. dp[i][j - 2].

p: a b x *
     |
     j

s: a b
     |
     i

In code,

if (dp[i][j - 2]) dp[i][j] = true;

Next, to match any number of characters, we first have to check if the wildcard actually matches. This can be done with:

if (s[i - 1] == p[j - 2] || p[j - 2] == '.') {...}

Now we can try to match a single character, e.g. "x".

p: a b y x *
           |
           j
s: a b y x
         |
         i

To do this, we move j back by 2 and i back by 1 and look at the cached result there, i.e. whether or not pattern "aby" matches string "aby" (it does).

p: a b y x *
       |
       j

s: a b y x
       |
       i

In code:

if (dp[i - 1][j - 2]) dp[i][j] = true;

Lastly, to match 2+ characters, consider the following example:

p: a b y x *
           |
           j

s: a b y x x
           |
           i

To match the string "xx" with the pattern "x*", we keep the same pattern, but check whether the previous substring matches by moving i back by 1.

p: a b y x *
           |
           j

s: a b y x x
         |
         i

We see that pattern "abyx*" also matches string "abyx", so dp[i][j] is true. This translates to the following code:

if (dp[i - 1][j]) dp[i][j] = true;

Putting it all together:

bool isMatch(string s, string p) {
    if (p == "") return (s == "");

    vector<vector<bool>> dp(s.size() + 1, vector<bool>(p.size() + 1));

    // base case: empty string, empty pattern
    dp[0][0] = true;
    // base case: empty pattern, first column
    for (int i = 1; i < s.size() + 1; ++i) dp[i][0] = false;
    // base case: empty string, first row
    for (int j = 2; j < p.size() + 1; ++j) {
        dp[0][j] = p[j - 1] == '*' && dp[0][j - 2];
    }

    for (int i = 1; i < s.size() + 1; ++i) {
        for (int j = 1; j < p.size() + 1; ++j) {
            // case 1: exact match
            if ((s[i - 1] == p[j - 1] || p[j - 1] == '.')) {
                dp[i][j] = dp[i - 1][j - 1];
            // case 2: wildcard (*)
            } else if (p[j - 1] == '*') {
                // case 2a: match zero characters
                if (dp[i][j - 2]) dp[i][j] = true;
                if (s[i - 1] == p[j - 2] || p[j - 2] == '.') {
                    // case 2b: match 1 character
                    if (dp[i - 1][j - 2]) dp[i][j] = true;
                    // case 2c: match 2+ characters
                    if (dp[i - 1][j]) dp[i][j] = true;
                }
            }
        }
    }
    return dp[s.size()][p.size()];
}

I realize this implementation is highly redundant and un-optimized, but that is by design. Anyway, I hope this post didn’t leave anyone even more confused :)

Matrix multiplication tricks on CPU

Mon, 27 Oct 2025 00:00:00 +0000

In this post we’ll iteratively improve on multiplying two random 1024 x 1024 float matrices, resulting in a 20x speedup on CPU. We’ll mostly focus on how different mathematical interpretations of matrix multiplication translate to vastly different outcomes on modern hardware, but we’ll also touch a bit on topics like multithreading and SIMD.

You can find the full code for benchmarking here.

Interpretation 1: inner product

There are many interpretions of matrix multiplication. The simplest is that given A @ B = C, each element C[i,j] is the inner product between row A[i,:] and column B[:,j].

The implementation is also the simplest: the first loop iterates through the rows of A, the second loop iterates through the columns of B, the third loop iterates through the columns of A (and rows of B) and calculates the inner product. Here’s an implementation in C++, with each matrix represented as a float array and stored in row-major order.

template <int rowsA, int colsA, int colsB>
float *matmul_naive(float *A, float *B) {
    float *C = new float[rowsA * colsB];
    float tmp;
    for (int rowA = 0; rowA < rowsA; ++rowA) {
        for (int colB = 0; colB < colsB; ++colB) {
            tmp = 0.0;
            for (int colA = 0; colA < colsA; ++colA) {
                tmp += A[rowA * colsA + colA] * B[colA * colsB + colB];
            }
            C[rowA * colsA + colB] = tmp;
        }
    }
    return C;
}

We can stick this in a wrapper function that times how long it takes on a 1024 x 1024 matrix.

#include <chrono>

// Runs and times f(A, B)
float *run_and_time(float*(*f)(float*, float*), float *A, float *B) {
    std::chrono::steady_clock::time_point begin =
        std::chrono::steady_clock::now();
    float *C = f(A, B);
    std::chrono::steady_clock::time_point end =
        std::chrono::steady_clock::now();
    std::cout << "time = " <<
        std::chrono::duration_cast<std::chrono::microseconds>
        (end - begin).count() <<
        "µs" << std::endl;
    return C;
}

Which we can run as

int dim = 1024;
float *A = randmat(dim, dim); // generates pseudo-random dim x dim matrix
float *B = randmat(dim, dim);
float *C0 = run_and_time(matmul_naive<1024, 1024, 1024>, A, B);

This initial run takes 3.71s.

Unfortunately, the simplest interpretation is also the worst in practice since it is oblivious to the CPU’s cache organization. The pain point is the inner-most loop, in which we iterate over all the rows of B. Since we are storing our matrices in row-major order, we discard an entire cache line on each iteration of the inner-most loop.

Interpretation 2: linear combination of rows

To fix this, recall from linear algebra an alternative interpretation of matrix multiplication: that each row of C, C[i,:], is a linear combination of all the rows of B, with the weights given by the columns of row A[i,:].

In other words,

C[i,:] = A[i,0] * B[0,:] + A[i,1] * B[1,:] + ... + A[i,n-1] * B[n-1,:]

Crucially, this means we don’t have to calculate each element of C to its entirety before moving on. We can calculate a partial result and come back to it on the next loop iteration. This allows us to use an entire cached row of B before moving on to the next. In code, this simply translates to a reordering of the two inner loops:

template <int rowsA, int colsA, int colsB>
float *matmul_loop_reordered(float *A, float *B) {
    float *C = new float[rowsA * colsB];
    for (int rowA = 0; rowA < rowsA; ++rowA) {
        for (int colA = 0; colA < colsA; ++colA) {
            for (int colB = 0; colB < colsB; ++colB) {
                C[rowA * colsA + colB] +=
                    A[rowA * colsA + colA] * B[colA * colsB + colB];
            }
        }
    }
    return C;
}

Which brings the time down to more than half our previous run of 1.62s.

However, we have yet another caching inefficiency. Observe that when we get to the next iteration i + 1 of the outer-most loop, we need to load the very first row of B, i.e. B[0,:], again. But since B[0,:] was last used in the beginning of iteration i, it will likely no longer be in the cache.

Interpretation 3: sum of outer products

An interesting property of matrix multiplication is that you can take the outer product of any column of A and any row of B to get a partial result with the same dimensions as C. Add up all the partial results and you get the final result C. This is yet another interpretation of matrix multiplication: C can be viewed as a sum of all the outer products between the columns of A and rows of B.

To exploit this, we can divide our matrices into multiple tiles and run our previous algorithm on each of the tiles. Each tile run results in a intermittent result with the full dimensions of C. The final result is the sum of all the tile runs.

From a hardware standpoint, doing this ensures that we access the same elements close together in time, increasing the likelihood that they are still in the cache. For instance, when we reach iteration i + 1 of the outer loop, the first few rows of B will still be cached from the previous iteration i.

Choosing the correct tile size is non-trivial, but we can do some quick dirty math to estimate. We want to fit in the L1 cache:

1024 tiled row of A (1024 * tile_size * 4B)
tile_size rows of B (tile_size * 1024 columns * 4B)
1 full row of C (1024 * 4B)

The L1d cache size on my machine is 64KB, which means with a tile size of 4, we can keep 36896 bytes cached.

The implementation just adds an additional outer loop, and changes the inner loops to run on specific tiles rather than the whole of A and B.

template <int rowsA, int colsA, int colsB, int tile_size>
float *matmul_tiled(float *A, float *B) {
    float *C = new float[rowsA * colsB];
    // multiply A[:, tile * tile_size : (tile + 1) * tile_size]
    // and B[ tile * tile_size : (tile + 1) * tile_size ,:]
    for (int tile = 0; tile < colsA / tile_size; ++tile) {
        for (int rowA = 0; rowA < rowsA; ++rowA) {
            for (int colA = tile*tile_size; colA<(tile+1) * tile_size; ++colA) {
                for (int colB = 0; colB < colsB; ++colB) {
                    C[rowA * colsA + colB] += 
                        A[rowA * colsA + colA] * B[colA * colsB + colB];
                }
            }
        }
    }
    return C;
}

Unfortunately we don’t quite get a massive speedup we were hoping for; this runs for 1.60s. There’s probably other things going on that are polluting the cache, or maybe our matrices need to be much larger for tiling to have an significant impact.

Multithreading

So far we have only utilized one core, but we can vastly speed up our computation by dividing our work into multiple pieces. We just need to make sure the different pieces of work don’t have any dependencies between each other.

Luckily, matrix multiplication is quite suited for divide-and-conquer approaches, since any submatrix of C C[start_row:end_row,start_col:end_col] depends only on the corresponding rows of A and columns of B, i.e. A[start_row:end_row,:] and B[:,start_col:end_col].

This means we can partition A and B into 2^n blocks and process each combination in a separate thread. With enough cores, in theory we should be able to achieve a 1/2^n speedup. Furthermore, as each thread writes to a separate section of C, we don’t need to worry about race conditions.

A function that computes some submatrix of C is known as a kernel. We can write one that takes the start and end rows and columns, computes the product submatrix, and writes to the appropriate section of C.

template <int rowsA, int colsA, int colsB, int tile_size>
void kernel(float *A, float *B, float *C,
        int start_row, int end_row, int start_col, int end_col) {
    for (int tile = 0; tile < colsA / tile_size; ++tile) {
        for (int rowA = start_row; rowA < end_row; ++rowA) {
            for (int colA=tile*tile_size; colA<(tile+1)*tile_size; ++colA) {
                for (int colB = start_col; colB < end_col; ++colB) {
                    C[rowA * colsA + colB] +=
                        A[rowA * colsA + colA] * B[colA * colsB + colB];
                }
            }
        }
    }
}

To make use of this, we just need to partition A and B, spin up multiple threads, and in each, call the kernel method on a specific combination of partitions.

template <int rowsA, int colsA, int colsB, int tile_size, int num_threads>
float *matmul_multithreaded(float *A, float *B) {
    float *C = new float[rowsA * colsB];
    int start, end;
    int block_size = rowsA / sqrt(num_threads);

    std::vector<std::thread> threads;
    int start_row, end_row, start_col, end_col;
    for (int row = 0; row < sqrt(num_threads); ++row) {
        start_row = row * block_size;
        end_row = row * block_size + block_size;
        for (int col = 0; col < sqrt(num_threads); ++col) {
            start_col = col * block_size;
            end_col = col * block_size + block_size;
            threads.push_back(
                std::thread(kernel<rowsA, colsA, colsB, tile_size>, A, B, C,
                    start_row, end_row, start_col, end_col)
            );
        }
    }
    for (auto &thread: threads) {
        thread.join();
    }
    return C;
}

With just 4 threads, our time improves to 0.46s.

Vectorization

Another way we can parallelize our code is to use SIMD instructions to speed up individual computations. For the sake of simplicity, we’ll use GCC’s SIMD extensions instead of dealing with intrinsics, but the latter is really what you want if you want reliability, as these extensions aren’t part of the C/C++ standard.

Anyhow, here’s how we can define a vector data type of 8 floats packed into a single register.

// 32 bytes for 8 floats
typedef float vec8 __attribute__ (( vector_size(32) ));

vec8 v = {1, 2, 3, 4, 5, 6, 7, 8};
v *= 2;
for (int i = 0; i < 8; ++i) {
    printf("%f ", v[i]);
}

> 2.000000 4.000000 6.000000 8.000000 10.000000 12.000000 14.000000 16.000000

Let’s forget about tiling and multithreading and go back to our loop-reordered example and see if we can improve it using SIMD vector extensions. Recall that we’re working with the row interpretation - that is, each row of C is a linear combination of rows of B, with the weights given by the columns of the corresponding row of A. We can collapse B and C into matrices of size rowsB * colsB / 8, where each element is a 8-float vector. Then, instead of doing colsB multiplications per row of B, we do colsB / 8 multiplications, where each is a vector instruction multiplying a scalar weight in A by a vector in B.

This is what the code looks like.

template <int rowsA, int colsA, int colsB>
vec8 *matmul_simd(float *A, float *B) {
    // setup: reshape B from colsA x colsB to colsA x colsB / 8
    vec8 *B_vec8 = new vec8[colsA * colsB / 8];
    vec8 tmp;
    for (int row = 0; row < colsA; ++row) {
        for (int col = 0; col < colsB / 8; ++col) {
            tmp = {
                B[row * colsB + col*8],
                B[row * colsB + col*8 + 1],
                B[row * colsB + col*8 + 2],
                B[row * colsB + col*8 + 3],
                B[row * colsB + col*8 + 4],
                B[row * colsB + col*8 + 5],
                B[row * colsB + col*8 + 6],
                B[row * colsB + col*8 + 7],
            };
            B_vec8[row * colsB / 8 + col] = tmp;
        }
    }

    // do the actual matmul
    vec8 *C_vec8 = new vec8[rowsA * colsB / 8];
    for (int rowA = 0; rowA < rowsA; ++rowA) {
        for (int colA = 0; colA < colsA; ++colA) {
            for (int colB = 0; colB < colsB / 8; ++colB) {
                C_vec8[rowA * colsB / 8 + colB] +=
                    A[rowA * colsA + colA] * B_vec8[colA * colsB / 8 + colB];
            }
        }
    }
    return C_vec8;
}

Running this on the same 1024 x 1024 matrix takes just 0.24s, without any multithreading or tiling! Redefining our vector type as

typedef float vec16 __attribute__ (( vector_size(64) ))

(16-float vectors) goes even faster, finishing in just 0.18s. You can pack as many floats as the maximum register width your processor supports.

This is just the tip of the iceberg; there are myriad other ways you can redesign your algorithm to exploit SIMD parallelism. Ultimately the name of the game is the fused multiply-add instruction, which multiplies two vectors and adds the result to a third vector - the core or matrix multiplication - all in a single step.

To sum it all up, here’s the final results on multiplying two 1024 x 1024 random matrices:

algorithm	time
naive (inner products)	3.71s
loop-reordered (linear combination of rows)	1.62s
loop-reordered + tile size 4	1.60s
loop-reordered + tile size 4 w/ 4 threads	0.46s
loop-reordered w/ SIMD (vec8)	0.24s
loop-reordered w/ SIMD (vec16)	0.18s

References

C++ smart pointers speedrun

Sat, 04 Oct 2025 00:00:00 +0000

Raw pointers can be useful when you want to manipulate memory directly, but using them comes with consequences if improperly managed, e.g. if you forget to free a pointer, free a pointer more than once, or try to use a pointer after freeing it.

void func() {
    int *i = new int(1);
    int *j = new int(2);
    delete j;
    
    cout << *j << endl; // undefined: use after free
    delete j;           // undefined: double free
}
// memory leak for i

Smart pointers are essentially containers around pointers that have additional memory management capabilities. C++11 comes with three types of smart pointers: unique pointers, shared pointers, and weak pointers.

Unique pointers

A unique pointer is a type of smart pointer that ensures a single owner. It makes sure any memory allocated is reclaimed after the pointer goes out of scope.

void func() {
    // create unique pointer that points to some heap memory
    unique_ptr<int> i = unique_ptr<int>(new int(1));
    // unique_ptr<int> i(new int(1));           // alternate syntax
    // unique_ptr<int> i = make_unique<int>(1); // alternate syntax
}
// i is freed here automatically

To ensure a single owner, unique pointers cannot be assigned or copied.

unique_ptr<int> i = make_unique<int>(2);
unique_ptr<int> j = i;                    // error: cannot copy

unique_ptr<int> j = make_unique<int>(3);
j = i;                                    // error: cannot assign

The copy constructor (used to create a new object from an existing object) and the copy assignment operator (used to replace an existing object with another object) are both intentionally deleted.

You can only move a unique pointer, which transfers its ownership.

unique_ptr<int> i = make_unique<int>(3);
unique_ptr<int> j = move(i);

// j now owns the memory and i is set to nullptr

You can also move a unique pointer by returning it.

unique_ptr<int> return_ptr() {
    unique_ptr<int> res = make_unique<int>(3);
    return res;
}

int main() {
    unique_ptr<int> i = return_ptr();
    // ownership is transferred from res to i
    return 0;
}

The memory is first owned by res, then is transferred to i via the function call. Now, when i goes out of scope, the memory is freed.

A common struggle with returning raw pointers from functions is that it isn’t clear who is responsible for freeing the memory - the caller or the callee? Usually programmers will try to clarify this in variable names, comments, or docs. But with smart pointers, the transfer of ownership can be captured in the type.

If you want to delete the memory prematurely (i.e. before the pointer goes out of scope) you can do so with reset():

unique_ptr<int> i = make_unique<int>(3);
i.reset();
// i's memory is cleared before it goes out of scope

Shared pointers

So far we have only talked about exclusive ownership of pointers. If you want multiple owners of the same pointer, you can use a shared_ptr.

shared_ptr<int> i = make_shared<int>(4); // ref count = 1
shared_ptr<int> j = i;                   // ref count = 2

Unlike a unique pointer, a shared pointer does not free its memory once it is out of scope, since there can still be active users. Instead, memory is freed when there are no users remaining, i.e. its reference count reaches zero.

void create_owners(shared_ptr<int> ptr) {
    shared_ptr<int> owner2 = ptr; // 2: ref count = 2
    shared_ptr<int> owner3 = ptr; // 3: ref count = 3
}
// 4: out of scope, so owner2 and owner3 are freed; ref count = 1

int main() {
    shared_ptr<int> owner1 = make_shared<int>(4); // 1: ref count initialized to 1
    create_owners(owner1);
    cout << *owner1 << endl; // 5: still accessible
    return 0;
}
// 6: owner1 out of scope, ref count = 0 and memory is freed

Circular references

A problem with reference counting memory management is that it cannot deal with cycles. If two objects contain pointers to each other, neither can be freed due to the other’s presence.

class B; // forward declaration

class A {
    public:
        A() {
            cout << "calling A()\n";
        }
        ~A() {
            cout << "calling ~A()\n";
        }
        void create_ptr(shared_ptr<B> b) {
            ptr_to_B = b;
        }
    private:
        shared_ptr<B> ptr_to_B;
};

class B {
    public:
        B() {
            cout << "calling B()\n";
        }
        ~B() {
            cout << "calling ~B()\n";
        }
        void create_ptr(shared_ptr<A> a) {
            ptr_to_A = a;
        }
    private:
        shared_ptr<A> ptr_to_A;
};

int main() {
    shared_ptr<A> a = make_shared<A>();
    shared_ptr<B> b = make_shared<B>();
    a->create_ptr(b);
    b->create_ptr(a);
    return 0;
}
// output:
// calling A
// calling B

In the above example, both a and b have a pointer to each other, so neither’s destructor is called.

Weak pointers

A weak pointer can be used to break circular references. A weak pointer is just like a shared pointer, except it does not contribute to the reference count. In other words, the presence of weak pointers is not enough to keep the memory around.

If we change A’s pointer to B to be a weak pointer instead:

@@ -1 +1 @@
-shared_ptr<B> ptr_to_B;
+weak_ptr<B> ptr_to_B;

We now see the destructors called:

// output:
// calling A()
// calling B()
// calling ~B()
// calling ~A()

When the main function goes out of scope, b is freed despite a having a pointer to it, since the pointer is a weak pointer. a is then freed since both its owners are out of scope.

Lvalues, rvalues, and move semantics in C++

Sun, 31 Aug 2025 00:00:00 +0000

I’ve written a decent amount of C++, but never really took the time to understand its internals. In the first of what will hopefully become a series of articles, we will look at lvalues, rvalues, and move semantics. This turns out to be a crucial part of the language and understanding it will greatly help you reason about the performance of your program.

Lvalues and rvalues

C++ has a distinction between lvalues and rvalues. A lvalue is something that has a long-term memory location, i.e. it is stored somewhere on the stack or the heap. You can expect that others will try to access and modify it.

int i = 0; // i is a lvalue

An rvalue, on the other hand, is a temporary value stored in a register and used for intermediate calculations. These don’t have a long-term memory location.

int add_one(int num) {
    return num + 1;
}
add_one(1); // 1 here is a rvalue

As such, lvalues are usually on the left side of an expression, and rvalues are usually on the right, hence their naming.

You can take the address of a lvalue, since again, it has a long-term memory location.

int num = 20;
int *ptr = &num;

Conversely, you cannot take the address of a rvalue.

int *ptr = &20; // error

Similarly, you can take a reference to a lvalue, but not a rvalue.

int num = 20;
int &ref = num; // ok
int &ref = 20;  // error

It sort of makes sense if you think about it. It’s a bit weird to take a reference to a temporary variable stored in some register. It’s meant to be used once and then discarded, and the content of that register is expected to change anytime, invalidating your reference.

Another way to think about it is that when you take a reference to a rvalue, you are trying to convert a rvalue into a lvalue, and then taking a reference to it, a practice that C++ forbids. On the other hand, you can convert a lvalue into a rvalue. When you do something like int j = i + 2, i, a lvalue, is implicitly converted into a rvalue, since the + operation takes two rvalues and returns a rvalue. An easy way to remember this is that it’s easy to move something in a permanent location to a temporary location (lvalue to rvalue conversion), but much harder to move a temporary object into a permanent location (rvalue to lvalue conversion).

Actually I may have lied a bit - the whole distinction between how lvalues and rvalues are stored (register vs stack/heap) isn’t totally true. The C++ spec doesn’t make any such restrictions on how variables are stored in memory; if the compiler sees that a variable is only used temporarily, it is free to move it to a register, so long as it doesn’t change the observable behavior of the program. Nonetheless, I think it’s helpful to differentiate between “short-term” temporaries and “long-term” memory locations.

However, what if you wanted to pass in temporary values to functions that won’t modify the underlying values? It would be annoying to have to convert the rvalue into a lvalue everytime you need to pass some read-only object into a function. As a result, C++ does allow you to take a const reference to a rvalue. Under the hood, the compiler will create a implicit temporary lvalue from your rvalue before passing it into your function, but it saves the programmer a headache each time.

// error
void do_nothing1(int &num) {
    return;
}
do_nothing1(1);

// ok
void do_nothing2(const int &num) {
    return;
}
do_nothing2(1);

One important thing to note about const lvalue references to rvalues is that their lifetime extends past the underlying rvalue they point to. Below is an example to illustrate this point.

const int &ref = 20;                      // 1
std::cout << "ref: " << ref << std::endl; // 2

Usually, a reference is valid only as long as the object it points to, so the example would introduce a dangling pointer. In this case, the lifetime of the rvalue 20 is the length of the expression it is in, i.e. the right hand side of line 1. However, since we have a const lvalue reference to it, its lifetime is now extended to when that reference expires.

So to summarize:

You can take a non-const lvalue reference to a lvalue but not a rvalue
However, you can take a const lvalue reference to a rvalue
(You can also take a const lvalue reference to a lvalue)
When you take a const lvalue reference to a temporary rvalue, the rvalue’s lifetime is extended to match that of the reference

Rvalue references

Turns out you can take references to temporaries (rvalues) as well. Let’s motivate this with an example. Suppose we want to implement a dynamic array of integers, one that automatically resizes when it reaches capacity. Since its size is not known at compile-time, we will need to allocate it on the heap via the new keyword in the constructor. We will also initialize the elements to 0 by default, with an optional argument init to change it. In the destructor, we will call delete on the memory.

class DynamicArray {
    public:
        // constructor
        DynamicArray(int init=0, size_t sz=10) {
            m_nums = new int[sz];
            for (int i = 0; i < sz; ++i) {
                m_nums[i] = init;
            }
            m_sz = sz;
        }
        // destructor
        ~DynamicArray() {
            delete[] m_nums;
        }
    private:
        int *m_nums;
        int init;
        size_t m_sz;
}

What should happen when we want to copy an existing DynamicArray object to an uninitialized object? For example:

DynamicArray d1(1, 10);
DynamicArray d2 = d1;

We need to 1. dynamically allocate memory for the new object and 2. copy the data from the old object to the new object, which is what we will do in our copy constructor.

// copy constructor
DynamicArray(const DynamicArray &that) {
    m_nums = new int[that.m_sz];
    std::memcpy(m_nums, that.m_nums, that.m_sz * sizeof(int));
    m_sz = that.m_sz;
}

On the other hand, what if we have an initialized object and we want to replace its contents with another initialized object?

DynamicArray d3(3, 10);
DynamicArray d4(4, 10);
d3 = d4;

This is what the assignment operator does: it needs to 1. delete the old object’s memory 2. re-allocate it with new, then 3. copy the new object’s data into the old object’s memory. As a slight optimization, note that we only need to delete and re-allocate if the new object and old object’s arrays are of different sizes. If they are the same, we can reuse the same memory and avoid an additional allocation.

// assignment
DynamicArray &operator=(const DynamicArray &that) {
    // prevent self-assignment
    if (this == &that) return *this;

    // if same size, then reuse memory
    if (m_sz == that.m_sz) {
        std::memcpy(m_nums, that.m_nums, that.m_sz * sizeof(int));
    } else {
        delete[] m_nums;
        m_nums = new int[that.m_sz];
        std::memcpy(m_nums, that.m_nums, that.m_sz * sizeof(int));
        m_sz = that.m_sz;
    }
    return *this;
}

Everything so far works as expected, but observe that the right-hand side of both our copy and assignment calls are lvalues.

// copy
DynamicArray d1(1, 10);
DynamicArray d2 = d1;

// assignment
DynamicArray d3(3, 10);
DynamicArray d4(4, 10);
d3 = d4;

Hence it makes sense that we need to make separate copies of memory - the lvalue is stored in a long-term memory location on the stack or heap and may be used by other entities. But what happens when the right hand side of our expressions consists of rvalues?

// copy
DynamicArray d2 = DynamicArray(1, 10);

// assignment
DynamicArray d3(3, 10);
d3 =  DynamicArray(4, 10);

The exact same thing happens! For the copy call, we allocate memory for d2 and copy the rvalue’s data into it. For the assignment call, we delete d3’s memory, re-allocate it with a new size, and copy the rvalue’s data into it. In other words, we aren’t taking advantage of the fact that the thing we’re copying from is a temporary, and thus will not be around beyond the expression it’s contained in.

This is where rvalue references come into play. An rvalue reference is denoted with two amperands (&&). Instead of having the compiler implicitly convert the rvalue into a lvalue and invoke the expensive copy/assignment operators, we take in references to the rvalues and simply change our internal structures to point to them. This idea allows us to implement what’s called move semantics - we’re moving objects around as opposed to copying them.

// move constructor
DynamicArray(DynamicArray &&that) {
    // just change a couple pointers!
    m_nums = that.m_nums;
    m_sz = that.m_sz;

    // invalidate the rvalue
    that.m_nums = nullptr;
    that.m_sz = 0;
}

// move assignment
DynamicArray &operator=(DynamicArray &&that) {
    if (this == &that) return *this;
    delete[] m_nums;
    // same thing here: no deep copying; just a couple assignments
    m_nums = that.m_nums;
    m_sz = that.m_sz;

    // invalidate rvalue
    that.m_nums = nullptr;
    that.m_sz = 0;
    return *this;
}

Now, whenever we invoke the copy or assignment operators, we no longer make a separate allocation and do a copy; we simply reuse the existing allocation.

This seems like a lot of complication for what seems like a trivial issue. But in general, you can assume the new and delete functions always come with extreme overhead. If you think about it, whenever you call new, the allocator has to search through the entire heap space to find a contiguous chunk of memory large enough to fit your data. When blocks are freed, it also has to perform coalescing between adjacent free blocks and compaction to avoid external fragmentation.

Recap

To recap what we learned so far:

Lvalues are usually on the left-hand side of an expression, and have a long-term memory location
Rvalues are usually on the right-hand side of an expression, and are stored temporarily in a register
You can take the address of a lvalue, but not of a rvalue, since it does not have a long-term memory location
You cannot bind a non-const lvalue reference to a rvalue
You can, however, take a rvalue reference to a rvalue, which allows us to implement move semantics and avoid additional memory allocations and copies, which you should assume are slow

References

How to fight the attention economy

Sat, 30 Aug 2025 00:00:00 +0000

If you’ve ever been to a casino, you’ll notice that there are no clocks, no windows, and no straight angles. Ugly carpet patterns keep your eyes forward as you wander through curved hallways, your gaze fought over by the endless glow of slot machines. These design peculiarities are not accidental, but deliberately chosen to keep you in a prolonged state of mindlessness.

The Internet today pretty much operates in the same way. Auto-playing reels, bright red notification bubbles, and an infinite algorithmic feed, all meticulously engineered to maximize your engagement. But the difference between Big Internet and Big Casino is that the former isn’t vying for your money, but an arguably much more precious resource - your attention.

Luckily, there are ways to take back our attention from the criminal entities trying to steal it from us. Below I will share five tips that have worked for me so far, but your mileage may vary.

1. Make yourself busy

I’ve had friends suggest apps that set time limits for each app, but I never found them useful or convincing. Presumably if you’re choosing to spend time on your phone, a simple reminder isn’t going to stop it. But if you have other obligations that take time out of your day, by elementary arithmetic that means you have less time doomscrolling.

Once I started making more plans with friends, developed a weekly running schedule, and picked up photography, I naturally lost the time and will to be on my phone all day.

2. Consume long-form content

To me, what constitutes “long-form content” has less to do with its length and more to do with how much mental work it takes to consume it. Usually this includes books, podcasts, and articles, but a well-written social media post on a deep subject matter can be equally effective. Consuming more long-form content not only helps your attention span, but you will find them so fulfulling that you won’t want to go back to those silly cat videos anymore.

3. Browser > app

Use everything from your browser. Literally, delete all your apps - Starbucks, Facebook, Bluesky, and the rest of them. If you need to use Instagram, for instance, open your browser, type in “www.instagram.com”, then enter your username and password. When you’re done, clear your current session.

I recommend Firefox Focus or the DuckDuckGo browser, since both allow you to easily erase all your data whenever you’re done with your current browsing session.

Doing this helps you become more intentional about using social media and prevents you from subconsciously opening your apps whenever you’re bored. As a side benefit, you’ll notice that UIs are less responsive in the browser. Lots of features like pop-ups, auto-playing videos, and animations don’t work, making the whole experience much less addictive.

4. Disable biometrics and use a long password

Disable biometrics - face ID, touch ID, and whatever else is out there. Use a 20-character passphrase with special symbols. This will make unlocking your phone more difficult. Furthermore, if you get arrested, usually law enforcement can force you to unlock your phone via biometrics, but if they ask for your password, all you have to do is stay silent.

5. Spend more time outdoors

Spending time in nature is both physically and mentally therapeutic. It can aid our attention span and calm our nervous system. Furthermore, with total ecological collapse at our feet, who knows when the next time you’ll be able to climb that mountain or see a turtle?

Parser combinators for postal addresses

Fri, 04 Jul 2025 00:00:00 +0000

A while ago, Tsoding did a stream on parsing JSON with parser combinators. I was curious how hard it would be to use the basic parsers he implemented to create a new parser for U.S. postal addresses. It turns out once you have basic building blocks, creating new parsers is not only easy, but fun! You can find the full code here.

I recommend watching the video first, but if you want a dumbed down introduction to parser combinators, read on.

What’s a postal address?

To keep things simple, we will be working with a simplified version of this Wikipedia BNF example.

<postal-address> ::= <name-part> <street-address> <zip-part>

    <name-part> ::= <first-name> <last-name> <opt-suffix-part> <EOL> |

        <opt-suffix-part> ::= "Sr." | "Jr." | ""

    <street-address> ::= <house-num> <street-name> <apt-num> <EOL>

    <zip-part> ::= <town-name> "," <state-code> <ZIP-code> <EOL>

An address consists of three parts: a name part, a street address, and a zip part. Each part can take on multiple forms; for example, a name part can optionally have a suffix at the end. We would like to parse a string representing a postal address into a tree, where each node represents each component.

For this simple example, using parser combinators is probably an overkill, as you can probably just brute-force parse it in Python. However, as the postal address format changes and grows, we’re going to want a more scalable approach that can adapt to these changes. And as you will see by the end, parser combinators provide a clean abstraction that lets you easily build new parsers on top of existing ones. You’ll also realize that functional programming can actually be useful and isn’t just a pretentious cult!

Parsing characters and strings

The core idea of combinator parsing is to 1. define basic parsers as our building blocks and 2. define the operations on those parsers such that they can combine with each other in various ways.

First, let’s translate the BNF from the previous section to code.

-- final address
data PostalAddress =
  PostalAddress NamePart StreetAddress ZipPart deriving (Show, Eq)
-- name part
data NamePart =
  NamePartBasic FirstName LastName |
  NamePartWithSuffix FirstName LastName SuffixPart deriving (Show, Eq)
data FirstName =
  FirstName String deriving (Show, Eq)
data LastName =
  LastName String deriving (Show, Eq)
data SuffixPart =
  SuffixPart String deriving (Show, Eq)
-- address part
data StreetAddress =
  StreetAddress HouseNum StreetName AptNum deriving (Show, Eq)
data HouseNum =
  HouseNum String deriving (Show, Eq)
data StreetName =
  StreetName String deriving (Show, Eq)
-- zip part
data ZipPart =
  ZipPart TownName StateCode ZipCode deriving (Show, Eq)
data TownName =
  TownName String deriving (Show, Eq)
data StateCode =
  StateCode String deriving (Show, Eq)
data ZipCode =
  ZipCode String deriving (Show, Eq)
data AptNum =
  AptNum String deriving (Show, Eq)

We can then define our parser.

data Parser a = Parser {
  runParser :: String -> Maybe (a, String)
}

which is a datatype with a single field runParser. You can see that it takes a string to parse, and returns a Maybe of something of type a that it parsed, along with the remainder of the string that it didn’t parse. The remaining string can be fed as input into other parsers to continue parsing.

A couple notes on this weird syntax. Haskell actually creates a method named runParser that has signature

ghci> :t runParser
runParser :: Parser a -> String -> Maybe (a, String)

So you can supply the parser to it and it’ll return the function field, much like accessing a field name of a struct in other languages. This is why we named it runParser rather than something like parsingFunction, since runParser gives us the function of type String -> Maybe(a, String), which we can run directly by providing the string argument!

To make this more concrete, let’s create our first parser for the Char type. To do this, we’ll first want a function that take any character c and generate a parser for c.

charParserG :: Char -> Parser Char
charParserG c = Parser f
  where
    f (x:xs)
      | x == c = Just (x, xs)
      | otherwise = Nothing
    f [] = Nothing

We can use this to create a parser for the letter 'h' for instance, and use it to parse "hello".

ghci> runParser (charParserG 'h') "hello"
Just ('h',"ello")

As expected, it parsed the letter 'h' and left the rest of the string untouched.

How would we parse a string? We could do something similar to charParserG, but instead of looking at a single character, we try to match an entire string.

substr :: Int -> Int -> String -> String
substr start end s = take (end - start) (drop start s)

stringParserGDumb :: String -> Parser String
stringParserGDumb s = Parser f
  where
    f (x)
      | isPrefixOf s x = Just(x, substr (length s) (length x) x)
      | otherwise = Nothing

This works fine, but there is a lot of boilerplate code. What if I told you we could combine many charParserG’s to create a stringParserG?

After all, a string is simply a list of characters. As a first attempt, we can try to call the map function, but unfortunately the result is of the wrong type.

ghci> :t map charParserG "hello"
map charParserG "hello" :: [Parser Char]

That is, it gives us a list of char parsers, but what we want is a parser of a list of chars. So we need to somehow flip the parser inside out. Luckily, there is a function that does exactly this.

ghci> :info sequenceA
type Traversable :: (* -> *) -> Constraint
class (Functor t, Foldable t) => Traversable t where
  ...
  sequenceA :: Applicative f => t (f a) -> f (t a)
  ...
  	-- Defined in ‘Data.Traversable’

sequenceA however, is defined in the Functor interface which mean we need to implement that for our Parser type before we can use it.

Functor

To implement a functor, we need to define the operator fmap, or <$>, which has the following signature.

fmap :: (a -> b) -> f a -> f b

It takes two arguments: a function mapping a -> b and a value f a, which is something of type a wrapped in some container f. It then unwraps the f a value, runs the function on the a to get a b, then rewraps it, finally returning f b.

This is much easier to understand through an example. Let’s say we have a Maybe of an Int, and we want to double the value inside it and return another Maybe type. Since the Maybe type is a functor, we can simply call the fmap operator.

ghci> (\i -> i * 2) <$> (Just 2)
Just 4

Much better than manually unwrapping the Maybe and doing the repackaging ourselves! This is a trivial example but you can imagine much more complicated versions of f with a lot of hidden state that would be impractical to handle manually.

So for our parser, given a function and parserA, we need to apply the function to the output of parserA and return a new parser parserB.

instance Functor Parser where
  -- fmap :: (a -> b) -> Parser a -> Parser b
  fmap f parserA =
    Parser $ \s ->
      case runParser parserA s of
        Nothing -> Nothing
        Just (a, as) -> Just (f a, as)

As an example, we can easily map the function toUpper to our parser for 'h'.

ghci> runParser (toUpper <$> (charParserG 'h')) "hello"
Just ('H',"ello")

Now that Parser is a functor, implementing stringParserG is a two-line endeavor:

stringParserG :: String -> Parser String
stringParserG = sequenceA . map charParserG

It works!

ghci> runParser (stringParserG "hello") "hello world!!"
Just ("hello"," world!!")

If we go back to our postal address discussion and try to parse something simple like a FirstName, we run into an issue: that is, our stringParserG function can only generate parsers for specific strings. But a first name can be any string given some condition, such as that containing only letters in the alphabet. This means we need another function that can generate a string parser for some condition.

Luckily, there is a function called span defined in GHC.List that does just this! It takes a string and a boolean function and returns a tuple of two elements: everything it could greedily match and the rest of the string.

ghci> span isAlpha "hello world 123"
("hello"," world 123")

We can now create a function that takes in a condition and returns a parser that parses not specific strings, but any string that satisfies that condition.

spanParserG :: (Char -> Bool) -> Parser String
spanParserG f = Parser $ \s ->
  let (token, rest) = span f s
    in Just(token, rest)

Now we can write a parser that parses string literals by supplying it the isAlpha function:

stringLiteralParser :: Parser String
stringLiteralParser = spanParserG isAlpha

And one that parses digits using the isDigit function:

numberParser :: Parser String
numberParser = spanParserG isDigit

Using the fmap operator we defined earlier for our functor, we can now create a parser for FirstName.

firstNameParser :: Parser FirstName
firstNameParser = FirstName <$> stringLiteralParser

Doing the same for LastName:

lastNameParser :: Parser LastName
lastNameParser = LastName <$> stringLiteralParser

We can try to write a parser for SuffixPart but there is another problem. Recall that a suffix can be either “Sr.” or “Jr.” so we’ll need a way to apply the “or” operator on two parsers, such that we return the first match that succeeds. Then we can write a parser for “Sr.” and a parser for “Jr.” and then glue them together.

This can be done with the <|> operator, defined in yet another interface, the Alternative. But to implement Alternative, we must first implement the Applicative interface. So once again, we’re going to take a detour into some PL theory.

Applicative

An applicative has these two operations:

pure :: a -> f a 
(<*>) :: f (a -> b) -> f a -> f b

pure simply wraps some primitive type a inside our container f. The <*> operator looks similar to <$> in its type signature, but notice that in this case, the function is also wrapped inside the container!

We use it like this:

ghci> (Just toUpper) <*> (Just 'h')
Just 'H'

The applicative implementation is similar to what we did for our functor, except we also need to “unwrap” the container wrapping the function. In this context, unwrapping our container means running the parser!

instance Applicative Parser where
  -- pure :: a -> Parser a
  pure a = Parser $ \s -> Just (a, s)

  -- <*> :: Parser (a -> b) -> Parser a -> Parser b
  parserF <*> parserA = Parser $ \s ->
    case runParser parserF s of
      Nothing -> Nothing
      Just (f, fs) ->
        case runParser parserA fs of
          Nothing -> Nothing
          Just (a, as) -> Just (f a, as)

Alternative

Now that our parser is an applicative, we can continue on to implement Alternative. In this case, we need the empty operator and the <|> operator, which we will use as a “or” function combining our parsers.

To implement the <|> operator, we need to parse our string with the first parser, and depending on the results, potentially run it through the second parser.

instance Alternative Parser where
  -- empty :: f a
  empty = Parser (\s -> Nothing)

  -- (<|>) :: f a -> f a -> f a
  parserA <|> parserB = Parser $ \s ->
    case runParser parserA s of
      Just (a, as) -> Just (a, as)
      Nothing -> case runParser parserB s of
        Just (b, bs) -> Just (b, bs)
        Nothing -> Nothing

Now that our Parser is both an Applicative and an Alternative, we can write our suffix parser.

suffixPartParser :: Parser SuffixPart
suffixPartParser = SuffixPart <$> ((stringParserG "Jr.") <|> (stringParserG "Sr."))

Remember that a NamePart can optionally have a suffix. So our final parser has to look something like this:

namePartParser :: Parser NamePart
namePartParser = namePartWithSuffixParser <|> namePartBasicParser

which tries to match the name part with a suffix, but if it fails falls back to a basic name.

How do we implement namePartWithSuffixParser and namePartBasicParser? For these, we now need to run a sequence of parsers on some input string, each parser parsing the remainder of the input string left behind by its preceding parser. To do this, we need the “bind” operator, or >>= defined in the Monad interface.

ghci> :info >>=
type Monad :: (* -> *) -> Constraint
class Applicative m => Monad m where
  (>>=) :: m a -> (a -> m b) -> m b
  ...
  	-- Defined in ‘GHC.Base’
infixl 1 >>=

So before we can finish our parser, we need to do one last task, which is to implement the Monad interface. But once we have this, the rest will be smooth sailing.

Monad

Simply enough, to implement >>=, we just run the first parser on the input, take the Maybe result and run the second parser on the rest of the input.

instance Monad Parser where
  -- >>= :: (Parser a) -> (a -> Parser b) -> (Parser b)
  parser >>= f = Parser $ \s ->
    case runParser parser s of
      Nothing -> Nothing
      Just (a, as) -> runParser (f a) as

Consider the following parser that parses "good".

ghci> runParser (stringParserG "good") "goodbye"
Just ("good","bye")

If we want to do the same thing but additionally thread the remaining string, i.e. "bye", into another parser that consumes "bye", we can!

ghci> runParser ((stringParserG "good") >>= (\s -> stringParserG "bye")) "goodbye"
Just ("bye","")

Implementing our parser

The hard part is done! Now we can implement a parser for basic names and a parser for names with suffixes. To do this, we can make use of the do notation for monads and call the smaller parsers we implemented earlier, i.e. firstNameParser, lastNameParser, and suffixPartParser. Then finally, we can <|> the two parsers together.

namePartBasicParser :: Parser NamePart
namePartBasicParser = do
  fst <- firstNameParser <* charParserG ' '
  snd <- lastNameParser
  pure $ NamePartBasic fst snd

namePartWithSuffixParser :: Parser NamePart
namePartWithSuffixParser = do
  fst <- firstNameParser <* charParserG ' '
  snd <- lastNameParser <* charParserG ' '
  thrd <- suffixPartParser
  pure $ NamePartWithSuffix fst snd thrd

namePartParser :: Parser NamePart
namePartParser = namePartWithSuffixParser <|> namePartBasicParser 

Note the <* operator defined in the Applicative interface. It sequentially applies two parsers, but only returns the result of the first. As an example, if we want to parse "good night" followed by an exclamation point, but only want the string "good night" to be captured, we can do something like:

ghci> runParser ( stringParserG "good night" <* charParserG '!') "good night!"
Just ("good night","")

Next, parsing the address part of the postal address should look familiar.

houseNumParser :: Parser HouseNum
houseNumParser = HouseNum <$> numberParser

streetNameParser :: Parser StreetName
streetNameParser = StreetName <$> (stringLiteralParser <* stringParserG " St")

aptNumParser :: Parser AptNum
aptNumParser = AptNum <$> ((stringParserG "Apt ") *> numberParser)

streetAddressParser :: Parser StreetAddress
streetAddressParser = do
  houseNum <- houseNumParser <* charParserG ' '
  streetName <- streetNameParser <* charParserG ' '
  aptNum <- aptNumParser
  pure $ StreetAddress houseNum streetName aptNum

Then lastly, the zip portion of the address:

townNameParser :: Parser TownName
townNameParser = TownName <$> stringLiteralParser

-- only the West Coast exists
stateCodeParser :: Parser StateCode
stateCodeParser = StateCode <$>
  (stringParserG "WA" <|>
    stringParserG "CA" <|>
    stringParserG "OR" <|>
    stringParserG "AR" <|>
    stringParserG "HI")

zipCodeParser :: Parser ZipCode
zipCodeParser = ZipCode <$> numberParser

zipPartParser = do
  town <- townNameParser <* charParserG ','
  state <- stateCodeParser <* charParserG ' '
  zip <- zipCodeParser
  pure $ ZipPart town state zip

The final step is to create postal address parser by combining the name, address, and zip parsers!

postalAddressParser :: Parser PostalAddress
postalAddressParser = do
  namePart <- namePartParser <* charParserG '\n'
  streetAddress <- streetAddressParser <* charParserG '\n'
  zipPart <- zipPartParser
  pure $ PostalAddress namePart streetAddress zipPart

We can test this on a couple examples:

ghci> -- test case 1
ghci> runParser postalAddressParser "Linus Torvalds Jr.\n1538 John St Apt 550\nSeattle,WA 98702"
Just (PostalAddress (NamePartWithSuffix (FirstName "Linus") (LastName "Torvalds") (SuffixPart "Jr.")) (StreetAddress (HouseNum "1538") (StreetName "John") (AptNum "550")) (ZipPart (TownName "Seattle") (StateCode "WA") (ZipCode "98702")),"")
ghci> -- test case 2
ghci> runParser postalAddressParser "Grace Hopper\n528 Madison St Apt 702\nFremont,CA 78771"
Just (PostalAddress (NamePartBasic (FirstName "Grace") (LastName "Hopper")) (StreetAddress (HouseNum "528") (StreetName "Madison") (AptNum "702")) (ZipPart (TownName "Fremont") (StateCode "CA") (ZipCode "78771")),"")

These are admittedly pretty simple examples but you can easily build on this to create more complicated parsers to deal with your favorite edge cases.

Summary

To recap, parser combinators are powerful abstractions that allow you to combine small, simple parsers in different ways in order to build larger, more complicated parsers. We started with a simple parser that can parse a single character, then built more parsers on top of that to parse strings, numbers, names, street names, zip codes, and finally, entire postal addresses. To do this, we implemented various interfaces for our Parser type, including Functor, Applicative, Alternative, and Monad, each of which gave us some unique operator we used to glue our various parsers together.

For more on parser combinators, I recommend this list of resources:

And if you really must, a more formal paper discussing this:

Monadic Parser Combinators

Attention as a kernel smoothing problem

Fri, 23 May 2025 00:00:00 +0000

Reddit discussion

This post is about a rarely discussed interpretation of “attention,” the underlying technique behind transformers, which has found its way into everything from natural language processing to computer vision. Namely: attention can be viewed as a kernel smoothing problem for estimating a function given surrounding observations.

This is by no means an original observation, and has already been covered in, for example, Tsai et. al or Song et. al. But it is still surprisingly absent from any material you can find online explaining this subject. More than anything, I think viewing attention through this lens gave me the clearest conceptual understanding of what attention is really doing.

Attention

To recap, the idea of attention is as follows. We have an input sequence of vectors $<x_1, x_2, ...,x_n>$ and an output sequence of vectors $<y_1, y_2, ..., y_m>$, and we want these vectors to somehow encode information about one another. Perhaps we’re doing machine translation, where the input sequence represents words in English, and the output sequence represents words in Korean. We want the English and Korean words to somehow absorb context from surrounding words in their sequence, a.k.a. “self attention.” We also the Korean words to derive meaning from English words across the pond, referred to as “cross attention.”

We can formulate this as a deep learning problem. To do this, we divide this process into two stages: the encoder, which processes the input sequence, and the decoder, which processes the output sequence, each with its own learnable weight parameters. This is then repeated a large number of times until some cost function is sufficiently small, at which point each vector will have learned its surrounding context.

The way we get these vectors to “talk” to each other is by projecting each vector onto three separate subspaces; these new vectors are known as the “query,” the “key,” and the “value.”

This projection is done by left-multiplying the original vectors $x_1, ... , x_n$ by learnable weight matrices, $W_Q$, $W_K$, and $W_V$.

\[\begin{align} q_i &= x_{Qi}W_Q\\ k_i &= x_{Ki}W_K\\ v_i &= x_{Vi}W_V\\ \end{align}\]

where $x_{Qi} = x_{Ki} = x_{Vi}$ for self-attention. In cross-attention, $x_Q$ comes from the decoder side while $x_K$ and $x_V$ comes from the encoder side.

One way to intuit this is to view the query as a database query, and the keys and values as the entries stored in the database. We can match the query with each key and return a similarity measure where higher means a “better match.” Then, rather than returning a discrete set of results that “match,” we instead return a distribution of results, where each result is weighed by the similarity measure. That is, $similarity(query, key) \times value$.

To formalize this: for each query $q_i$, key $k_i$ and value $v_i$, we define attention as

\[\begin{align} \tag{1.1} attention(q_i, k_i, v_i) = softmax(\frac{q_ik_i^T}{\sqrt{d_k}})v_i \end{align}\]

where $d_k$ is some stabalization term needed for numerical stability.

To calculate how well our query associates with all possible key/value pairs, we can pack all the keys into a matrix $K$ and the values into a matrix $V$. Then, we get a condensed representation

\[\begin{align} \tag{1.2} attention(q_i, K, V) = softmax(\frac{q_iK^T}{\sqrt{d_k}})V \end{align}\]

The result of the softmax is a probability distribution where each column $j$ measures the interaction between $q_i$ and $k_j$. This is used to weigh each value $v_j$.

Multi-headed attention

This, however, only uses one set of learnable weight parameters, namely $(W_Q, W_K, W_V)$. Ideally, we want to train multiple weights for each query, key and value so that they can all influence each other in different ways. This will give us a set of $h$ queries, keys, and values.

\[\begin{align} Q_i &= W_{Qi}Q\\ K_i &= W_{Ki}K\\ V_i &= W_{Vi}V\\ \end{align}\]

for $i = 1, 2, ..., h$. With $h$ queries, keys, and vectors, we can then calculate $h$ attention heads:

\[\begin{align} head_i = attention(Q_i, K_i, V_i) \end{align}\]

Usually the dimension of the new weights will be some fraction of the dimension of our original vectors, for example $d_{model} / h$. We can then stack them all together horizontally:

\[\begin{align} attention = horzcat(head_1, ..., head_h)W_O \end{align}\]

(Don’t worry about what $W_O$ is for now; it isn’t particularly important.)

Since each head is of dimension $n \times d_{model} / h$, stacking them horizontally gives us a matrix of dimension $n \times d_{model}$, equivalent to our previous single-headed attention. The benefit of using multiple, smaller weight matrices instead of a single large one is that it lets us capture a more diverse set of interactions.

This is the basics of the so-called attention mechanism popularized by the 2017 paper Attention Is All You Need.

Kernel smoothing

Suppose we have a set of points $(x_1, y_1), (x_2, y_2), ..., (x_n, y_n)$ and an observation $x_o$, and we want to predict what the corresponding $y$ would be, i.e. $\hat{y}(x_o)$

One way to do this is to identify the $k$ closest points to $x_o$, i.e. $x^\prime_1,...,x^\prime_k$ and average up their $y$ values. More formally:

\[\hat{y}(x_o) = \frac{1}{k} \sum_{i=1}^{k}{y^{\prime}_i}\]

But this doesn’t take into account the closeness of each $x^\prime_i$ to $x_o$. Thus, we introduce a similarity measure $K(x_1, x_2)$ that is maximized when $x_1 = x_2$ and use it to weigh each point. This similarity measure is known as the kernel, and there are many ways to define it, each with different tradeoffs. Our expression then becomes:

\[\tag{2} \hat{y}(x_o) = \sum_{i=1}^{n} \frac{K(x_o, x_i)y_i}{\sum_{i=1}^{n}{K(x_o, x_i)}}\]

Note that we no longer have to pick out $k$ points; we can just use all $n$ points and the similarity function should take care of eliminating unrelated points by decaying their weights towards zero.

Attention as a kernel smoother

What does kernel smoothing have to do with attention? It turns out that with a little derivation, the attention mechanism can be reformulated as a kernel smoothing problem!

Let’s revisit an attention interaction between a single query, key and value.

\[\begin{align} attention(q_i, k_j, v_j) &= softmax(\frac{q_ik_j^T}{\sqrt{d_k}})v_j\\ &= \frac{exp(q_ik_j^T/\sqrt{d_k})}{\sum_{j=1}^nexp(q_ik_j^T/\sqrt{d_k})}v_j\\ \end{align}\]

Letting $K(q, k) = exp(qk^T / \sqrt{d_k})$ we get

\[\begin{align} \tag{3} attention(q_i, k_j, v_j) &= \frac{K(q_i, k_j)v_j}{\sum_{l=1}^{n}{K(q_i, k_l)}} \end{align}\]

Observe that this takes on a similar form to the kernel smoothing equation in (2)! In particular, the “query” is the $x_o$, the “keys” are the $x_i$’s and the “values” are the $y_i$’s (albeit with an additional linear transformation). And lastly, the exponential function of the query-key dot product divided by the stabalization term is the kernel.

With this realization, multi-headed attention with $h$ heads can be reduced to combining $h$ different kernel smoothers!

One final thing to point out is that our specific kernel is an example of a non-symmetric kernel, i.e. $K(a, b) \ne K(b, a)$, due to the fact that we apply different linear mappings for the queries and for the keys. This can be more clearly seen if rewritten as a function of the input vectors $x$:

\[\begin{align} K(x_q, x_k) = exp((x_qW_Q)(x_kW_K) / \sqrt{d_k}) \end{align}\]

With a bit of thought, this should make sense, since the ways two words influence each other in a sentence shouldn’t necessarily be identical.

Summary

In summary, attention can be seen as a kind of kernel smoother with a special non-symmetric kernel. The way we get a word to absorb contexual information from its neighboring words is by calculating its interaction with each neighbor and then weighing it by a relevance score, akin to how kernel smoothing approximates a function at a given point by calculating a weighted average of its surrounding points.

Combining Futures and Options in Scala

Wed, 19 Mar 2025 00:00:00 +0000

In Scala, two interesting concepts you’ll often work with are Futures and Options. A Future is an abstraction for some value that might not be available yet. An Option abstracts over the possibility of a value.

Both Futures and Options are monads, meaning you can chain them together without explicitly unwrapping them. More formally, every monad F[A] has the following three operations [¹]:

map[B](f: A => B): F[B]
flatMap[B](f: A => F[B]): F[B]
pure(x: A) => F[A]

With these, you can easily combine Futures and Options. As a dummy example:

Future("hello").map(_ + " world").flatMap(x => Future(Some(x)))
// returns Future(Success(Some(hello world)))

However, what if you had a Future of an Option, i.e. Future[Option[A]]? Perhaps a potentially long-running database fetch.

def getUserIdOptF: Future[Option[String]] = {
    // ...some potentially long running database fetch...
}
def getSSNOptF(s: String): Future[Option[String]] = {
    // ...get ssn if it exists...
}

Your code would unfortunately become more verbose:

getUserIdOptF.flatMap(_.map(num => getSSNOptF(num)).getOrElse(Future(None)))

Explanation: the map() call returns a Option[Future[Option[A]]] so we need the extra getOrElse() call so that the function passed to flatMap() obeys its signature, i.e. it returns a Future[Option[A]]. This seems rather cumbersome, especially if many your methods share the same pattern of returning a Future[Option[A]].

To reduce the boilerplate, we can instead make Future[Option[A]] itself a monad, so that we can simply call flatMap() and pass in a function with type A => Future[Option[B]].

class FutureOption[A](futureOpt: Future[Option[A]]) {
  def map[B](f: A => B): Future[Option[B]] = futureOpt.map(_.map(f))
  def flatMap[B](f: A => Future[Option[B]]): Future[Option[B]] = {
    futureOpt.flatMap(_.map(f).getOrElse(Future(None)))
  }
  def pure(a: A) = Future(Some(a))
}

Now this works:

val userIdOptF = FutureOption[String](getUserIdOptF)
userIdOptF.flatMap(getSSNOptF)

We can generalize this idea even further into something that can take any monadic type and wrap it around an Option type. This will allow us to define List[Option[A]] for the List type, Either[Option[A]] for the Either type, and similarly for every other monad that exists!

This type of thing is called a monad transformer, which basically lets you stick a monad inside another monad. We’ll use the OptionT type in the cats package, which is a handy implementation of this concept. The same idea above can now be written much more succinctly:

import cats.data.OptionT
import cats.syntax.all._

def wrappedGetUserIdOptF: OptionT[Future, String] = OptionT(getUserIdOptF)
def wrappedGetSSNOptF(s: String): OptionT[Future, String] = OptionT(getSSNOptF(s))
wrappedGetUserIdOptF.flatMap(wrappedGetSSNOptF)

Note that while the outer monad can be generic, the inner is fixed to an Option. As far as I know, there’s no easy way to take in two arbitrary monads A and B and compose another monad A[B]. The reasoning for this is beyond my understanding.

Lastly, you can imagine dealing with functions that return Futures and Options as well.

def getSSNOfSpouseOpt(s: String): Option[String] = {
    // ...given someone's ssn, get their spouse's ssn...
}
def scrambleDigitsF(s: String): Future[String] {
    // ... scramble digits of a ssn...
}

[²]

It would be nice to be able to combine those using the same general pattern. Fortunately, cats provides two functions that allow you to “lift” both Options and some type F (in our case a Future) into an OptionT.

liftF() lifts a function returning type F[A] into an OptionT[F, A]
fromOption[F]() does the same to functions returning Options

def wrappedGetSSNOfSpouseOpt(s: String) =
    OptionT.fromOption[Future](getSSNOfSpouseOpt(s))
def wrappedScrambleDigitsF(s: String) = OptionT.liftF(scrambleDigitsF(s))

And we’re back to where we started - one operation to rule them all:

wrappedGetUserIdOptF
    .flatMap(wrappedGetSSNOptF)
    .flatMap(wrappedGetSSNOfSpouseOpt)
    .flatMap(wrappedScrambleDigitsF)

map() actually comes from applicatives, but every monad is also an applicative so must also define it. ↩
You might think these examples are ridiculous, but I doubt they’re beyond the abilities of a 21st Century Corporation. ↩

Configuring external storage devices for Jellyfin

Sat, 15 Feb 2025 00:00:00 +0000

This post serves as a personal guide to running a Jellyfin server locally using an external hard drive. The following assumes:

Debian GNU/Linux 12+ (I’m using a Raspberry Pi 4)
External hard drive (e.g. /dev/sda1) mounted at something like /media/<username>/<hd name>

1. User/group setup

Jellyfin runs as a systemd service with its own user and group, both of which are usually just jellyfin. To verify this:

$ cat /lib/systemd/system/jellyfin.service | grep "User\|Group"
User = jellyfin
Group = jellyfin

To give jellyfin access to your content, you could of course make it the owner and chmod away. But you’ll probably want to the ability to create new users in the future and given them access as well. Furthermore, manually setting ownership and permissions each time can be cumbersome and error-prone, not to mention you’ll need to mount your drive as read-write. We’ll see later on how to set permissions automatically at mount-time.

The alternate way to do this is to create a group. New users that need to access media can just be added to that group.

$ sudo groupadd media              # create group named media
$ sudo usermod -aG media jellyfin  # add jellyfin to group

2. Mounting your drive

You can mount your drive manually with mount(8), but the better way is to have it done automatically at boot time. The simplest way to do this is to add an entry to /etc/fstab, which is read by mount(8) to determine the overall filesystem structure. (Note that this approach is quite primitive, and there are more modern tools such as udev, which can handle userspace events as well, but for now we’ll stick to fstab, as it is the de facto option and available on most Unix systems.)

An entry in /etc/fstab looks like:

<device> <dir> <type> <options> <dump> <fsck>

First, to get the <device> uuid and filesystem <type>, we can search for our drive in blkid(8):

$ blkid | grep "/dev/sda1"
/dev/sda1: UUID="93033593-60b5-38ef-8086-e434e74192b0" BLOCK_SIZE="4096" LABEL="TOSHIBA_EXT" TYPE="hfsplus" PARTUUID="fea07a4a-01"

Next, <dir> is the mount point, e.g. /media/jamesma100/TOSHIBA_EXT. For <options>, we’ll want the following:

ro to mount as read-only
uid and gid are the user/group for the device when mounted. We’ll want uid to be yourself and gid to be set to the media group we created earlier. To get these ids, you can run
```
$ id
uid=1000(jamesma100) gid=1000(jamesma100) groups=1000(jamesma100),...,1001(media)...
```
umask=022 to give read-write permissions to yourself and read-only permissions to others. The permissions will now be 666 - 022 = 644 for files and 777 - 022 - 755 for directories.

The last two fields are filesystem checks - <dump> is for backups and <fsck> checks for filesystem corruption. I usually set these to off (0) and on (1), respectively.

Putting it all together:

$ echo "UUID=93033593-60b5-38ef-8086-e434e74192b0  /media/jamesma100/TOSHIBA_EXT  hfsplus ro,umask=22,uid=1000,gid=1001 0 1">> /etc/fstab

To test the newly configured fstab without rebooting, run the following:

$ systemctl daemon-reload
$ sudo mount -a -v

This should remount all your partitions, and the -v (verbose) option should tell you which, if any, were unsuccessful.

One last thing to note here: if any of the -o options failed, mount will not notify you! As an example, I ran into an issue where the filesystem on my hard drive was mounted as read-only, despite specifiying the rw option since I had to make some modifications.

I had to resort to dmesg(1) to figure out what was going on.

$ dmesg | tail -n 1
[13719.862245] hfsplus: write access to a journaled filesystem is not supported, use the force option at your own risk, mounting read-only.

Sneaky sneaky!

3. Managing your server

After changing any configuration, you should run

$ systemctl daemon-reload
$ systemctl restart jellyfin

To stop the server:

$ systemctl stop jellyfin

Jellyfin logs go under /var/log/jellyfin. To view status:

$ systemctl status jellyfin

4. Dealing with crashes

If your hard drive was improperly unmounted for any reason, such a crash, it will usually still remount but prompt the user to perform a consistency check. You should do that and then remount it. Once again, it’s necessary to dig through logs; you will not be notified!

$ dmesg | tail -n 2
[  137.881974] hfsplus: filesystem was not cleanly unmounted, running fsck.hfsplus is recommended.  leaving read-only.
[  170.342788] hfsplus: Filesystem was not cleanly unmounted, running fsck.hfsplus is recommended.  mounting read-only.

Now that we’ve confirmed the issue, we can use fsck to do a repair. Keep in mind that you will need a fsck implementation tailored to the filesystem type of your storage device, since fsck operates directly on disk-specific data structures. In my case, I need a fsck.hfsplus for the HFS+ filesystem, which is included in the hfsprogs package.

$ sudo apt-get -y install hfsprogs
$ sudo fsck.hfsplus /dev/sda1
$ sudo mount -a -v