Tenderlove Making

Bainbridge Island Mochi Tsuki

2026-01-19T15:18:23-08:00

Last weekend we took the ferry to Bainbridge Island to see a Mochi Tsuki event. I read about the history of Japanese immigrants on Bainbridge island. I saw people making mochi, a taiko drummer group, and traditional dances. It was a lot of fun, and I learned a lot. Definitely recommend this event!

Pixoo64 Ruby Client

2026-01-01T19:17:26-08:00

I bought a Pixoo64 LED Display to play around with, and I love it! It connects to WiFi and has an on-board HTTP API so you can program it. I made a Ruby client for it that even includes code to convert PNG files to the binary format the sign wants.

One cool thing is that the display can be configured to fetch data from a remote server, so I configured mine to fetch PM2.5 and CO2 data for my office.

Here’s what it’s looking like so far:

Yes, this is how I discovered I need to open a window 😂

Cat Pics

2025-12-30T18:00:58-08:00

Did a few cat pics tonight!

Can Bundler Be as Fast as uv?

2025-12-29T12:26:00-08:00

At RailsWorld earlier this year, I got nerd sniped by someone. They asked “why can’t Bundler be as fast as uv?” Immediately my inner voice said “YA, WHY CAN’T IT BE AS FAST AS UV????”

My inner voice likes to shout at me, especially when someone asks a question so obvious I should have thought of it myself. Since then I’ve been thinking about and investigating this problem, going so far as to give a presentation at XO Ruby Portland about Bundler performance. I firmly believe the answer is “Bundler can be as fast as uv” (where “as fast” has a margin of error lol).

Fortunately, Andrew Nesbitt recently wrote a post called “How uv got so fast”, and I thought I would take this opportunity to review some of the highlights of the post and how techniques applied in uv can (or can’t) be applied to Bundler / RubyGems. I’d also like to discuss some of the existing bottlenecks in Bundler and what we can do to fix them.

If you haven’t read Andrew’s post, I highly recommend giving it a read. I’m going to quote some parts of the post and try to reframe them with RubyGems / Bundler in mind.

Rewrite in Rust?

Andrew opens the post talking about rewriting in Rust:

uv installs packages faster than pip by an order of magnitude. The usual explanation is “it’s written in Rust.” That’s true, but it doesn’t explain much. Plenty of tools are written in Rust without being notably fast. The interesting question is what design decisions made the difference.

This is such a good quote. I’m going to address “rewrite in Rust” a bit later in the post. But suffice to say, I think if we eliminate bottlenecks in Bundler such that the only viable option for performance improvements is to “rewrite in Rust”, then I’ll call it a success. I think rewrites give developers the freedom to “think outside the box”, and try techniques they might not have tried. In the case of uv, I think it gave the developers a good way to say “if we don’t have to worry about backwards compatibility, what could we achieve?”.

I suspect it would be possible to write a uv in Python (PyUv?) that approaches the speeds of uv, and in fact much of the blog post goes on to talk about performance improvements that aren’t related to Rust.

Installing code without eval’ing

pip’s slowness isn’t a failure of implementation. For years, Python packaging required executing code to find out what a package needed.

I didn’t know this about Python packages, and it doesn’t really apply to Ruby Gems so I’m mostly going to skip this section.

Ruby Gems are tar files, and one of the files in the tar file is a YAML representation of the GemSpec. This YAML file declares all dependencies for the Gem, so RubyGems can know, without evaling anything, what dependencies it needs to install before it can install any particular Gem. Additionally, RubyGems.org provides an API for asking about dependency information, which is actually the normal way of getting dependency info (again, no eval required).

There’s only one other thing from this section I’d like to quote:

PEP 658 (2022) put package metadata directly in the Simple Repository API, so resolvers could fetch dependency information without downloading wheels at all.

Fortunately RubyGems.org already provides the same information about gems.

Reading through the number of PEPs required as well as the amount of time it took to get the standards in place was very eye opening for me. I can’t help but applaud folks in the Python community for doing this. It seems like a mountain of work, and they should really be proud of themselves.

What uv drops

I’m mostly going to skip this section except for one point:

Ignoring requires-python upper bounds. When a package says it requires python<4.0, uv ignores the upper bound and only checks the lower. This reduces resolver backtracking dramatically since upper bounds are almost always wrong. Packages declare python<4.0 because they haven’t tested on Python 4, not because they’ll actually break. The constraint is defensive, not predictive.

I think this is very very interesting. I don’t know how much time Bundler spends on doing “required Ruby version” bounds checking, but it feels like if uv can do it, so can we.

Optimizations that don’t need Rust

I really love that Andrew pointed out optimizations that could be made that don’t involve Rust. There are three points in this section that I want to pull out:

Parallel downloads. pip downloads packages one at a time. uv downloads many at once. Any language can do this.

This is absolutely true, and is a place where Bundler could improve. Bundler currently has a problem when it comes to parallel downloads, and needs a small architectural change as a fix.

The first problem is that Bundler tightly couples installing a gem with downloading the gem. You can read the installation code here, but I’ll summarize the method in question below:

def install
  path = fetch_gem_if_not_cached
  Bundler::RubyGemsGemInstaller.install path, dest
end

The problem with this method is that it inextricably links downloading the gem with installing it. This is a problem because we could be downloading gems while installing other gems, but we’re forced to wait because the installation method couples the two operations. Downloading gems can trivially be done in parallel since the .gem files are just archives that can be fetched independently.

The second problem is the queuing system in the installation code. After gem resolution is complete, and Bundler knows what gems need to be installed, it queues them up for installation. You can find the queueing code here. The code takes some effort to understand. Basically it allows gems to be installed in parallel, but only gems that have already had their dependencies installed.

So for example, if you have a dependency tree like “gem a depends on gem b which depends on gem c” (a -> b -> c), then no gems will be installed (or downloaded) in parallel.

To demonstrate this problem in an easy-to-understand way, I built a slow Gem server. It generates a dependency tree of a -> b -> c (a depends on b, b depends on c), then starts a Gem server. The Gem server takes 3 seconds to return any Gem, so if we point Bundler at this Gem server and then profile Bundler, we can see the impact of the queueing system and download scheme.

In my test app, I have the following Gemfile:

source "http://localhost:9292"

gem "a"

If we profile Bundle install with Vernier, we can see the following swim lanes in the marker chart:

The above chart is showing that we get no parallelism during installation. We spend 3 seconds downloading the c gem, then we install it. Then we spend 3 seconds downloading the b gem, then we install it. Finally we spend 3 seconds downloading the a gem, and we install it.

Timing the bundle install process shows we take over 9 seconds to install (3 seconds per gem):

> rm -rf x; rm -f Gemfile.lock; time GEM_PATH=(pwd)/x GEM_HOME=(pwd)/x bundle install
Fetching gem metadata from http://localhost:9292/...
Resolving dependencies...
Fetching c 1.0.0
Installing c 1.0.0
Fetching b 1.0.0
Installing b 1.0.0
Fetching a 1.0.0
Installing a 1.0.0
Bundle complete! 1 Gemfile dependency, 3 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

________________________________________________________
Executed in   11.80 secs      fish           external
   usr time  341.62 millis  231.00 micros  341.38 millis
   sys time  223.20 millis  712.00 micros  222.49 millis

Contrast this with a Gemfile containing d, e, and f, which have no dependencies, but still take 3 seconds to download:

source "http://localhost:9292"

gem "d"
gem "e"
gem "f"

Timing bundle install for the above Gemfile shows it takes about 4 seconds:

> rm -rf x; rm -f Gemfile.lock; time GEM_PATH=(pwd)/x GEM_HOME=(pwd)/x bundle install
Fetching gem metadata from http://localhost:9292/.
Resolving dependencies...
Fetching d 1.0.0
Fetching e 1.0.0
Fetching f 1.0.0
Installing e 1.0.0
Installing f 1.0.0
Installing d 1.0.0
Bundle complete! 3 Gemfile dependencies, 3 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

________________________________________________________
Executed in    4.14 secs      fish           external
   usr time  374.04 millis    0.38 millis  373.66 millis
   sys time  368.90 millis    1.09 millis  367.81 millis

We were able to install the same number of gems in a fraction of the time. This is because Bundler is able to download siblings in the dependency tree in parallel, but unable to handle other relationships.

There is actually a good reason that Bundler insists dependencies are installed before the gems themselves: native extensions. When installing native extensions, the installation process must run Ruby code (the extconf.rb file). Since the extconf.rb could require dependencies be installed in order to run, we must install dependencies first. For example nokogiri depends on mini_portile2, but mini_portile2 is only used during the installation process, so it needs to be installed before nokogiri can be compiled and installed.

However, if we were to decouple downloading from installation it would be possible for us to maintain the “dependencies are installed first” business requirement but speed up installation. In the a -> b -> c case, we could have been downloading gems a and b at the same time as gem c (or even while waiting on c to be installed).

Additionally, pure Ruby gems don’t need to execute any code on installation. If we knew that we were installing a pure Ruby gem, it would be possible to relax the “dependencies are installed first” business requirement and get even more performance increases. The above a -> b -> c case could install all three gems in parallel since none of them execute Ruby code during installation.

I would propose we split installation in to 4 discrete steps:

Download the gem
Unpack the gem
Compile the gem
Install the gem

Downloading and unpacking can be done trivially in parallel. We should unpack the gem to a temporary folder so that if the process crashes or the machine loses power, the user isn’t stuck with a half-installed gem. After we unpack the gem, we can discover whether the gem is a native extension or not. If it’s not a native extension, we “install” the gem simply by moving the temporary folder to the “correct” location. This step could even be a “hard link” step as discussed in the next point.

If we discover that the gem is a native extension, then we can “pause” installation of that gem until its dependencies are installed, then resume (by compiling) at an appropriate time.

Side note: gel, a Bundler alternative, works mostly in this manner today. Here is a timing of the a -> b -> c case from above:

> rm -f Gemfile.lock; time gel install
Fetching sources....
Resolving dependencies...
Writing lockfile to /Users/aaron/git/gemserver/app/Gemfile.lock
Installing c (1.0.0) 
Installing a (1.0.0)
Installing b (1.0.0)
Installed 3 gems  

________________________________________________________
Executed in    4.07 secs      fish           external
   usr time  289.22 millis    0.32 millis  288.91 millis
   sys time  347.04 millis    1.36 millis  345.68 millis

Lets move on to the next point:

Global cache with hardlinks. pip copies packages into each virtual environment. uv keeps one copy globally and uses hardlinks

I think this is a great idea, but I’d actually like to split the idea in two. First, RubyGems and Bundler should have a combined, global cache, full stop. I think that global cache should be in $XDG_CACHE_HOME, and we should store .gem files there when they are downloaded.

Currently, both Bundler and RubyGems will use a Ruby version specific cache folder. In other words, if you do gem install rails on two different versions of Ruby, you get two copies of Rails and all its dependencies.

Interestingly, there is an open ticket to implement this, it just needs to be done.

The second point is hardlinking on installation. The idea here is that rather than unpacking the gem multiple times, once per Ruby version, we simply unpack once and then hard link per Ruby version. I like this idea, but I think it should be implemented after some technical debt is paid: namely implementing a global cache and unifying Bundler / RubyGems code paths.

On to the next point:

PubGrub resolver

Actually Bundler already uses a Ruby implementation of the PubGrub resolver. You can see it here. Unfortunately, RubyGems still uses the molinillo resolver.

In other words you use a different resolver depending on whether you do gem install or bundle install. I don’t really think this is a big deal since the vast majority of users will be doing bundle install most of time. However, I do think this discrepancy is some technical debt that should be addressed, and I think this should be addressed via unification of RubyGems and Bundler codebases (today they both live in the same repository, but the code isn’t necessarily combined).

Lets move on to the next section of Andrew’s post:

Where Rust actually matters

Andrew first mentions “Zero-copy deserialization”. This is of course an important technique, but I’m not 100% sure where we would utilize it in RubyGems / Bundler. I think that today we parse the YAML spec on installation, and that could be a target. But I also think we could install most gems without looking at the YAML gemspec at all.

Thread-level parallelism. Python’s GIL forces parallel work into separate processes, with IPC overhead and data copying.

This is an interesting point. I’m not sure what work pip needed to do in separate processes. Installing a pure Ruby, Ruby Gem is mostly an IO bound task, with some ZLIB mixed in. Both of these things (IO and ZLIB processing) release Ruby’s GVL, so it’s possible for us to do things truly in parallel. I imagine this is similar for Python / pip, but I really have no idea.

Given the stated challenges with Python’s GIL, you might wonder whether Ruby’s GVL presents similar parallelism problems for Bundler. I don’t think so, and in fact I think Ruby’s GVL gets kind of a bad rap. It prevents us from running CPU bound Ruby code in parallel. Ractors address this, and Bundler could possibly leverage them in the future, but since installing Gems is mostly an IO bound task I’m not sure what the advantage would be (possibly the version solver, but I’m not sure what can be parallelized in there). The GVL does allow us to run IO bound work in parallel with CPU bound Ruby code. CPU bound native extensions are allowed to release the GVL, allowing Ruby code to run in parallel with the native extension’s CPU bound code.

In other words, Ruby’s GVL allows us to safely run work in parallel. That said, the GVL can work against us because releasing and acquiring the GVL takes time.

If you have a system call that is very fast, releasing and acquiring the GVL could end up being a large percentage of that call. For example, if you do File.binwrite(file, buffer), and the buffer is very small, you could encounter a situation where GVL book keeping is the majority of the time. A bummer is that Ruby Gem packages usually contain lots of very small files, so this problem could be impacting us. The good news is that this problem can be solved in Ruby itself, and indeed some work is being done on it today.

No interpreter startup. Every time pip spawns a subprocess, it pays Python’s startup cost.

Obviously Ruby has this same problem. That said, we only start Ruby subprocesses when installing native extensions. I think native extensions make up the minority of gems installed, and even when installing a native extension, it isn’t Ruby startup that is the bottleneck. Usually the bottleneck is compilation / linking time (as we’ll see in the next post).

Compact version representation. uv packs versions into u64 integers where possible, making comparison and hashing fast.

This is a cool optimization, but I don’t think it’s actually Rust specific. Comparing integers is much faster than comparing version objects. The idea is that you take a version number, say 1.0.0, and then pack each part of the version in to a single integer. For example, we could represent 1.0.0 as 0x0001_0000_0000_0000 and 1.1.0 as 0x0001_0001_0000_0000, etc.

It should be possible to use this trick in Ruby and encode versions to integer immediates, which would unlock performance in the resolver. Rust has an advantage here - compiled native code comparing u64s will always be faster than Ruby, even with immediates. However, I would bet that with the YJIT or ZJIT in play, this gap could be closed enough that no end user would notice the difference between a Rust or Ruby implementation of Bundler.

I started refactoring the Gem::Version object so that we might start doing this, but we ended up reverting it because of backwards compatibility (I am jealous of uv in that regard). I think the right way to do this is to refactor the solver entry point and ensure all version requirements are encoded as integer immediates before entering the solver. We could keep the Gem::Version API as “user facing” and design a more internal API that the solver uses. I am very interested in reading the version encoding scheme in uv. My intuition is that minor numbers tend to get larger than major numbers, so would minor numbers have more dedicated bits? Would it even matter with 64 bits?

Wrapping this up

I’m going to quote Andrew’s last 2 paragraphs:

uv is fast because of what it doesn’t do, not because of what language it’s written in. The standards work of PEP 518, 517, 621, and 658 made fast package management possible. Dropping eggs, pip.conf, and permissive parsing made it achievable. Rust makes it a bit faster still.

pip could implement parallel downloads, global caching, and metadata-only resolution tomorrow. It doesn’t, largely because backwards compatibility with fifteen years of edge cases takes precedence. But it means pip will always be slower than a tool that starts fresh with modern assumptions.

I think these are very good points. The difference is that in RubyGems and Bundler, we already have the infrastructure in place for writing a “fast as uv” package manager. The difficult part is dealing with backwards compatibility, and navigating two legacy codebases. I think this is the real advantage the uv developers had. That said, I am very optimistic that we could “repair the plane mid-flight” so to speak, and have the best of both worlds: backwards compatibility and speed.

I mentioned at the top of the post I would address “rewrite it in Rust”, and I think Andrew’s own quote mostly does that for me. I think we could have 99% of the performance improvements while still maintaining a Ruby codebase. Of course if we rewrote it in Rust, you could squeeze an extra 1% out, but would it be worthwhile? I don’t think so.

I have a lot more to say about this topic, and I feel like this post is getting kind of long, so I’m going to end it here. Please look out for part 2, which I’m tentatively calling “What makes Bundler / RubyGems slow?” This post was very “can we make RubyGems / Bundler do what uv does?” (the answer is “yes”). In part 2 I want to get more hands-on by discussing how to profile Bundler and RubyGems, what specifically makes them slow in the real world, and what we can do about it.

I want to end this post by saying “thank you” to Andrew for writing such a great post about how uv got so fast.

Happy Holidays

2025-12-22T16:01:02-08:00

Happy holidays everyone! Have a great rest of the year!

Seattle Waterfront

2025-12-16T16:49:54-08:00

Went to the Seattle waterfront over the weekend to watch the sunset (at like 4pm lol). Unfortunately it was pretty cloudy out, but I had a good time.

Seattle Downtown Library

2025-11-30T14:05:50-08:00

I want to try posting more images to my blog, so here’s my first try. Instagram doesn’t really seem like a good place to post photos anymore, so I figured I’d try on my blog. I’d like to get my blog working with Posse Party at some point, I just need to figure out the API keys, and then I can cross post this to Instagram anyway.

Recently I went on a photo walk to the Seattle downtown public library. These images are from that photo walk! I’ve been living in Seattle since before the library was built, and I never took the chance to actually go visit, so this was a good opportunity. I feel like when you live somewhere, you don’t take the opportunity to visit all of the cool stuff there, and going on local photo walks seems like a good way for me to visit more of the city.

Anyway, the Seattle public library is really great and I recommend anyone to visit!

Apple Photos App Corrupts Images

2025-09-17T08:59:23+09:00

The Apple Photos app sometimes corrupts images when importing from my camera. I just wanted to make a blog post about it in case anyone else runs into the problem. I’ve seen other references to this online, but most of the people gave up trying to fix it, and none of them went as far as I did to debug the issue.

I’ll try to describe the problem, and the things I’ve tried to do to fix it. But also note that I’ve (sort of) given up on the Photos app too. Since I can’t trust it to import photos from my camera, I switched to a different workflow.

Here is a screenshot of a corrupted image in the Photos app:

How I used to import images

I’ve got an OM System OM-1 camera. I used to shoot in RAW + jpg, then when I would import to Photos app, I would check the “delete photos after import” checkbox in order to empty the SD card. Turns out “delete after import” was a huge mistake.

Getting corrupted images

I’m pretty sure I’d been getting corrupted images for a while, but it would only be 1 or 2 images out of thousands, so I thought nothing of it (it was probably my fault anyway, right?)

But the problem really got me upset when last year I went to a family member’s wedding and took tons of photos. Apple Photos combines RAW + jpg photos so you don’t have a bunch of duplicates, and when you view the images in the photos app, it just shows you the jpg version by default. After I imported all of the wedding photos I noticed some of them were corrupted. Upon closer inspection, I found that it sometimes had corrupted the jpg, sometimes corrupted the RAW file, and sometimes both. Since I had been checking the “delete after import” box, I didn’t know if the images on the SD card were corrupted before importing or not. After all, the files had been deleted so there was no way to check.

I estimate I completely lost about 30% of the images I took that day.

Losing so many photos really rattled me, but I wanted to figure out the problem so I didn’t lose images in the future.

Narrowing down the problem

I was worried this was somehow a hardware problem. Copying files seems so basic, I didn’t think there was any way a massively deployed app like Photos could fuck it up (especially since its main job is managing photo files). So, to narrow down the issue I changed out all of the hardware. Here are all the things I did:

Switched USB-C cables
Bought a new SD card direct from the manufacturer (to eliminate the possibility of buying a bootleg SD card)
Switched to only shooting in RAW (if importing messes up 30% of my images, but I cut the number of images I import by half, then that should be fewer corrupted images right? lol)
Bought a new laptop
Bought a new camera: the OM System OM-1 MKii

I did each of these steps over time, as to only change one variable at a time, and still the image corruption persisted. I didn’t really want to buy a new camera, the MKii is not really a big improvement over the OM-1, but we had a family trip coming up and the idea that pressing the shutter button on the camera might not actually record the image didn’t sit well with me.

Finally a smoking gun

Since I had replaced literally all of the hardware involved, I knew it must be a software problem. I stopped checking the “delete after import” button, and started reviewing all of the photos after import. After verifying none of them were corrupt, then I would format the SD card. I did this for months without finding any corrupt files. At this point I figured it was somehow a race condition or something when copying the photo files and deleting them at the same time.

However, after I got home from RailsConf and imported my photos, I found one corrupt image (the one above). I was able to verify that the image was not corrupt on the SD card, so the camera was working fine (meaning I probably didn’t need to buy a new camera body at all).

I tried deleting the corrupt file and re-importing the original to see if it was something about that particular image, but it re-imported just fine. In other words, it seems like the Photos app will corrupt files randomly.

I don’t know if this is a problem that is specific to OM System cameras, and I’m not particularly interested in investing in a new camera system just to find out.

If I compare the corrupted image with the non-corrupted image, the file sizes are exactly the same, but the bytes are different:

Checksums:

aaron@tc ~/Downloads> md5sum P7110136-from-camera.ORF Exports/P7110136.ORF 
17ce895fd809a43bad1fe8832c811848  P7110136-from-camera.ORF
828a33005f6b71aea16d9c2f2991a997  Exports/P7110136.ORF

File sizes:

aaron@tc ~/Downloads> ls -al P7110136-from-camera.ORF Exports/P7110136.ORF
-rw-------@ 1 aaron  staff  18673943 Jul 12 04:38 Exports/P7110136.ORF
-rwx------  1 aaron  staff  18673943 Jul 17 09:29 P7110136-from-camera.ORF*

The P7110136-from-camera.ORF is the non-corrupted file, and Exports/P7110136.ORF is the corrupted file from Photos app. Here’s a screenshot of the preview of the non-corrupted photo:

Here is the binary diff between the files. I ran both files through xxd then diffed them. Also if anyone cares to look, I’ve posted the RAW files here on GitHub.

My new workflow

I’m not going to put any more effort into debugging this problem, but I wanted to blog about it in case anyone else is seeing the issue. I take a lot of photos, and to be frank, most of them are not very good. I don’t want to look through a bunch of bad photos every time I look at my library, so culling photos is important. Culling photos in the Photos app is way too cumbersome, so I’ve switched to using Darktable.

My current process is:

Import images to Darktable
Delete the ones I don’t like
Process ones I do like
Export both the jpg and the original raw file
Import those to the Photos app so they’re easy to view and share
Periodically format my SD card

I’ve not seen any file corruption when importing to Darktable, so I am convinced this is a problem with the Photos app. But now, since all of my images land in Darktable before making their way to the Photos app, I don’t really care anymore. The bad news is that I’ve spent a lot of time and money trying to debug this. I guess the good news is that now I have redundant hardware!

File preallocation on macOS in Ruby

2025-09-10T07:12:21+09:00

I haven’t blogged in a while, so I figured I should do that. Jet lag has blessed me with some free time this morning, so I figured I would make some content in order to feed the AI bots.

I’ve been messing around with pre-allocating files on the file system on macOS. This is useful in cases where you have a large file you need to copy, and you want to copy it quickly. For example, a tar implementation where the tar file might contain large files you need to copy.

Here is the code:

require "fcntl"

# typedef struct fstore {
#     u_int32_t fst_flags;      /* IN: flags word */
#     int       fst_posmode;    /* IN: indicates offset field */
#     off_t     fst_offset;     /* IN: start of the region */
#     off_t     fst_length;     /* IN: size of the region */
#     off_t     fst_bytesalloc; /* OUT: number of bytes allocated */
# } fstore_t;

size = 1234
fmt = [Fcntl::F_ALLOCATECONTIG, Fcntl::F_PEOFPOSMODE, 0, size, 0]
bytes = fmt.pack("LlQQQ")

File.open("foo", "wb") { |fd|
  fd.fcntl(Fcntl::F_PREALLOCATE, bytes)
  fd.truncate size
}

If you run this script, you’ll find a file named “foo” with the size 1234. For this code to work, you’ll need to be on macOS, and using this branch of the fcntl gem (though hopefully my patch will make it upstream and you can just use the fcntl gem).

I tried implementing this as a performance optimization, but unfortunately the performance optimization didn’t work out, so I’m probably not going to use this code IRL. Rather than leaving the code to rot on my computer, I figured I’d make a blog post so at least people can search for it, or I can train the LLMs in my image (lol).

Anyway, thanks for reading my very niche content! Have a good day!

Monkey Patch Detection in Ruby

2024-10-16T16:13:00-07:00

My last post detailed one way that CRuby will eliminate some intermediate array allocations when using methods like Array#hash and Array#max. Part of the technique hinges on detecting when someone monkey patches array. Today, I thought we’d dive a little bit in to how CRuby detects and de-optimizes itself when these “important” methods get monkey patched.

Monkey Patching Problem

The optimization in the previous post made the assumption that the implementation Array#max was the original definition (as defined in Ruby itself). But the Ruby language allows us to reopen classes, redefine any methods we want, and that those methods will “just work”.

For example, if someone were to reopen Array and define a new max method, we would need to respect that monkey patch:

class Array
  def max
    "hello!"
  end
end

puts [1, 2].max # => "hello!"

In fact, a monkey patch implementation could mutate the array itself, so we’re definitely required to allocate an array in the case that someone added their own max method:

class Array
  def max
    self << :neat
    self
  end
end

x = [1, 2].max
p x # => [1, 2, :neat]

So how does CRuby detect that a method has been monkey patched?

Method Definition Time

Every time a method is defined, an entry is stored in a hash table pointed to by the current class. We call this the “method table”, but you’ll see it referred to as M_TBL or RCLASS_M_TBL in the code. The key to the hash is simply the method name as an ID type (an integer which represents a Ruby Symbol), and the value of the hash is a method entry structure. If there was already an entry in the table, then we know it’s a “redefinition” (a.k.a. “monkey patch”), and we end up calling rb_vm_check_redefinition_opt_method here.

rb_vm_check_redefinition_opt_method checks to see if this is a method we “care” about. Methods we “care” about are typically ones where we’ve made some kind of optimization and we need to deoptimize if someone redefines them.

If the redefined method is something we care to detect, then we set a flag in a global variable ruby_vm_redefined_flag, which is an array of integers.

The indexes of the ruby_vm_redefined_flag array correspond to “basic operators”, or BOPs. So for example, the 0th element is for BOP_PLUS, the 1th element is BOP_MINUS, etc. You can see the full list of basic operators here. These basic operators correspond to method names that we care about. So if someone monkey patches the + operator, we’ll set a flag in ruby_vm_redefined_flag[BOP_PLUS].

The values of the ruby_vm_redefined_flag array correspond to a bitmap that maps to classes we care about. You can see the list of classes and their corresponding bits here, as well as a function for mapping “classes we care about” to their corresponding bit flag.

For example, if someone monkey patches Array#pack, we would set a bit in ruby_vm_redefined_flag like this:

ruby_vm_redefined_flag[BOP_PACK] |= ARRAY_REDEFINED_OP_FLAG;

Then, when we execute our optimized instruction (opt_newarray_send which was introduced in the last post), we can check the bitmap to decide whether or not to take our fast path:

if ((ruby_vm_redefined_flag[BOP_PACK] & ARRAY_REDEFINED_OP_FLAG) == 0) {
  // It _hasn't_ been monkey patched, so take the fast path
}
else {
  // It _has_ been monkey patched, do the slow path
}

Of course this bitmask checking is wrapped in a macro that looks more like this:

if (BASIC_OP_UNREDEFINED_P(BOP_PACK, ARRAY_REDEFINED_OP_FLAG)) {
  // It _hasn't_ been monkey patched, so take the fast path
}
else {
  // It _has_ been monkey patched, do the slow path
}

You can see the actual code for Array#pack redefinition checking here.

Bonus Stuff

A cool thing (at least I think it’s cool) is that the function rb_vm_check_redefinition_opt_method not only sets up the “monkey patch detection” bits, it’s also a natural place to inform the JIT compiler that someone has done something catastrophic and that it should de-optimize. In fact, you can see those calls right here.

A weird thing is that since ruby_vm_redefined_flag is just a list bitmaps, it’s technically possible for us to track the definition of Integer#pack even though that method doesn’t exist:

ruby_vm_redefined_flag[BOP_PACK] |= INTEGER_REDEFINED_OP_FLAG;

I guess that means there’s a lot of bit space that isn’t used, but I don’t really think it’s a big deal.

Anyway, have a good day!

Eliminating Intermediate Array Allocations

2024-09-29T19:06:28-07:00

Recently I gave a talk at RailsWorld (hopefully they’ll post the video soon), and part of my presentation was about eliminating allocations in tokenizers. I presented a simple function for measuring allocations:

def allocations
  x = GC.stat(:total_allocated_objects)
  yield
  GC.stat(:total_allocated_objects) - x
end

Everything in Ruby is an object, but not all objects actually make allocations. We can use the above function to measure allocations made in a block. Here are some examples of code that never allocate:

p allocations { true }                  # => 0
p allocations { false }                 # => 0
p allocations { nil }                   # => 0
p allocations { :hello }                # => 0
p allocations { 1 }                     # => 0
p allocations { 2.3 }                   # => 0
p allocations { 0xFFFF_FFFF_FFFF_FFFF } # => 0

Literals like booleans, nil, symbols, integers, and floats are represented internally to CRuby as “tagged pointers” and they don’t allocate anything when executed.

Here is an example of code that sometimes allocates:

# Depends on the size of the number
p allocations { 1 + 2 }                     # => 0
p allocations { 0x3FFF_FFFF_FFFF_FFFF + 1 } # => 1

# Depends on `frozen_string_literal`
p allocations { "hello!" }                  # => 0 or 1

Math on integers generally doesn’t allocate anything, but it depends on the integer. When a number gets large enough, CRuby will allocate an object to represent that number. On 64 bit platforms, the largest whole number we can represent without allocating is 0x3FFF_FFFF_FFFF_FFFF.

String literals will sometimes allocate, but it depends on the frozen_string_literal setting in your program.

Here is an example of code that always allocates:

p allocations { [1, 2] }      # => 1
p allocations { { a: :b } }   # => 1
p allocations { Object.new }  # => 1
p allocations { "foo"[0, 1] } # => 1

Hopefully these examples are fairly straightforward. Arrays, hashes, objects, string slices, etc will allocate an object.

Eliminating Intermediate Array Allocations

At the Shopify after-party at RailsWorld, someone asked me a really great question. Their codebase has a RuboCop rule that says that when doing min or max calculations, you should always have code like this:

def foo(x, y)
  [x, y].max
end

They were concerned this is wasteful as it has an Array literal, so it will be allocating an array every time!

I think this is a really great question, and if you read my earlier allocation measurement examples, I think it’s a very reasonable conclusion. However, it’s actually not the case. This code in particular will not allocate an array, and I thought we’d look in to how that works.

The compiler in Ruby is able to tell a few important things about this code. First, we’re calling a method on an array literal which means that we’re guaranteed that the max method will be sent to an array object. Second, we know statically that we’re calling the max method. Third, the max method that is implemented in core Ruby will not mutate its receiver, and it returns some value (an integer) that isn’t the array literal.

Since the compiler knows that the array literal is ephemeral, it allocates the array on the stack, does the max calculation, then throws away the array, never asking the GC for a new object.

To get a more concrete picture, lets look at the instruction sequences for the above code:

def foo(x, y)
  [x, y].max
end

insn = RubyVM::InstructionSequence.of(method(:foo))
puts insn.disasm

== disasm: #<ISeq:foo@x.rb:1 (1,0)-(1,30)>
local table (size: 2, argc: 2 [opts: 0, rest: -1, post: 0, block: -1, kw: -1@-1, kwrest: -1])
[ 2] x@0<Arg>   [ 1] y@1<Arg>
0000 getlocal_WC_0                          x@0                       (   1)[LiCa]
0002 getlocal_WC_0                          y@1
0004 opt_newarray_send                      2, 1
0007 leave                                  [Re]

The first two instructions fetch the locals x and y, and push them on the stack. Next we have a special instruction opt_newarray_send. This instruction takes two parameters, 2, 1. It’s a bit cryptic, but the 2 means that this instruction is going to operate on two stack elements. The 1 is an enum and means “we want to call the max method”.

The opt_newarray_send instruction will first check to see if Array#max has been monkey patched. If it has been monkey patched, then the instruction will allocate a regular array and call the monkey patched method. If it hasn’t been monkey patched, then it calls a “max” function which uses Ruby’s stack as an array buffer.

Here is what the stack looks like before executing opt_newarray_send:

+----+-------------+-------------+
|    | Stack Index | Stack Value |
+----+-------------+-------------+
|    | -2          | x           |
|    | -1          | y           |
| SP | 0           | Undef       |
+----+-------------+-------------+

The opt_newarray_send instruction was passed the value 2, so it knows to start the array at negative 2 relative to the stack pointer (SP). Since the stack is just an array, it calls the same function that the max function would normally call, popping 2 values from the stack, then pushing the return value of the max function.

In this way we can calculate the max value without allocating the intermediate array.

If we use our allocations function, we can confirm that the foo method indeed does not allocate anything:

def foo(x, y)
  [x, y].max
end

allocations { foo(3, 4) } # heat inline caches
p allocations { foo(3, 4) } # => 0

Aaron’s Opinion Corner

I don’t really know RuboCop very well, but I think that in cases like this it would be really helpful if the linter were to tell you why a particular rule is a rule. Personally, I dislike following rules unless I understand the reason behind them. Even if the reasoning is simply “this is just how our team styles our code”. If such a feature is already available in RuboCop, then please feel free to link to this blog post for this particular rule.

I can only assume the rule that enforced this style was “performance” related. I’m not a huge fan of linting, but I’m even less of a fan when it comes to rules around “performance”. If idiomatic Ruby is not performant, then I think there can be a strong case to be made that the CRuby team (which I am a part of) should make that code performant. If the CRuby team does make the code performant, then there is no need for the performance rule because most people write idiomatic Ruby code (by definition).

Of course there are cases where you may need to write non-idiomatic Ruby for performance reasons, but hopefully those cases are few and far between. Should the time arrive when you need to write odd code for performance reasons, it will require knowledge, experience, and nuance that neither a linter nor an AI can provide. Fortunately, this is a case where idiomatic Ruby is also “the fast way to do things”, so I definitely recommend people use the [x, y].max pattern.

More Stuff

Array#max isn’t the only method that uses this trick. It works with Array#min, Array#pack and Array#hash. If you need to implement a custom hash method on an object, then I highly recommend doing something like this:

def hash
  [@ivar1, @ivar2, ...].hash
end

Finally, there are cases where CRuby won’t apply this trick. Lets look at the instructions for the following method:

def foo
  [3, 4].max
end

insn = RubyVM::InstructionSequence.of(method(:foo))
puts insn.disasm

== disasm: #<ISeq:foo@x.rb:1 (1,0)-(3,3)>
0000 duparray                               [3, 4]                    (   2)[LiCa]
0002 opt_send_without_block                 <calldata!mid:max, argc:0, ARGS_SIMPLE>
0004 leave                                                            (   3)[Re]

If you read these instructions carefully, you’ll see it has a duparray instruction. This instruction allocates an array, and then we call the max method on the array.

When all of the elements of the array are static, CRuby applies an optimization to allocate the array once, embed it in the instructions, and then do a dup on the array. Copying an existing array is much faster than allocating a new one. Unfortunately, this optimization is applied before the “max” method optimization, so it doesn’t apply both.

For those of you at home saying “the compiler could calculate the max of [3, 4] and eliminate the array all together!” just remember that someone could monkey patch Array#max and we’d need to respect it. Argh!! Fixing this particular case is not worth the code complexity, in my opinion. We all know that 4 is greater than 3, so we could “manually inline” this case and just write 4.

Anyway, all this to say is that these optimizations are context dependent. Attempting to “prescribe” more optimal code seems like it could become a hairy situation, especially since the linter can’t know what the Ruby compiler will do.

I do like the idea of language servers possible suggesting possibly faster code, but only as a teaching opportunity for the developer. The real goal should be to help build understanding so that this type of linting becomes unnecessary.

Anyway, I had a really great time at RailsWorld. I am very happy I got this question, and I hope that this post helps someone!

Using Serial Ports with Ruby

2024-02-16T11:56:28-08:00

Lets mess around with serial ports today! I love doing hardware hacking, and dealing with serial ports is a common thing you have to do when working with embedded systems. Of course I want to do everything with Ruby, and I had found Ruby serial port libraries to be either lacking, or too complex, so I decided to write my own. I feel like I’ve not done a good enough job promoting the library, so today we’re going to mess with serial ports using the UART gem. Don’t let the last commit date on the repo fool you, despite being over 6 years ago, this library is actively maintained (and I use it every day!).

I’ve got a GMC-320 Geiger counter. Not only is the price pretty reasonable, but it also has a serial port interface! You can log data, then download the logged data via serial port. Today we’re just going to write a very simple program that gets the firmware version via serial port, and then gets live updates from the device. This will allow us to start with UART basics in Ruby, and then work with streaming data and timeouts.

The company that makes the Geiger counter published a spec for the UART commands that the device supports, so all we need to do is send the commands and read the results.

According to the spec, the default UART config for my Geiger counter is 115200 BPS, Data bit: 8, no parity, Stop bit: 1, and no control. This is pretty easy to configure with the UART gem, all of these values are default except for the baud rate. The UART gem defaults to 9600 for the baud rate, so that’s the only thing we’ll have to configure.

Getting the hardware version

To get the hardware model and version, we just have to send <GETVER>> over the serial port and then read the response. Let’s write a small program that will fetch the hardware model and version and print them out.

require "uart"

UART.open ARGV[0], 115200 do |serial|
  # Send the "get version" command
  serial.write "<GETVER>>"

  # read and print the result
  puts serial.read
end

The first thing we do is require the uart library (make sure to gem install uart if you haven’t done so yet). Then we open the serial interface. We’ll pass the tty file in via the command line, so ARGV[0] will have the path to the tty. When I plug my Geiger counter in, it shows up as /dev/tty.usbserial-111240. We also configure the baud rate to 115200.

Once the serial port is open, we are free to read and write to it as if it were a Ruby file object. In fact, this is because it really is just a regular file object.

First we’ll send the command <GETVER>>, then we’ll read the response from the serial port.

Here’s what it looks like when I run it on my machine:

$ ruby rad.rb /dev/tty.usbserial-111240
GMC-320Re 4.09

Live updates

According to the documentation, we can get live updates from the hardware. To do that, we just need to send the <HEARTBEAT1>> command. Once we send that command, the hardware will write a value to the serial port every second, and it’s our job to read the data when it becomes available. We can use IO#wait_readable to wait until there is data to be read from the serial port.

According to the specification, there are two bytes (a 16 bit integer), and we need to ignore the top 2 bits. We’ll create a mask to ignore the top two bits, and combine that with the two bytes we read to get our value:

require "uart"

MASK = (~(3 << 14)) & 0xFFFF

UART.open ARGV[0], 115200 do |serial|
  # turn on heartbeat
  serial.write "<HEARTBEAT1>>"

  loop do
    if serial.wait_readable
      count = ((serial.readbyte << 8) | serial.readbyte) & MASK
      p count
    end
  end
ensure
  # make sure to turn off heartbeat
  serial.write "<HEARTBEAT0>>"
end

After we’ve sent the “start heartbeat” command, we enter a loop. Inside the loop, we block until there is data available to read by calling serial.wait_readable. Once there is data to read, we’ll read two bytes and combine them to a 16 bit integer. Then we mask off the integer using the MASK constant so that the two top bits are ignored. Finally we just print out the count.

The ensure section ensures that when the program exits, we’ll tell the hardware “hey, we don’t want to stream data anymore!”

When I run this on my machine, the output is like this (I hit Ctrl-C to stop the program):

$ ruby rad.rb /dev/tty.usbserial-111240
0
0
0
0
0
0
0
1
0
1
0
0
0
1
^Crad.rb:10:in 'IO#wait_readable': Interrupt
	from rad.rb:10:in 'block (2 levels) in <main>'
	from <internal:kernel>:191:in 'Kernel#loop'
	from rad.rb:9:in 'block in <main>'
	from /Users/aaron/.rubies/arm64/ruby-trunk/lib/ruby/gems/3.4.0+0/gems/uart-1.0.0/lib/uart.rb:57:in 'UART.open'
	from rad.rb:5:in '<main>'

Lets do two improvements, and then call it a day. First, lets specify a timeout, then lets calculate the CPM.

Specifying a timeout

Currently, serial.wait_readable will block forever, but we expect an update from the hardware about every second. If it takes longer than say 2 seconds for data to be available, then something must be wrong and we should print a message or exit the program.

Specifying a timeout is quite easy, we just pass the timeout (in seconds) to the wait_readable method like below:

require "uart"

MASK = (~(3 << 14)) & 0xFFFF

UART.open ARGV[0], 115200 do |serial|
  # turn on heartbeat
  serial.write "<HEARTBEAT1>>"

  loop do
    if serial.wait_readable(2)
      count = ((serial.readbyte << 8) | serial.readbyte) & MASK
      p count
    else
      $stderr.puts "oh no, something went wrong!"
      exit(1)
    end
  end
ensure
  # make sure to turn off heartbeat
  serial.write "<HEARTBEAT0>>"
end

When data becomes available, wait_readable will return a truthy value, and if the timeout was reached, then it will return a falsy value. So, if it takes more than 2 seconds for data to become available wait_readable will return nil, and we print an error message and exit the program.

Calculating CPM

CPM stands for “counts per minute”, meaning the number of ionization events the hardware has detected within one minute. However, the value that we’re reading from the serial port is actually the “counts per second” (or ionization events the hardware detected in the last second). Most of the time that value is 0 so it’s not super fun to read. Lets calculate the CPM and print that instead.

We know the samples are arriving about every second, so I’m just going to modify this code to keep a list of the last 60 samples and just sum those:

require "uart"

MASK = (~(3 << 14)) & 0xFFFF

UART.open ARGV[0], 115200 do |serial|
  # turn on heartbeat
  serial.write "<HEARTBEAT1>>"

  samples = []

  loop do
    if serial.wait_readable(2)
      # Push the sample on the list
      samples.push(((serial.readbyte << 8) | serial.readbyte) & MASK)

      # Make sure we only have 60 samples in the list
      while samples.length > 60; samples.shift; end

      # Print a sum of the samples (if we have 60)
      p CPM: samples.sum if samples.length == 60
    else
      $stderr.puts "oh no, something went wrong!"
      exit(1)
    end
  end
ensure
  # make sure to turn off heartbeat
  serial.write "<HEARTBEAT0>>"
end

Here is the output on my machine:

$ ruby rad.rb /dev/tty.usbserial-111240
{:CPM=>9}
{:CPM=>8}
{:CPM=>8}
{:CPM=>8}
{:CPM=>8}
{:CPM=>9}
{:CPM=>9}
{:CPM=>9}

After about a minute or so, it starts printing the CPM.

Conclusion

I love playing with embedded systems as well as dealing with UART. Next time you need to do any serial port communications in Ruby, UART to consider using my gem. Thanks for your time, and I hope you have a great weekend!

Fast Tokenizers with StringScanner

2023-09-02T13:00:14-07:00

Lately I’ve been messing around with writing a GraphQL parser called TinyGQL. I wanted to see how fast I could make a GraphQL parser without writing any C extensions. I think I did pretty well, but I’ve learned some tricks for speeding up parsers and I want to share them.

Today we’re going to specifically look at the lexing part of parsing. Lexing is just breaking down an input string in to a series of tokens. It’s the parser’s job to interpret those tokens. My favorite tool for tokenizing documents in Ruby is StringScanner. Today we’re going to look at a few tricks for speeding up StringScanner based lexers. We’ll start with a very simple GraphQL lexer and apply a few tricks to speed it up.

A very basic lexer

Here is the lexer we’re going to work with today:

require "strscan"

class Lexer
  IDENTIFIER =    /[_A-Za-z][_0-9A-Za-z]*\b/
  WHITESPACE =  %r{ [, \c\r\n\t]+ }x
  COMMENTS   = %r{ \#.*$ }x
  INT =           /[-]?(?:[0]|[1-9][0-9]*)/
  FLOAT_DECIMAL = /[.][0-9]+/
  FLOAT_EXP =     /[eE][+-]?[0-9]+/
  FLOAT =  /#{INT}#{FLOAT_DECIMAL}#{FLOAT_EXP}|#{FLOAT_DECIMAL}|#{FLOAT_EXP}/

  KEYWORDS = [ "on", "fragment", "true", "false", "null", "query", "mutation",
    "subscription", "schema", "scalar", "type", "extend", "implements",
    "interface", "union", "enum", "input", "directive", "repeatable"
  ].freeze

  KW_RE = /#{Regexp.union(KEYWORDS.sort)}\b/
  KW_TABLE = Hash[KEYWORDS.map { |kw| [kw, kw.upcase.to_sym] }]

  module Literals
    LCURLY =        '{'
    RCURLY =        '}'
    LPAREN =        '('
    RPAREN =        ')'
    LBRACKET =      '['
    RBRACKET =      ']'
    COLON =         ':'
    VAR_SIGN =      '$'
    DIR_SIGN =      '@'
    EQUALS =        '='
    BANG =          '!'
    PIPE =          '|'
    AMP =           '&'
  end

  ELLIPSIS =      '...'

  include Literals

  PUNCTUATION = Regexp.union(Literals.constants.map { |name|
    Literals.const_get(name)
  })

  PUNCTUATION_TABLE = Literals.constants.each_with_object({}) { |x,o|
    o[Literals.const_get(x)] = x
  }

  def initialize doc
    @doc = doc
    @scan = StringScanner.new doc
  end

  def next_token
    return if @scan.eos?

    case
    when s = @scan.scan(WHITESPACE)  then [:WHITESPACE, s]
    when s = @scan.scan(COMMENTS)    then [:COMMENT, s]
    when s = @scan.scan(ELLIPSIS)    then [:ELLIPSIS, s]
    when s = @scan.scan(PUNCTUATION) then [PUNCTUATION_TABLE[s], s]
    when s = @scan.scan(KW_RE)       then [KW_TABLE[s], s]
    when s = @scan.scan(IDENTIFIER)  then [:IDENTIFIER, s]
    when s = @scan.scan(FLOAT)       then [:FLOAT, s]
    when s = @scan.scan(INT)         then [:INT, s]
    else
      [:UNKNOWN_CHAR, @scan.getch]
    end
  end
end

It only tokenizes a subset of GraphQL. Namely, it omits string literals. Matching string literals is kind of gross, and I wanted to keep this example small, so I removed them. I have a large document that I’ll use to measure some performance aspects of this lexer, and if you want to try it out, you can find the document here.

To use the lexer, just pass the document you want to tokenize, then repeatedly call next_token on the lexer until it returns nil:

lexer = Lexer.new input
while tok = lexer.next_token
  # do something
end

GraphQL documents look something like this:

mutation {
  a: likeStory(storyID: 12345) {
    b: story {
      c: likeCount
    }
  }
}

And with this lexer implementation, the tokens come out as tuples and they look something like this:

[:IDENTIFIER, "likeStory"]
[:LPAREN, "("]
[:IDENTIFIER, "storyID"]

Our benchmarking code is going to be very simple, we’re just going to use the lexer to pull all of the tokens out of the test document:

require "benchmark/ips"

def allocations
  x = GC.stat(:total_allocated_objects)
  yield
  GC.stat(:total_allocated_objects) - x
end

def go doc
  lexer = Lexer.new doc
  while tok = lexer.next_token
    # do nothing
  end
end

doc = ARGF.read

Benchmark.ips { |x| x.report { go doc } }
p ALLOCATIONS: allocations { go doc }

With this implementation of the lexer, here are the benchmark results on my machine:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        21.000  i/100ms
Calculating -------------------------------------
                        211.043  (± 0.9%) i/s -      1.071k in   5.075133s
{:ALLOCATIONS=>20745}

We can do a little over 200 iterations per second, and tokenizing the document allocates a bit over 20k objects.

StringScanner context

Before we get to optimizing this lexer, lets get a little background on StringScanner. StringScanner is one of my favorite utilities that ships with Ruby. You can think of this object as basically a “cursor” that points inside a string. When you successfully scan a token from the beginning of the cursor, StringScanner will move the cursor forward. If scanning fails, the cursor doesn’t move.

The inspect method on the StringScanner object makes this behavior very clear, so lets just look at some code in IRB:

>> scanner = StringScanner.new("the quick brown fox jumped over the lazy dog")
=> #<StringScanner 0/44 @ "the q...">
>> scanner.scan(/the /)
=> "the "
>> scanner
=> #<StringScanner 4/44 "the " @ "quick...">
>> scanner.scan(/qui/)
=> "qui"
>> scanner
=> #<StringScanner 7/44 "...e qui" @ "ck br...">
>> scanner.scan(/hello/)
=> nil
>> scanner
=> #<StringScanner 7/44 "...e qui" @ "ck br...">

The @ symbol in the inspect output shows where the cursor currently points, and the ratio at the beginning gives you kind of a “progress” counter. As I scanned through the string, the cursor moved forward. Near the end, you can see where I tried to scan “hello”, it returned nil, and the cursor stayed in place.

Combining StringScanner with the linear case / when in Ruby is a great combination for really easily writing tokenizers.

StringScanner also allows us to skip particular values, as well as ask for the current cursor position:

>> scanner
=> #<StringScanner 7/44 "...e qui" @ "ck br...">
>> scanner.skip(/ck /)
=> 3
>> scanner
=> #<StringScanner 10/44 "...uick " @ "brown...">
>> scanner.skip(/hello/)
=> nil
>> scanner
=> #<StringScanner 10/44 "...uick " @ "brown...">
>> scanner.pos
=> 10

Calling skip will try to skip a pattern. If skipping works, it returns the length of the string it matched, and if it fails, it returns nil. You can also get and set the position of the cursor using the pos and pos= methods.

Now lets try to speed up this lexer!

Speeding up this lexer

The name of the game for speeding up lexers (or really any code) is to reduce the number of method calls as well as the number of allocations. So we’re going to try applying some tricks to reduce both.

Whenever I’m trying to improve the performance of any code, I find it is important to think about the context of how that code is used. For example, our lexer currently yields tokens for comments and whitespace. However, the GraphQL grammar ignores comments and whitespace. Since the parser doesn’t actually need to know about whitespace or comments in order to understand the document, it is fine for the lexer to just skip them.

Our first optimization is to combine the whitespace and comment check, and then quit returning tokens:

diff --git a/test.rb b/test.rb
index 2c1e874..9130a54 100644
--- a/test.rb
+++ b/test.rb
@@ -2,8 +2,12 @@ require "strscan"
 
 class Lexer
   IDENTIFIER =    /[_A-Za-z][_0-9A-Za-z]*\b/
-  WHITESPACE =  %r{ [, \c\r\n\t]+ }x
-  COMMENTS   = %r{ \#.*$ }x
+  IGNORE   =       %r{
+    (?:
+      [, \c\r\n\t]+ |
+      \#.*$
+    )*
+  }x
   INT =           /[-]?(?:[0]|[1-9][0-9]*)/
   FLOAT_DECIMAL = /[.][0-9]+/
   FLOAT_EXP =     /[eE][+-]?[0-9]+/
@@ -51,11 +55,11 @@ class Lexer
   end
 
   def next_token
+    @scan.skip(IGNORE)
+
     return if @scan.eos?
 
     case
-    when s = @scan.scan(WHITESPACE)  then [:WHITESPACE, s]
-    when s = @scan.scan(COMMENTS)    then [:COMMENT, s]
     when s = @scan.scan(ELLIPSIS)    then [:ELLIPSIS, s]
     when s = @scan.scan(PUNCTUATION) then [PUNCTUATION_TABLE[s], s]
     when s = @scan.scan(KW_RE)       then [KW_TABLE[s], s]

By combining the whitespace and comment regex, we could eliminate one method call. We also changed the scan to a skip which eliminated string object allocations. Lets check the benchmark after this change:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        32.000  i/100ms
Calculating -------------------------------------
                        322.100  (± 0.3%) i/s -      1.632k in   5.066846s
{:ALLOCATIONS=>10527}

This is great! Our iterations per second (IPS) went from 211 to 322, and our allocations went from about 20k down to around 10k. So we cut our allocations in half and increased speed by about 50%.

Thinking Bigger

This lexer returns a tuple for each token. The tuple looks like this: [:LPAREN, "("]. But when the parser looks at the token, how often does it actually need the string value of the token?

When the parser looks at the first element, it is able to understand that the lexer found a left parenthesis just by looking at the symbol :LPAREN. The parser gets no benefit from the "(" string that is in the tuple.

Just by looking at the token name, the parser can tell what string the lexer found. This is true for all punctuation, as well as keywords.

Identifiers and numbers are a little bit different though. The parser doesn’t particularly care about the actual string value of any identifier or number. It only cares that an identifier or number was found. However, if we think one level up, it’s quite likely that consumers of the parser will care what field name or number was in the GraphQL document.

Since the parser doesn’t care about the actual token value, but the user does care about the token value, lets split the next_token method in two:

One method to get the token (:INT, :LCURLY, etc)
One method to get the token value

When the parser encounters a token where the token value actually matters, the parser can ask the lexer for the token value. For example, something like this:

lexer = Lexer.new doc
while tok = lexer.next_token
  if tok == :IDENTIFIER
    p lexer.token_value
  end
end

__END__
mutation {
  a: likeStory(storyID: 12345) {
    b: story {
      c: likeCount
    }
  }
}

This split buys us two really big wins. The first is that next_token doesn’t need to return an array anymore. That’s already one object per token saved. The second win is that we only ever allocate a string when we really need it.

Here is the new next_token method, and the token_value helper method:

  def next_token
    @scan.skip(IGNORE)

    return if @scan.eos?

    case
    when @scan.skip(ELLIPSIS)        then :ELLIPSIS
    when s = @scan.scan(PUNCTUATION) then PUNCTUATION_TABLE[s]
    when s = @scan.scan(KW_RE)       then KW_TABLE[s]
    when @scan.skip(IDENTIFIER)      then :IDENTIFIER
    when @scan.skip(FLOAT)           then :FLOAT
    when @scan.skip(INT)             then :INT
    else
      @scan.getch
      :UNKNOWN_CHAR
    end
  end

  def token_value
    @doc.byteslice(@scan.pos - @scan.matched_size, @scan.matched_size)
  end

We’ve changed the method to only return a symbol that identifies the token. We also changed most scan calls to skip calls. scan will return the string it matched (an allocation), but skip simply returns the length of the string it matched (not an allocation).

As the parser requests tokens from the lexer, if it encounters a token where it actually cares about the string value, it just calls token_value. This makes our benchmark a little bit awkward now because we’ve shifted the blame of “identifier” allocations from the lexer to the parser. If the parser wants an allocation, it’ll have to ask the lexer for it. But lets keep pushing forward with the same benchmark (just remembering that once we integrate the lexer with the parser, we’ll have allocations for identifiers).

With this change, our benchmark results look like this:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        35.000  i/100ms
Calculating -------------------------------------
                        360.209  (± 0.6%) i/s -      1.820k in   5.052764s
{:ALLOCATIONS=>1915}

We went from 322 IPS to 360 IPS, and from 10k allocations down to about 2k allocations.

Punctuation Lookup Table

Unfortunately we’ve still got two lines in the tokenizer that are doing allocations:

    when s = @scan.scan(PUNCTUATION) then PUNCTUATION_TABLE[s]
    when s = @scan.scan(KW_RE)       then KW_TABLE[s]

Let’s tackle the punctuation line first. We still extract a string from the scanner in order to do a hash lookup to find the symbol name for the token. We need the string ")" so that we can map it to the symbol :RPAREN. One interesting feature about these punctuation characters is that they are all only one byte and thus limited to values between 0 - 255. Instead of extracting a substring, we can get the byte at the current scanner position, then use the byte as an array index. If there is a value at that index in the array, then we know we’ve found a token.

First we’ll build the lookup table like this:

  PUNCTUATION_TABLE = Literals.constants.each_with_object([]) { |n, o|
    o[Literals.const_get(n).ord] = n
  }

This will create an array. The array will have a symbol at the index corresponding to the byte value of our punctuation. Any other index will return nil. And since we’re only dealing with one byte, we know the maximum value can only ever be 255. The code below gives us a sample of how this lookup table works:

  '()ab'.bytes.each do |byte|
    p PUNCTUATION_TABLE[byte]
  end

The output is like this:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
:LPAREN
:RPAREN
nil
nil

We can use the pos method on the StringScanner object to get our current cursor position (no allocation), then use that information to extract a byte from the string (also no allocation). If the byte has a value in the lookup table, we know we’ve found a token and we can push the StringScanner forward one byte.

After incorporating the punctuation lookup table, our next_token method looks like this:

  def next_token
    @scan.skip(IGNORE)

    return if @scan.eos?

    case
    when @scan.skip(ELLIPSIS)        then :ELLIPSIS
    when tok = PUNCTUATION_TABLE[@doc.getbyte(@scan.pos)] then
      # If the byte at the current position is inside our lookup table, push
      # the scanner position forward 1 and return the token
      @scan.pos += 1
      tok
    when s = @scan.scan(KW_RE)       then KW_TABLE[s]
    when @scan.skip(IDENTIFIER)      then :IDENTIFIER
    when @scan.skip(FLOAT)           then :FLOAT
    when @scan.skip(INT)             then :INT
    else
      @scan.getch
      :UNKNOWN_CHAR
    end
  end

Rerunning our benchmarks gives us these results:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        46.000  i/100ms
Calculating -------------------------------------
                        459.031  (± 1.1%) i/s -      2.300k in   5.011232s
{:ALLOCATIONS=>346}

We’ve gone from 360 IPS up to 459 IPS, and from about 2k allocations down to only 350 allocations.

Perfect Hashes and GraphQL Keywords

We have one more line in our lexer that is allocating objects:

    when s = @scan.scan(KW_RE)       then KW_TABLE[s]

This line is allocating objects because it needs to map the keyword it found in the source to a symbol:

>> Lexer::KW_TABLE["query"]
=> :QUERY
>> Lexer::KW_TABLE["schema"]
=> :SCHEMA

It would be great if we had a hash table that didn’t require us to extract a string from the source document. And that’s exactly what we’re going to build.

When this particular regular expression matches, we know that the lexer has found 1 of the 19 keywords listed in the KW_TABLE, we just don’t know which one. What we’d like to do is figure out which keyword matched, and do it without allocating any objects.

Here is the list of 19 GraphQL keywords we could possibly match:

["on",
 "true",
 "null",
 "enum",
 "type",
 "input",
 "false",
 "query",
 "union",
 "extend",
 "scalar",
 "schema",
 "mutation",
 "fragment",
 "interface",
 "directive",
 "implements",
 "repeatable",
 "subscription"]

StringScanner#skip will return the length of the match, and we know that if the length is 2 we unambiguously matched on, and if the length is 12 we unambiguously matched subscription. So if the matched length is 2 or 12, we can just return :ON or :SUBSCRIPTION. That leaves 17 other keywords we need to disambiguate.

Of the 17 remaining keywords, the 2nd and 3rd bytes uniquely identify that keyword:

>> (Lexer::KW_TABLE.keys - ["on", "subscription"]).length
=> 17
>> (Lexer::KW_TABLE.keys - ["on", "subscription"]).map { |w| w[1, 2] }
=> ["ra", "ru", "al", "ul", "ue", "ut", "ch", "ca", "yp", "xt", "mp", "nt", "ni", "nu", "np", "ir", "ep"]
>> (Lexer::KW_TABLE.keys - ["on", "subscription"]).map { |w| w[1, 2] }.uniq.length
=> 17

We can use these two bytes as a key to a hash table and design a “perfect hash” to look up the right token. A perfect hash is a hash table where the possible keys for the hash are known in advance, and the hashing function will never make a collision. In other words, no two hash keys will result in the same bucket index.

We know that the word we found is one of a limited set, so this seems like a good application for a perfect hash.

Building a Perfect Hash

A perfect hash function uses a pre-computed “convenient” constant that let us uniquely identify each key, but also limit the hash table to a small size. Basically we have a function like this:

def _hash key
  (key * SOME_CONSTANT) >> 27 & 0x1f
end

But we must figure out the right constant to use such that each entry in our perfect hash gets a unique bucket index. We’re going to use the upper 5 bits of a “32 bit integer” (it’s not actually 32 bits, we’re just going to treat it that way) to find our hash key. The reason we’re going to use 5 bits is because we have 17 keys, and 17 can’t fit in 4 bits. To find the value of SOME_CONSTANT, we’re just going to use a brute force method.

First lets convert the two bytes from each GraphQL keyword to a 16 bit integer:

>> keys = (Lexer::KW_TABLE.keys - ["on", "subscription"]).map { |w| w[1, 2].unpack1("s") }
=> [24946, 30066, 27745, 27765, 25973, 29813, 26723, 24931, 28793, 29816, 28781, 29806, 26990, 30062, 28782, 29289, 28773]

Next we’re going to use a brute force method to find a constant value such that we can convert these 16 bit numbers in to unique 5 bit numbers:

>> c = 13
=> 13
?> loop do
?>   z = keys.map { |k| ((k * c) >> 27) & 0x1f }
?>   break if z.uniq.length == z.length
?>   c += 1
>> end
=> nil
>> c
=> 18592990

We start our search at 13. Our loop tries applying the hashing function to all keys. If the hashing function returns unique values for all keys, then we found the right value for c, otherwise we increment c by one and try the next number.

After this loop finishes (it takes a while), we check c and that’s the value for our perfect hash!

Now we can write our hashing function like this:

def _hash key
  (key * 18592990) >> 27 & 0x1f
end

This function will return a unique value based on the 2nd and 3rd bytes of each GraphQL keyword. Lets prove that to ourselves in IRB:

?> def _hash key
?>   (key * 18592990) >> 27 & 0x1f
>> end
=> :_hash
>> keys = (Lexer::KW_TABLE.keys - ["on", "subscription"]).map { |w| w[1, 2].unpack1("s") }
=> [24946, 30066, 27745, 27765, 25973, 29813, 26723, 24931, 28793, 29816, 28781, 29806, 26990, 30062, 28782, 29289, 28773]
>> keys.map { |key| _hash(key) }
=> [31, 5, 3, 6, 14, 1, 21, 29, 20, 2, 18, 0, 26, 4, 19, 25, 17]

We’ll use these integers as an index in to an array that stores the symbol name associated with that particular keyword:

>> # Get a list of the array indices for each keyword
=> nil
>> array_indexes = keys.map { |key| _hash(key) }
=> [31, 5, 3, 6, 14, 1, 21, 29, 20, 2, 18, 0, 26, 4, 19, 25, 17]
>> # Insert a symbol in to an array at each index
=> nil
>> table = kws.zip(array_indexes).each_with_object([]) { |(kw, key),o| o[key] = kw.upcase.to_sym }
=> 
[:INTERFACE,
...

Now we have a table we can use to look up the symbol for a particular keyword given the keyword’s 2nd and 3rd bytes.

Take a breather

I think this is getting a little complicated so I want to step back and take a breather. What we’ve done so far is write a function that, given the 2nd and 3rd bytes of a string returns an index to an array.

Let’s take the keyword interface as an example. The 2nd and 3rd bytes are nt:

>> "interface"[1, 2]
=> "nt"

We can use unpack1 to convert nt in to a 16 bit integer:

>> "interface"[1, 2].unpack1("s")
=> 29806

Now we pass that integer to our hashing function (I called it _hash in IRB):

>> _hash("interface"[1, 2].unpack1("s"))
=> 0

And now we have the array index where to find the :INTERFACE symbol:

>> table[_hash("interface"[1, 2].unpack1("s"))]
=> :INTERFACE

This will work for any of the strings we used to build the perfect hash function. Lets try a few:

>> table[_hash("union"[1, 2].unpack1("s"))]
=> :UNION
>> table[_hash("scalar"[1, 2].unpack1("s"))]
=> :SCALAR
>> table[_hash("repeatable"[1, 2].unpack1("s"))]
=> :REPEATABLE

Integrating the Perfect Hash in to the Lexer

We’ve built our hash table and hash function, so the next step is to add them to the lexer:

  KW_TABLE = [:INTERFACE, :MUTATION, :EXTEND, :FALSE, :ENUM, :TRUE, :NULL,
              nil, nil, nil, nil, nil, nil, nil, :QUERY, nil, nil, :REPEATABLE,
              :IMPLEMENTS, :INPUT, :TYPE, :SCHEMA, nil, nil, nil, :DIRECTIVE,
              :UNION, nil, nil, :SCALAR, nil, :FRAGMENT]

  def _hash key
    (key * 18592990) >> 27 & 0x1f
  end

Remember we derived the magic constant 18592990 earlier via brute force.

In the next_token method, we need to extract the 2nd and 3rd bytes of the keyword, combine them to a 16 bit int, use the _hash method to convert the 16 bit int to a 5 bit array index, then look up the symbol (I’ve omitted the rest of the next_token method):

    when len = @scan.skip(KW_RE) then
      # Return early if uniquely identifiable via length
      return :ON if len == 2
      return :SUBSCRIPTION if len == 12

      # Get the position of the start of the keyword in the main document
      start = @scan.pos - len

      # Get the 2nd and 3rd byte of the keyword and combine to a 16 bit int
      key = (@doc.getbyte(start + 2) << 8) | @doc.getbyte(start + 1)

      # Get the array index
      index = _hash(key)

      # Return the symbol
      KW_TABLE[index]

We know the length of the token because it’s the return value of StringScanner#skip. If the token is uniquely identifiable based on its length, then we’ll return early. Otherwise, ask StringScanner for the cursor position and then use the length to calculate the index of the beginning of the token (remember StringScanner pushed the cursor forward when skip matched).

Once we have the beginning of the token, we’ll use getbyte (which doesn’t allocate) to get the 2nd and 3rd bytes of the keyword. Then we’ll combine the two bytes to a 16 bit int. Finally we pass the int to the hash function and use the return value of the hash function to look up the token symbol in the array.

Let’s check our benchmarks now!

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        46.000  i/100ms
Calculating -------------------------------------
                        468.978  (± 0.4%) i/s -      2.346k in   5.002449s
{:ALLOCATIONS=>3}

We went from 459 IPS up to 468 IPS, and from 346 allocations down to 3 allocations. 1 allocation for the Lexer object, 1 allocation for the StringScanner object, and 1 allocation for ????

Actually, if we run the allocation benchmark twice we’ll get different results:

require "benchmark/ips"

def allocations
  x = GC.stat(:total_allocated_objects)
  yield
  GC.stat(:total_allocated_objects) - x
end

def go doc
  lexer = Lexer.new doc
  while tok = lexer.next_token
  end
end

doc = ARGF.read

Benchmark.ips { |x| x.report { go doc } }
p ALLOCATIONS: allocations { go doc }
p ALLOCATIONS: allocations { go doc }

Output is this:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        46.000  i/100ms
Calculating -------------------------------------
                        465.071  (± 0.6%) i/s -      2.346k in   5.044626s
{:ALLOCATIONS=>3}
{:ALLOCATIONS=>2}

Ruby uses GC allocated objects to store some inline caches. Since it was the first time we called the allocations method, a new inline cache was allocated, and that dinged us. We’re actually able to tokenize this entire document with only 2 allocations: the lexer and the string scanner.

One more hack

Lets do one more trick. We want to reduce the number of method calls the scanner makes as much as we can. The case / when statement in next_token checks each when statement one at a time. One trick I like to do is rearrange the statements so that the most popular tokens come first.

If we tokenize our benchmark program and tally up all of the tokens that come out, it looks like this:

>> lexer = Lexer.new File.read "benchmark/fixtures/negotiate.gql"
=> 
#<Lexer:0x0000000105c33c90
...
>> list = []
=> []
?> while tok = lexer.next_token
?>   list << tok
>> end
=> nil
>> list.tally
=> {:QUERY=>1, :IDENTIFIER=>2976, :LPAREN=>15, :VAR_SIGN=>6, :COLON=>56, :BANG=>1,
    :RPAREN=>15, :LCURLY=>738, :RCURLY=>738, :ELLIPSIS=>350, :ON=>319, :INT=>24,
    :TYPE=>4, :INPUT=>1, :FRAGMENT=>18}

From this data, it looks like ELLIPSIS tokens aren’t as popular as punctuation or IDENTIFIER tokens. Yet we’re always checking for ELLIPSIS tokens first. Lets move the ELLIPSIS check below the identifier check. This makes looking for ELLIPSIS more expensive, but it makes finding punctuation and identifiers cheaper. Since punctuation and identifiers occur more frequently in our document, we should get a speedup.

I applied this patch:

diff --git a/test.rb b/test.rb
index ac147c2..275b8ba 100644
--- a/test.rb
+++ b/test.rb
@@ -59,7 +59,6 @@ class Lexer
     return if @scan.eos?
 
     case
-    when @scan.skip(ELLIPSIS)        then :ELLIPSIS
     when tok = PUNCTUATION_TABLE[@doc.getbyte(@scan.pos)] then
       # If the byte at the current position is inside our lookup table, push
       # the scanner position forward 1 and return the token
@@ -78,6 +77,7 @@ class Lexer
 
       KW_TABLE[_hash(key)]
     when @scan.skip(IDENTIFIER)      then :IDENTIFIER
+    when @scan.skip(ELLIPSIS)        then :ELLIPSIS
     when @scan.skip(FLOAT)           then :FLOAT
     when @scan.skip(INT)             then :INT
     else

Now when we rerun the benchmark, we get this:

$ ruby -I lib test.rb benchmark/fixtures/negotiate.gql
Warming up --------------------------------------
                        48.000  i/100ms
Calculating -------------------------------------
                        486.798  (± 0.4%) i/s -      2.448k in   5.028884s
{:ALLOCATIONS=>3}
{:ALLOCATIONS=>2}

Great, we went from 465 IPS to 486 IPS!

Conclusion

The lexer we started with tokenized the 80kb GraphQL document at 211 IPS, and where we left off it was running at 486 IPS. More than a 2x speed improvement!

Our starting lexer allocated over 20k objects, and when we finished we got it down to just 2 objects. Of course the parser may ask the lexer to allocate something, but we know that we’re only allocating the bare minimum. In fact, if the parser only records positional offsets, it could very well never ask the lexer to allocate anything!

When I’m doing this stuff I try to use as many tricks as possible for increasing speed. But I think the biggest and best payoffs come from trying to think about the problem from a higher level and adjust the problem space itself. Converting next_token to return only a symbol rather than a tuple cut our object allocations by more than half. Questioning the code’s design itself is much harder, but I think reaps a greater benefit.

Anyway, these are hacks I like to use! If you want to play around with the lexer we’ve been building in this post, I’ve put the source code here.

I hope you enjoyed this, and have a good day!

Bitmap Matrix and Undirected Graphs in Ruby

2023-03-19T12:12:27-07:00

I’ve been working my way through Engineering a Compiler. I really enjoy the book, but one part has you build an interference graph for doing register allocation via graph coloring. An interference graph is an undirected graph, and one way you can represent an undirected graph is with a bitmap matrix.

A bitmap matrix is just a matrix but the values in the matrix can only be 1 or 0. If every node in your graph maps to an index, you can use the bitmap matrix to represent edges in the graph.

I made a bitmap matrix implementation that I like, but I think the code is too trivial to put in a Gem. Here is the code I used:

class BitMatrix
  def initialize size
    @size = size
    size = (size + 7) & -8 # round up to the nearest multiple of 8
    @row_bytes = size / 8
    @buffer = "\0".b * (@row_bytes * size)
  end

  def initialize_copy other
    @buffer = @buffer.dup
  end

  def set x, y
    raise IndexError if y >= @size || x >= @size

    x, y = [y, x].sort

    row = x * @row_bytes
    column_byte = y / 8
    column_bit = 1 << (y % 8)

    @buffer.setbyte(row + column_byte, @buffer.getbyte(row + column_byte) | column_bit)
  end

  def set? x, y
    raise IndexError if y >= @size || x >= @size

    x, y = [y, x].sort

    row = x * @row_bytes
    column_byte = y / 8
    column_bit = 1 << (y % 8)

    (@buffer.getbyte(row + column_byte) & column_bit) != 0
  end

  def each_pair
    return enum_for(:each_pair) unless block_given?

    @buffer.bytes.each_with_index do |byte, i|
      row = i / @row_bytes
      column = i % @row_bytes
      8.times do |j|
        if (1 << j) & byte != 0
          yield [row, (column * 8) + j]
        end
      end
    end
  end

  def to_dot
    "graph g {\n" + each_pair.map { |x, y| "#{x} -- #{y};" }.join("\n") + "\n}"
  end
end

I like this implementation because all bits are packed in to a binary string. Copying the matrix is trivial because we just have to dup the string. Memory usage is much smaller than if every node in the graph were to store an actual reference to other nodes.

Anyway, this was fun to write and I hope someone finds it useful!

Vim, tmux, and Fish

2023-01-18T11:23:35-08:00

I do most of my text editing with MacVim, but when I pair with people I like to use tmate. tmate is just an easy way to connect tmux sessions with a remote person. But this means that I go from coding in a GUI to coding in a terminal. Normally this wouldn’t be a problem, but I had made a Fish alias that would open the MacVim GUI every time I typed vim in the terminal. Of course when I’m pairing via tmate, the other people cannot see the GUI, so I would have to remember a different command to open Vim.

Today I did about 10min of research to fix this problem and came up with the following Fish command:

$ cat .config/fish/functions/vim.fish 
function vim --wraps='vim' --description 'open Vim'
  if set -q TMUX # if we're in a TMUX session, open in terminal
    command vim $argv
  else
    # Otherwise open macvim
    open -a MacVim $argv; 
  end
end

All it does is open terminal Vim if I’m in a TMUX session, otherwise it opens the MacVim GUI.

Instead of putting up with this frustration for such a long time, I should have taken the 10 min required to fix the situation. This was a good reminder for me, and hopefully I’ll be better about it in the future!