Time remaining until October 4, 2026 at 01:43 PM Eastern time
--
Days
--
Hours
--
Minutes
--
Seconds
Time is up.
Time remaining until October 4, 2026 at 01:43 PM Eastern time
Time is up.
Like last year, a * indicates I especially enjoyed a book. I’m trying to be a bit more conservative with the * instead of just giving it to every other book, but it’s so hard :)
I am currently reading:
Camera Controls (click game frame)
Q/E - zoom in/out
W/A/S/D - pan
ants-again is an ant pheromone simulation written in Go and compiled for WASM using ebitengine.
The ‘again’ part of the name comes from the fact that this is not my first time attempting to simulate ants in this manner, but it’s the first that I’m happy enough with to share.
Each colored speck moving around the screen represents an ant.
The large white circle in the center represents the hill. And the brown bricks scattered about represent food sources.
If you zoom in a bit (click the game frame, hold Q), you will also notice small fading points left behind by ants of the same color.
These points represent ‘pheromones’ that are left behind by ants, and fade in strength over time, eventually disappearing.
Pheromones are the only thing these simulated ants can sense; they are otherwise ‘blind’ to the world around them. They cannot sense food or the hill directly, and can only interact with them by bumping into them by chance.
ants and some pheromones
Ants have one of two states. They remain in their current state until they accomplish their objective. Foraging ants (green) will become returning ants (lilac) when they encounter food. Returning ants will become foraging ants when they encounter the hill.
Ants drop and sense pheromone according to their state:
This allows ants to work together to discover paths between the hill and food. When a forager finds food, it becomes a returner. The new returner senses pheromone left by other foragers to find its way back to the hill. As it returns to the hill, it leaves behind returning pheromone that the remaining foragers can follow to find the same food it found. As more and more ants discover the same path, the pheromones they leave behind reinforce the path. Since pheromones fade over time, shorter and busier paths get reinforced, while paths left behind by lost ants fade away.
Getting the ants to converge on good paths quickly is a product of several tricks and optimizations. Many of these are inspired by real-world ant behavior.
When an ant senses pheromone, they only consider those in a fairly small area around them. This prevents them from getting distracted by far-away pheromones left by ants collecting other food sources.
In addition, ants are more strongly influenced by nearby pheromones, as well as pheromones that point in a direction more similar to their current heading.
These are fairly important behaviors because of the ‘pheromone gradient’. As a trail left by an ant starts to decay, the gradient points towards the ant. Pheromones left more recently are stronger, those left several seconds ago are almost gone. Another ant following this trail would then be more likely to follow the gradient, but this is not quite the effect that we want. If a forager follows directly behind a returner, they are likely walking towards the hill, not the food source the returner found. The same applies in reverse.
By applying more weight to closer, and more directionally similar pheromones, we make it more likely that an ant follows the trail in the direction we want.
To help ants forget bad paths, each ant has a limited ‘inventory’ of pheromone that they can drop. Once an ant has exhausted their inventory, they can’t drop any more pheromone until they accomplish their goal.
Finding a good balance between pheromone influence, decay, drop rate, and other parameters is challenging. If poorly selected, several pathological outcomes are possible.
If ants are not sensitive enough to pheromones, if pheromones decay too fast, or if ants have a mis-sized sensing radius, it’s possible that they fail to effectively converge on a path. In this case, ants continue to wander aimlessly, only sometimes collecting food by random chance.
The opposite scenario is also possible. If ants are over-influenced by pheromone, they will follow paths too strictly, and fail to discover more optimal paths. An even worse failure mode exists where foraging and returning ants create a circular path that does not pass near food or the hill. In that scenario, they may follow each other in an endless loop and never accomplish their goal. This is largely mitigated by having a reasonably small pheromone inventory, but it is still possible that they discover a very long and inefficient path that eventually does result in food collection.
ebitengine is an extremely minimal game engine. It exposes a simple interface to run and render games that may look familiar if you’ve done some game development before. An ebitengine game implements an interface that includes the methods Update() and Draw(). During Update, the game is expected to advance the simulation forward one step. This method is called by the engine every 1/60th of a second. Likewise, during Draw, the game is expected to render itself to the screen. This is also called every 1/60th of a second.
By separating Update and Draw, we can implement game-logic and rendering separately.
I’ll touch on this first because it’s simpler. My Draw function is implemented as a set of loops that iterate over and draw elements of my game to the screen.
For example, drawAnts:
func (g *Game) drawAnts() {
for _, ant := range g.ants {
// `tail` point 5 units opposite the direction the ant is facing (`ant.dir`)
tail := ant.Add(ant.dir.Normalize().Mul(-5))
// decide what color the ant should be based on ant.state
c := GREEN
if ant.state == RETURN {
c = LILAC
}
// draw a line from ant position to tail.
vector.StrokeLine(
g.world, // "world-space"
float32(ant.X), float32(ant.Y), // from
float32(tail.X), float32(tail.Y), // to
2, c, false) // thickness, color, anti-aliasing
}
}
Food sources and the hill are drawn in a similar manner. Pheromones are a bit different. Because the number of pheromones in the simulation can reach tens-of-thousands depending on parameters, drawing them is performance intensive.
The vector drawing package provided by ebitengine is sufficient for most things, but it requires an engine draw call every time it’s used. For pheromones we instead maintain a buffer representing every game pixel and render them all at once with a single call.
Using this API, each pixel in the game is represented by 4 bytes, one for each color channel (RGBA). If our game world is 1000x1000 pixels, this means our buffer needs to be 1000*1000*4 bytes, or 4MB. Not too bad.
Full disclosure, this was originally implemented with the help of ChatGPT.
func (g *Game) drawPheromones() {
// Clear buffer to black (or background color)
for i := range g.px {
g.px[i] = 0
}
writePheromones := func(ph spatial.Spatial[*Pheromone], color color.RGBA) {
for pher := range ph.PointsIter() {
// Fade color by pheromone amount (0..1)
c := Fade(color, pher.amount)
x := int(pher.X)
y := int(pher.Y)
// don't bother rendering anything outside the bounds of the game
if x < 0 || x >= GAME_SIZE || y < 0 || y >= GAME_SIZE {
continue
}
idx := 4 * (y*GAME_SIZE + x)
g.px[idx+0] = c.R
g.px[idx+1] = c.G
g.px[idx+2] = c.B
g.px[idx+3] = 255 // alpha channel
}
}
writePheromones(g.foragingPheromone, DARK_GREEN)
writePheromones(g.returningPheromone, DARK_LILAC)
// Write the pixel buffer to the ebiten.Image once
g.world.WritePixels(g.px)
}
I also left an unused naiveDrawPheromones function in the source code that is implemented like our other draw functions. It does work well enough for smaller simulation sizes.
I achieved the camera zoom/panning behavior by representing the game as a sub-image. When you adjust the camera, we update the transform applied to the game sub-image before drawing it to the screen. That also makes it easy to draw game elements in “world-space” without worrying about the “screen-space” size changing if I update the resolution or window size of the game.
That’s… pretty much it for rendering.
The Update function takes a similar approach to Draw. Each element of the game has a loop in it that iterates over game elements and advances their state by a step.
func (g *Game) updateAnts() {
for _, ant := range g.ants {
// move the ant forward
ant.Vector = ant.Add(ant.dir.Normalize().Mul(float64(g.params.AntSpeed)))
// prevent the ant from escaping the boundary of the game
keepInbounds(ant)
if util.Chance(g.params.PheromoneSenseProb) {
// ... smell nearby pheromones, update ant.dir ...
}
if ant.state == FORAGE {
// ... do foraging ant stuff, change to returning ant if we bump food ...
}
if ant.state == RETURN {
// ... do returning ant stuff, change to foraging ant if we bump hill ...
}
if ant.pheromoneStored > 0 && util.Chance(g.params.PheromoneDropProb) {
// ... drop some pheromone on the ground
}
// randomly turn a few degrees
ant.dir = ant.dir.Rotate(util.Rand(-g.params.AntRotation, g.params.AntRotation))
}
}
Food, pheromone, and hills are less interesting. If food is exhausted, we remove it from the sim. Pheromone decays a bit each tick, we remove it when it reaches 0. The hill doesn’t even have an update function, it just sits there.
Lots of our game logic relies on us being able to find elements ‘nearby’. With a more heavy-weight game engine, there might be a built-in way to do this, but here we’re on our own. Remember that each tick, an ant needs to sense nearby pheromone and compute the impact on direction. If we have 1000 ants, and 10,000 pheromones, computing that the naive way would require a nested loop with 10,000,000 iterations every tick. That is not feasible if our target is running ~60 ticks per second.
Instead, anything that we need to search an area for is stored in a data structure called a spatial hash. In ants-again, pheromone, food sources, and the hill are all stored in spatial hashes. This data structure allows us to quickly find elements in a given area, without checking every single element.
A spatial hash works by storing elements in a set of ‘cells’. The ‘cell’ that an element belongs to is determined by a hash of its position (x,y coordinates) after dividing by ‘cell size’ and rounding down. If we want to find elements in the spatial hash within a given radius of a point, we only need to search cells that overlap with the circle formed by our point and radius. When we consider a given point, we discard it if the distance is outside of our circle.
source: leetless
When deciding the cell size, there is a performance tradeoff. Choose too large, and you will have to iterate many elements that end up being discarded. Too small, and you have to search many cells. Generally, your cell size should be similar to the size of the queries you expect to be making.
Spatial hashes are just one of many spatial data structures. Each one provides tradeoffs on the performance of inserting, querying, and updating. Early iterations of this project used a KD-Tree instead of a spatial hash, but it proved to be less performant and more complex. The spatial package provides the interface used within the game for interacting with spatial data structures. This makes it possible to experiment with alternative implementations.
type Spatial[T vector.Point] interface {
Insert(p T)
PointsIter() iter.Seq[T]
Remove(p T) T
RadialSearchIter(center vector.Point, radius float64) iter.Seq[T]
Len() int
}
The Go standard-library has a package called "runtime/pprof" that makes it easy to collect pprof profiles to analyze CPU, memory, and traces. go tool pprof can create graphviz files with the -dot flag. I used this pretty extensively to identify CPU hot-spots. Unsurprisingly, garbage collection, and querying our spatial hashes are still by far the most time-consuming parts of our program.
Here is the output from ~30 seconds of simulation. (click to open visualizer)
As mentioned above, there are many tradeoffs to be made that result in vastly different ant behavior. There are many variations that produce stable simulations with different characteristics. It’s possible to create very fast ants that find and forget paths quickly, or slow and steady ants that take a while to converge, but keep finding their way back to a food source until it is exhausted.
I spent a little bit of time trying to automate this fiddling with a rudimentary form of parameter optimization.
Game parameters were factored into a single struct
type Params struct {
AntSpeed float64
AntRotation float64
AntPheromoneStart int
PheromoneSenseRadius float64
PheromoneSenseCosineSimilarity float64
PheromoneDecay float32
PheromoneDropProb float64
PheromoneInfluence float64
PheromoneSenseProb float64
}
Then, we pick random values (within bounds) for each parameter, and run the game for a fixed number of ticks (180 * 60, 3 ‘simulation’ minutes). For this, we can just run Update in a loop as fast as possible, and skip rendering entirely.
Afterwards, we evaluate the performance of the random parameters based on how much food the ants collected. If we beat our previous best score, we output the params. We can run multiple samples for each set of parameters, and test multiple parameters in parallel. Go makes this pretty easy, especially with a little bit of ChatGPT help.
This is essentially a random search of the parameter space. It was useful to find interesting parameter presets, but didn’t produce anything too groundbreaking.
An interesting future project might be applying a more sophisticated “machine-learning” approach here by using something like gradient descent, or ironically enough, ant-colony optimization.
As I mentioned at the start, this wasn’t my first time trying to simulate ants and pheromones. There are a ton of tradeoffs and alternative strategies to choose, and that makes it difficult to find and tune an approach enough to get a stable simulation. A few of those choices include:
In the future, I think it would be neat to include some sliders and dropdowns to alter parameters and behavior of a running simulation.
Those who know me would probably say I’m at least skeptical of AI tools, but ChatGPT was a pretty invaluable source for brainstorming solutions to problems I encountered along the way, and optimizing inefficient code. Other than that, a huge thank you to the implementors of similar projects whose games and code I looked at extensively while creating this project. I’ve tried to include links to all of them below.
Between my new job and my personal life, I didn’t get to do too much programming in my spare time. I did, however, make time for more reading. Rather than trying to provide a review or score, I’ll simply annotate books I especially enjoyed with a *.
I know you all waited with baited breath, so here it is, the short (but slightly longer) list of books I read in 2024!
And I am currently Reading:
Without further ado, behold, the short list of books I read in 2023!
Conway’s Game of Life is a classic cellular automaton. This implementation is written in Rust, rendered using Macroquad, and made available in the browser via WebAssembly.
Without delving too deep, we first need to understand just a bit about the ownership system in Rust. The Rust book has a great summary of the ownership rules that I’ll quote here:
- Each value in Rust has an owner.
- There can only be one owner at a time.
- When the owner goes out of scope, the value will be dropped.
Unlike other languages, in Rust, we cannot have multiple variables that refer directly to the same value. When we assign a new variable to equal an existing value, we give ownership to the new variable, and the old owner ceases to exist.
let a = String::from("hello world!");
let b = a;
// no good, the value pointed to by a was moved to be, a no longer exists
println!("{}", a);
The compiler even gives us a helpful error message showing exactly where our mistake is:
| println!("{}", a);
| ^ value borrowed here after move
One way we can get around this rule is by “borrowing” values instead of “moving” them. When we borrow a value, we get a reference type instead of ownership, which allows us to share our value while still imposing some safety restrictions.
let a = String::from("hello world!");
let b = &a;
let c = &a; // we can make as many immutable borrows as we'd like
// all good! a still exists because it still has ownership over the string,
// b and c are just borrowing it.
println!("{}", a);
println!("{}", b);
println!("{}", c);
Unlike immutable borrows, we can only ever have a single mutable reference to a value at a time.
let mut buffer = String::new();
let shared_1 = &mut buffer;
let shared_2 = &mut buffer; // no good! there is already a mutable borrow of the value
do_something(shared_1); // shared_1 still exists at the point shared_2 is created :(
Our helpful error:
| let shared_1 = &mut buffer;
| ----------- first mutable borrow occurs here
| let shared_2 = &mut buffer;
| ^^^^^^^^^^^ second mutable borrow occurs here
| do_something(shared_1);
| -------- first borrow later used here
Ownership works because the compiler guarantees that a reference cannot outlive its owner, references to values cannot escape the scope of the owning variable. In Go you could write something like this:
var s *string
{
hello := "hello world"
s = &hello
}
fmt.Println(*s)
This works because Go has a garbage collector, there is still a reference to the string despite the original variable going out of scope. In a language like C without a garbage collector, this can create a dangling pointer which can segfault your program at best or create a security vulnerability at worst.
But if we can’t share our references to other scopes, how can we share data in Rust? Especially when we start working with multiple threads, we certainly lose any ability to guarantee our reference doesn’t outlive its owner.
In other languages, using a mutex looks something like this:
// golang:
// acquire a lock on the mutex, blocks until it's our turn
mu.Lock()
// enter the critical section, mutate the shared value
sharedValue.DoSomething()
// release the lock, we're done
mu.Unlock()
Go even provides us the helpful defer keyword which we could use instead to automatically release the lock at the end of the surrounding scope (mu.Lock() followed immediately by defer mu.Unlock()).
This all seems pretty intuitive, but there are a couple of foot-guns lurking here:
In Rust, A mutex owns the data it protects. We can only ever acquire a reference to the data owned by the mutex by locking it. Since the compiler guarantees a reference cannot outlive its owner, we also cannot accidentally allow the value protected by the mutex to outlive the lock. Our go example from above might look something like this.
// locking the mutex gives us access to our shared value
let mut shared_value = mutex.lock().unwrap();
shared_value.do_something();
// no need to unlock, when shared_value leaves scope, the lock is released
So far we’ve been a bit hand-wavy with the details, we’ll use the classic concurrency demo of incrementing a shared counter.
use std::{
sync::{Arc, Mutex},
thread,
};
fn main() {
const THREADS: usize = 10;
const INCREMENTS: usize = 1000;
// Arc = Atomically Reference Counted,
// allows us to share the mutex itself (immutable)
let counter = Arc::new(Mutex::new(0));
// our thread handles
let mut handles = Vec::new();
// spawn multiple threads, share a copy of the mutex to each
for i in 0..THREADS {
let counter_copy = counter.clone();
handles.push(thread::spawn(move || {
let mut locked = counter_copy.lock().unwrap();
println!("{i} grabbed the lock");
for _ in 0..INCREMENTS {
*locked += 1;
}
println!("{i} all done!");
}));
}
for handle in handles {
handle.join();
}
let result = counter.lock().unwrap();
println!("after: {result}");
assert_eq!(10000, *result);
}
Our output looks about as expected, the threads obtain the lock in pseudo-random order and perform their work before releasing. Our final counter value is the sum of all increments, no updates were lost.
0 grabbed the lock
0 all done!
3 grabbed the lock
3 all done!
1 grabbed the lock
1 all done!
2 grabbed the lock
2 all done!
4 grabbed the lock
4 all done!
6 grabbed the lock
6 all done!
7 grabbed the lock
7 all done!
8 grabbed the lock
8 all done!
9 grabbed the lock
9 all done!
5 grabbed the lock
5 all done!
after: 10000
This all looks familiar if you’ve written any concurrency-related code in a language like Java or Go. That’s a good thing! Rust can already be difficult to learn, but here you get to apply a fairly ubiquitous pattern of concurrency and locking, just without all the risks you normally undertake when working with multiple threads.
The last aspect of Rust mutexes I want to touch on is composability. Because a Rust mutex gives you a reference to the owned data, I find it easier to compose functions that use it. Let’s write some pseudo-code demonstrating typical mutex usage in another language:
struct Balances {
mu sync.Mutex
accounts map[string]int
}
func Deposit(account, amt) error {
mu.Lock()
defer mu.Unlock()
// ... do some validation
accounts[account] += amt
return nil
}
func Withdraw(account, amt) error {
mu.Lock()
defer mu.Unlock()
// ... do some validation
accounts[account] -= amt
return nil
}
We have a structure that contains both the mutex as well as the data it protects. We have some functions that acquire the lock, and perform some work on the data. The problem arises when we want to start composing these functions together, say we want to implement a transfer function, we’ll write some pseudo-code with potential implementations:
func Transfer(from, to, amt) {
Withdraw(from, amt)
Deposit(to, amt)
}
This is no good! Withdraw and Deposit acquire the lock independently, meaning we have to acquire it twice to process and Transfer, another concurrent caller could acquire the lock between our 2 functions moving our data into an invalid state after we’ve already performed half the transaction. Acquiring the lock in Transfer instead would cause a deadlock, since we also need to acquire the lock for Withdraw and Deposit.
We could refactor our code to take the lock outside of all of these functions, and assume we’re already holding it during the actual mutation, but doing so in a language like go makes it easy for us to introduce some of the bugs we talked about earlier.
func Transfer(from, to, amt) {
mu.Lock()
defer mu.Unlock()
// these "internal" functions must assume they already have the lock,
// but nothing actually enforces that!
withdrawInternal(from, amt)
depositInternal(to, amt)
}
Now we’ve introduced a lot of complexity over whose job it is to acquire and release the lock, and where it’s safe to assume the lock is held. Enforcing that usages of these functions actually acquire the lock to protect their data is entirely the responsibility of the programmer, there isn’t any real relationship between the mutex and data other than the fact that they are in the same struct. Even with proper acquisition, it’s easy to make mistakes like passing the map to another thread that might outlive the scope in which we have the lock.
Rust protects us from all these mistakes, we can apply the same pattern, locking our Mutex outside of our business logic, and assuming we have it inside. The difference is that Rust will never allow us to access the data without first acquiring the lock, and since the lock is held for the lifetime of the reference, the data can never escape the scope of the lock.
struct Balances {
accounts: Arc<Mutex<HashMap<String, i32>>>,
}
impl Balances {
pub fn deposit(&self, account: &str, amt: i32) {
let mut accounts = self.accounts.lock().unwrap();
Balances::deposit_internal(&mut accounts, account, amt)
}
pub fn withdraw(&self, account: &str, amt: i32) {
let mut accounts = self.accounts.lock().unwrap();
Balances::withdraw_internal(&mut accounts, account, amt)
}
pub fn transfer(&self, from: &str, to: &str, amt: i32) {
let mut accounts = self.accounts.lock().unwrap();
Balances::withdraw_internal(&mut accounts, from, amt);
Balances::deposit_internal(&mut accounts, to, amt)
}
fn deposit_internal(accounts: &mut HashMap<String, i32>, account: &str, amt: i32) {
// we have a mutable reference to accounts, therefore it must
// be an exclusive reference due to Rusts ownership rules!
*accounts.get_mut(account).unwrap() += amt;
}
fn withdraw_internal(accounts: &mut HashMap<String, i32>, account: &str, amt: i32) {
// same assumption as deposit_internal
*accounts.get_mut(account).unwrap() -= amt;
}
}
Because of Rusts compile-time enforcement of ownership and borrowing rules, we know that our “internal” functions must have exclusive access to the hashmap, and therefore are always safe to mutate it. Rust mutexes make it much easier to write composable code without introducing nasty concurrency bugs that are possible in other languages.
If you’ve made it this far, I hope I’ve convinced you to give Rust a try!
Previously, we produced a Brainfuck compiler called Brainfrick-rs that worked much like a traditional compiler, creating a pipeline that parsed, optimized, and executed code on a virtual machine. Here is a rough diagram of the process that we used to execute brainfuck from our source file.
We spent a whole lot of time analyzing common patterns of brainfuck code to find opportunities to optimize. By applying all these neat little tricks, we were able to drive down the runtime of our sample programs more and more.
Just for reference, our most intensive brainfuck program was mandelbrot.bf, a nearly 12,000 instruction long program that produced a mandelbrot fractal using ASCII characters. By applying our optimizer pipeline to our brainfuck instructions, our compiler was able to speed up the runtime of the program from about 13.2 to 4.3 seconds on my machine with the most recent version. All told, brainfrick-rs is a fairly modest ~750 lines of code. While we could certainly keep improving performance with new clever optimizers and careful profiling, we are already reaching the limits of what could be squeezed out of our VM implementation.
Instead, we will take a different approach: leveraging one of the most powerful compilers in the world to execute mandelbrot.bf in less than 1 second with about 100 lines of code.
Metaprogramming is a programming strategy that allows one program to read, modify, or generate another. There are many fantastic examples of metaprogramming that you have likely heard of or maybe even used, code generation being of the the most prevalent. DSLs like lex and yacc utilize code generation to create complex programs like parsers from simpler representations, and Google’s Protobuf IDL can generate clients and servers in many different languages to facilitate interoperability between services.
While metaprogramming exists in many different forms, one of the first that programmers are often exposed to is the Macro. Macros allow the programmer to specify a pattern of characters or tokens that should be replaced by another. These macros are often processed or “expanded” during the pre-processor phase of the compiler, making them different than something like a function call. In the final program, there is no macro, just the expanded code.
For example, here is a simple C program that defines a macro to add two numbers.
main.c#include <stdio.h>
#define ADD(X, Y) ((X) + (Y))
int main() {
int x = 5;
int y = 10;
int result = ADD(x, y);
printf("%d + %d = %d\n", x, y, result);
return 0;
}
To make the difference between this macro and a function more apparent, we can take a look at the expanded C code using the Godbolt Compiler Explorer and adding the -E flag to gcc.
expanded main.c// ... trimmed ...
int main() {
int x = 5;
int y = 10;
int result = ((x) + (y));
printf("%d + %d = %d\n", x, y, result);
return 0;
}
When the macro was expanded, the resulting code was placed directly in the code where the macro was used. Unlike a function we are not “calling” the macro or passing x and y to a new stack frame, we replace the macro with the resulting code.
When programming in Rust, macros are introduced very early. When creating a new Rust project with cargo new, the default main.rs file looks like this:
main.rsfn main() {
println!("Hello, world!");
}
Here’s our first macro: println!.
Rust does not support variadic functions, that is, functions that take a variable number of arguments like Varargs in Java or params in C#. Rust could’ve instead defined println as a function that takes in a slice of &str, something like fn println(args: &[&str]), but what if we want to print non-string arguments? Things would get cumbersome fast, probably not a great impression for a hello world program.
Instead Rust’s println is a declarative macro that operates on a series of TokenTree, nodes directly from Rust’s AST. The macro hides the ugly details of formatting our arguments and outputting the result to stdout, while also giving us a convenient API.
Some other Rust macros you’re likely to come up against are vec!, assert!, panic!, and cfg!. While we won’t cover them in this article, Rust also supports Prodedural Macros which allow you to write more complex, imperative code that also operates on Rust AST nodes. You’ve probably seen the #[Derive(...)] attribute which allows you to automatically implement traits like Clone, Debug, Copy, and more for structs automatically. This works by generating the associated trait implementation in a procedural macro.
Much like our C example, we can write a simple Rust macro to add two numbers.
macro_rules! add {
($lhs:expr, $rhs:expr) => {
$lhs + $rhs
};
}
fn main() {
let x = 5;
let y = 10;
let result = add!(x, y);
}
macro_rules! is used to start the definition of a macro, like #define in C. Rust macros work by defining a set of rules to match the program AST, and the corresponding output. Here we define a single rule, ($lhs:expr, $rhs:expr). This rule matches a node of type expr, and binds it to the metavariable $lhs, which we can use later to refer to it. Likewise, it matches a second expr that we bind to $rhs. Now we define to body of the rule, which specifies how to expand the macro if we’ve found a match. Here, $lhs + $rhs expands the macro by placing a + between our 2 matched expressions. Jumping back to godbolt, we can view the expanded Rust program to see our macro in action.
// expanded
fn main() {
let x = 5;
let y = 10;
let result = x + y;
}
Notice, our macro rule specified expr as the AST node to match, this means we could pass any valid Rust expression to our macro, and the rule would match. Rust macros can go beyond matching a simple expression, there are a whole set of fragment-specifiers we can use to match Rust code. Macrofrick, our new brainfuck compiler, will leverage the tt fragment to match Rust code at the token level.
The last bit of Rust Macro basics we need to cover before moving onto macrofrick is repetition. One of the first justifications we gave for using macros over functions in Rust is the ability to use macros as variadic functions. A naive approach would be to just add rules to our macro to support more and more arguments, for example, our add macro could become
macro_rules! add {
($e1:expr, $e2:expr) => {
$e1 + $e2
},
($e1:expr, $e2:expr, $e3:expr) => {
$e1 + $e2 + $e3
},
($e1:expr, $e2:expr, $e3:expr, $e4:expr) => {
$e1 + $e2 + $e3 + $e4
},
// and on and on and on...
}
But this is pretty repetitive and unmaintainable. It also means that our macro would only support as many arguments as we write rules for.
Instead, we can use a repetition that matches multiple repeated fragments of code. We can define a group of tokens, and optional separator, and a repetition type (+, *, or ?).
Repetition types probably look familiar if you’ve written and Regex before, and they carry much the same meaning
*: 0 or more times+: 1 or more times?: 0 or 1 timesWe can then refer to the metavariables in our expansion to repeatedly expand based on how many times we matched.
Now we can rewrite our add macro to be truly variadic and concise.
macro_rules! add {
// an expression, followed by a comma,
// followed by 1 or more expressions,
// separated by commas
($first:expr, $( $rest:expr ),+ ) => {
// expand into the first expression,
// followed by a plus and the next expression,
// as many times as we matched
$first $( + $rest )+
}
}
fn main() {
let x = 5;
let y = 10;
let z = 123;
let result = add!(x, y, z, 3 + 8, -1);
}
Which expands into:
// expanded
fn main() {
let x = 5;
let y = 10;
let z = 123;
let result = x + y + z + (3 + 8) + -1;
}
If you want to learn more about Rust macros, Macrokata is a fantastic set of tutorials and exercises. I was able to write macrofrick before I even finished them all.
In our original Brainfuck article, we discussed the equivalencies between brainfuck instructions, and lines of C code. The table in that article gives a possible C implementation for all 8 of brainfucks instructions.
We are going to expand (pun intended) upon that idea by using Rust macros to translate brainfuck instructions directly into Rust a valid Rust program.
Lets start with matching. Like we mentioned above, we will use the tt fragment to match individual Rust tokens. Fortunately, all 8 brainfuck instructions are also valid Rust tokens. A valid Brainfuck program is made up of 0 or more instructions, so lets write a macro rule that matches exactly that.
main.rsmacro_rules! frick {
( $( $code:tt )* ) => {
// todo: expand our tokens
};
}
We used the * repetition type, which means we will match 0 or more tt. Before we start expanding our tokens, we need to set up the pointer and memory used by the brainfuck program. We can simply do this at the start of our expansion, by just including the following 2 lines.
main.rsmacro_rules! frick {
( $( $code:tt )* ) => {
let mut mem: [u8; 30_000] = [0; 30_000];
let mut ptr = 0;
// todo: expand our tokens
};
}
Like brainfrick-rs, we use a default of 30,000 cells of type u8, a single byte.
A quick note about macro hygiene. Because macros can expand to arbitrary code, it’s theoretically possible for the developer of a macro to accidentally shadow or capture a variable used elsewhere in the program.
Imagine we wrote a macro like this:
macro_rules! count_to_5 {
() => {
let mut i = 1;
while i <= 5 {
println!("{}", i);
i += 1;
}
};
}
Here we declare and modify a variable, i in our macro, but what if i was already defined in the surrounding scope. Depending on i’s type, we could cause a variety of problems. If i was perhaps a string, our program would likely just fail to compile, since after the macro was executed, i would now refer to a numeric type, where we were expecting a string. Even worse, if i was already a number, we now just unpredictably changed the value of i which would be incredibly hard to debug because it depends on how the macro developer decided to name their variables.
Lets try running some code and see if Rust suffers from this problem
let i = "I love macro hygiene";
count_to_5!();
println!("{}", i);
$ cargo run main.rs
1
2
3
4
5
I love macro hygiene
Woah! Rust saved us here. Rust uses hygienic macros which means macros cannot refer to variables from other scopes. The i inside the macro expansion is different than the one we defined in main.
While is is awesome in the general case, it also means that we’ll have to do some extra work to refer to mem and ptr in our next macro, instr!
Now that we have our brainfuck tape set up, and a way to match our instructions, we need to start expanding them into equivalent Rust code. To do this we’ll create another macro called instr! that matches a single tt and expands into Rust. Because of the macro hygiene rules we discussed above, we cannot refer to mem and ptr directly in instr!, since they are defined in frick!’s scope.
To get around this, we can add metavariables for them in instr!’s rules, so that we can essentially pass them into our expansion.
Each rule for instr! will look something like this
($mem:ident $ptr:ident /* THE TOKEN WE WANT TO MATCH */ ) => {
// ... expansion ...
}
The ident fragment specifier means the rule wants to match an identifier, like a variable name. We can write our instr! macro, and call it from frick! with mem and ptr used to match the first 2 metavariables.
main.rsmacro_rules! instr {
($mem:ident $ptr:ident /* THE TOKEN WE WANT TO MATCH */) => {
// ... expansion ...
},
($mem:ident $ptr:ident /* THE TOKEN WE WANT TO MATCH */) => {
// ... expansion ...
},
($mem:ident $ptr:ident /* THE TOKEN WE WANT TO MATCH */) => {
// ... expansion ...
},
// and on and on for each different brainfuck instruction token
}
frick! now becomes:
main.rsmacro_rules! frick {
( $( $code:tt )* ) => {
let mut mem: [u8; 30_000] = [0; 30_000];
let mut ptr = 0;
// invoke instr! for each repetition of $code
$(
instr!(mem ptr $code);
)*
};
}
Now for the easy part, we can just fill in the expansion for each token and rule in accordance with our table from the last article.
main.rsmacro_rules! instr {
($mem:ident $ptr:ident >) => {
// >
$ptr += 1;
};
($mem:ident $ptr:ident <) => {
// <
$ptr -= 1;
};
($mem:ident $ptr:ident +) => {
// +
$mem[$ptr] = $mem[$ptr].wrapping_add(1);
};
($mem:ident $ptr:ident -) => {
// -
$mem[$ptr] = $mem[$ptr].wrapping_sub(1);
};
($mem:ident $ptr:ident .) => {
// .
print!("{}", $mem[$ptr] as char);
};
($mem:ident $ptr:ident ,) => {
// ,
$mem[$ptr] = std::io::stdin()
.bytes().next().unwrap().unwrap();
};
($mem:ident $ptr:ident [ $( $body:tt )* ]) => {
// [ CODE ]
while $mem[$ptr] > 0 {
$(
instr!($mem $ptr $body);
)*
}
};
}
All of these are quite obvious except for the last rule. The Rust tokenizer recognizes anything between ()s, []s, and {} as a single tt. This means we need to match this tt explicitly, which means we can’t just have a rule for [ that expands to while $mem[$ptr] > 0 { and trust that the following instructions will close our brace at some point. Instead we match [, followed by any number of tokens inside the braces $( $body:tt )*, followed by a closing ] as a single tt. Then we just expand the entire loop at once, recursively calling our instr! macro on the tokens in our loop. This also has a side effect of validating that our braces match for us, if they don’t, the code will fail to compile, because there will be no matching rule for a lonely [ or ].
So far we’ve written a macro to match brainfuck instructions, set up memory and a pointer for our program, and written rules to expand instructions into valid Rust. We need to add a couple last little tricks before we’re ready to break any speed records.
Much like we saw with our loop rule, the Rust language’s Tokenizer recognizes a handful of other common Brainfuck instruction combinations as a single token. Namely >>, <<, .., ..., ->, and <-. This means that if we call our macro with something like this: frick!(>>), we’ll get a compiler error because Rust looks for a rule matching the single token >> instead of > twice. We can get around this limitation quite easily by just adding additional rules for each of these multi-character tokens to decompose them into their individual instructions.
Here are a few of them
main.rs// ...
($mem:ident $ptr:ident >>) => {
$ptr += 2;
};
($mem:ident $ptr:ident ..) => {
let c = $mem[$ptr] as char;
print!("{}{}", c, c);
};
($mem:ident $ptr:ident ->) => {
instr!($mem $ptr -);
instr!($mem $ptr >);
};
As you can see, we have the option of just implementing the expansion as a single statement (as we did with >>), or just deferring to instr! for each instruction (like ->).
Almost time to knock your socks off, just 2 more rules, I promise.
One common brainfuck pattern that we saw in brainfrick-rs was the clear loop: [-]. The clear loop is a set of 3 brainfuck instructions that repeatedly decrements the current cell until it reaches 0. We optimized this pattern in brainfrick-rs by replacing these 3 instructions with a special case Clear instruction to immediately set the current cell to 0 without looping. We can do the same in macrofrick by adding a special rule for it.
main.rs($mem:ident $ptr:ident [-]) => {
// [-]
$mem[$ptr] = 0;
};
Nice.
Lastly, the brainfuck specification dictates that non-brainfuck instruction characters should be ignored and treated as comments. We can include a final rule at the bottom of instr! to match anything else and expand to nothing.
main.rs($mem:ident $ptr:ident $other:tt) => {
// * poof! *
};
Lets test everything out with our classic brainfuck “Hello World!”, we’ll include a few brainfuck comments in our code to be sure we ellide them correctly.
main.rs// macros defined above!
fn main() {
frick!([ignore me please ]++++++++[>++++[>++>+++>middle of the loop+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.);
}
$ cargo run
Hello World!
Nice 😎
At first glance, it might seem like this implementation should be slower than brainfrick-rs, after all, we’ve only implemented one of the many optimizations that our first compiler had. On the surface, this would be right, however, we now have a different optimizer coming into play:
The Rust Compiler Itself.
Since our macro expands into valid Rust code, we’re just compiling and running Rust in the end, here is a truncated expansion of our “Hello World!”.
expanded main.rs
fn main() {
let mut mem: [TCell; 30_000] = [0; 30_000];
let mut ptr = 0;
while mem[ptr] > 0 { }; // our first comment, empty loop
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
while mem[ptr] > 0 {
ptr += 1;
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
while mem[ptr] > 0 {
ptr += 1;
// ... and on and on ...
This means that by compiling in release mode, we’ll get the benefits from any optimizations Rust performs itself.
One great way this benefits us is compile-time evaluation of constant expressions. The Rust compiler is smart enough to combine repetitive code into single instructions. For example, the following code increments the current cell 7 times, 7 brainfuck instructions, 7 lines of Rust.
frick!(+++++++);
// expanded
let mut mem: [TCell; 30_000] = [0; 30_000];
let mut ptr = 0;
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
mem[ptr] = mem[ptr].wrapping_add(1);
But when we look at the corresponding asm in Godbolt for these instructions:
mov byte ptr [rsp], 7
We see that we stored 7 in the cell with a single mov. In brainfrick-rs, we performed such optimizations by hand, but here we get optimization for free alongside any others that the compiler pipeline performs on Rust code.
So without further ado, let’s compile the entire Mandelbrot program in release mode and see how we do:
main.rs// macros defined above!
fn main() {
frick!(+++++++++++++[->++>>>+++++>++>+<<< /* ... snip ... */ );
}
$ cargo build --release
$ time cargo run --release
real 0m1.166s
user 0m0.000s
sys 0m0.000s
🚀
Not bad, but I know what you must be thinking, I promised you we’d get to under a second, and don’t you worry, because that’s where we’re headed.
While Rust is heralded for it’s performance and safety, we can squeeze even more juice out of our compiler by forgoing the safety aspect. Like other memory-safe languages, Rust provides automatic bounds checking on arrays. Unlike C, if you try to reach beyond the bounds of an array in Rust, you’ll get a runtime panic, because the Rust compiler inserts instructions to ensure you’re always accessing a valid index. Modern compilers and CPUs can make the impact of these checks nearly negligible, but if speed is the name of the game, we can forgo them all together. Maybe don’t write any banking or aerospace software with my brainfuck compiler.
We’ll add 2 more macros just to make our code prettier, they make use of the unsafe array methods get_unchecked and get_unchecked_mut.
branch:unsafe main.rsmacro_rules! get {
($mem:ident $ident:ident) => {
$mem.get_unchecked($ident)
};
}
macro_rules! set {
($mem:ident $ident:ident $value:expr) => {
*$mem.get_unchecked_mut($ident) = $value
};
}
Now we amend our rules to make use of these anywhere we index into mem.
branch:unsafe main.rs// ... snip ...
unsafe {
$(
instr!(mem ptr $code);
)*
}
// ... snip ...
($mem:ident $ptr:ident +) => {
// +
set!($mem $ptr get!($mem $ptr).wrapping_add(1))
};
($mem:ident $ptr:ident -) => {
// -
set!($mem $ptr get!($mem $ptr).wrapping_sub(1))
};
($mem:ident $ptr:ident .) => {
// .
print!("{}", *get!($mem $ptr) as char);
};
($mem:ident $ptr:ident ,) => {
// ,
let c = std::io::stdin()
.bytes().next().unwrap().unwrap();
set!($mem $ptr c);
};
($mem:ident $ptr:ident [ $( $body:tt )* ]) => {
// [ CODE ]
while *get!($mem $ptr) > 0 {
$(
instr!($mem $ptr $body);
)*
}
};
// ... snip ...
$ cargo build --release
$ time cargo run --release
real 0m0.818s
user 0m0.000s
sys 0m0.000s
🚀⚡⏩
…and whatever other emojis you associate with speed
]]>
Sefarim is a web application created using Django and Boostrap with a focus on ease of use and simplicity.
]]>About a year ago, I posted an article where I used Github Copilot to see if a student could theoretically use it to complete homework assignments. Github Copilot is an AI-based autocomplete tool that can write code in many languages based on comments and context from surrounding code. Copilot is developed by GitHub and OpenAI and is based on the GPT-3 language model.
ChatGPT is a new GPT-3 based AI tool also created by OpenAI that is aimed at providing even more functionality for a wider range of tasks. Today, we’ll see how far AI tooling has come by tackling the same problem, LetterInventory, the first homework assignment in the University of Washington’s CSE 143 course. You can take a look at last years article on Copilot for some more context on the assignment and it’s goals.
ChatGPT provides a chat-like interface in which you “talk” with the AI. Each query you provide is met with a response from the AI in about 5-10 seconds. Here’s a quick example, this is a real excerpt from ChatGPT:
Me: Knock knock
ChatGPT: Who’s there?
Me: boo
ChatGPT: Boo who?
Me: Why are you crying?
ChatGPT: I am a machine learning model and do not have the ability to cry. I am programmed to assist with providing information and answering questions to the best of my knowledge. Is there something I can help you with?
Charming.
Before we start our assignment, let’s try some simple code samples like we did with Copilot. Whereas Copilot worked as a VSCode extension, the conversational model of ChatGPT allows you to elaborate on previous queries and responses to refine the AI’s results. Quotes may be truncated for this article.
Me: Write a function in python to reverse a string
ChatGPT: Here is one possible implementation of a function that reverses a string in Python:
def reverse_string(string):
return string[::-1]
This function takes a string as input and returns a new string that is the reverse of the original string. It does this by using slicing to extract all the characters in the string in reverse order and then concatenating them together to form the new string. Here is an example of how you could use this function:
input_string = "Hello, world!"
reversed_string = reverse_string(input_string)
print(reversed_string) # Output: "!dlrow ,olleH"
I hope this helps! Let me know if you have any questions.
We can refine our results with further queries:
Me: add some comments and type hints to the function
ChatGPT:
def reverse_string(string: str) -> str:
"""
Reverses a given string.
Args:
string (str): The string to be reversed.
Returns:
str: The reversed string.
"""
# Use slicing to reverse the string and return the result
return string[::-1]
Lets change the requirements and see how it adapts:
Me: I change my mind, I want the function in Rust instead
ChatGPT:
fn reverse_string(string: &str) -> String {
// Create a mutable string to hold the reversed string
let mut reversed = String::new();
// Iterate over the characters in the string in reverse order
for character in string.chars().rev() {
// Push each character onto the mutable string
reversed.push(character);
}
// Return the reversed string
reversed
}
Last time, I wanted to see how little code I could get away with writing, instead relying on copilot and comments as much as possible. In the Copilot article, I wrote the class definition, method headers, and comments for each method. I also had to prod Copilot once or twice when it got stuck.
Today I’ll just be copy-pasting the entire spec at once and seeing what comes out:
Me: Help me complete this assignment in Java, respond with just a single code block, don’t include any additional explanations:
In this programming assignment you will practice using arrays and classes. You are to implement a class called LetterInventory that can be used to keep track of an inventory of letters of the alphabet. The constructor for the class takes a String and computes how many of each letter are in the String. This is the information the object keeps track of (how many a’s, how many b’s, etc). It ignores the case of the letters and ignores anything that is not an alphabetic character (e.g., it ignores punctuation characters, digits and anything else that is not a letter). Your class should have the following public methods. Method Description LetterInventory(String data) Constructs an inventory (a count) of the alphabetic letters in the given string, ignoring the case of letters and ignoring any non-alphabetic characters. int get(char letter) Returns a count of how many of this letter are in the inventory. Letter might be lowercase or uppercase (your method shouldn’t care). If a nonalphabetic character is passed, your method should throw an IllegalArgumentException. … (truncated) …
This is just ~4000 characters directly from the assignment PDF as well as some extra instructions about formatting.
And here is the result…
ChatGPT:
public class LetterInventory {
private int[] counts;
private int size;
private static final int NUM_LETTERS = 26;
public LetterInventory(String data) {
counts = new int[NUM_LETTERS];
size = 0;
data = data.toLowerCase();
for (int i = 0; i < data.length(); i++) {
char c = data.charAt(i);
if (c >= 'a' && c <= 'z') {
counts[c - 'a']++;
size++;
}
}
}
public int get(char letter) {
if (letter >= 'a' && letter <= 'z' || letter >= 'A' && letter <= 'Z') {
return counts[Character.toLowerCase(letter) - 'a'];
}
throw new IllegalArgumentException();
}
public void set(char letter, int value) {
if (letter >= 'a' && letter <= 'z' || letter >= 'A' && letter <= 'Z') {
size -= counts[Character.toLowerCase(letter) - 'a'];
counts[Character.toLowerCase(letter) - 'a'] = value;
size += value;
if (value < 0) {
throw new IllegalArgumentException();
}
} else {
throw new IllegalArgumentException();
}
}
public int size() {
return size;
}
public boolean isEmpty() {
return size == 0;
}
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append('[');
for (int i = 0; i < NUM_LETTERS; i++) {
for (int j = 0; j < counts[i]; j++) {
sb.append((char)('a' + i));
}
}
sb.append(']');
return sb.toString();
}
public LetterInventory add(LetterInventory other) {
LetterInventory sum = new LetterInventory("");
for (int i = 0; i < NUM_LETTERS; i++) {
sum.counts[i] = this.counts[i] + other.counts[i];
}
sum.size = this.size + other.size;
return sum;
}
public LetterInventory subtract(LetterInventory other) {
LetterInventory diff = new LetterInventory("");
for (int i = 0; i < NUM_LETTERS; i++) {
diff.counts[i] = this.counts[i] - other.counts[i];
if (diff.counts[i] < 0) {
return null;
}
}
diff.size = this.size - other.size;
return diff;
}
}
This looks… good!
Let’s write a quick sanity check to make sure this compiles and some of the methods works:
public class Main {
public static void main(String[] args) {
LetterInventory inventory = new LetterInventory("ChatGPT wuz here! :)");
System.out.println(inventory.toString()); // [aceeghhprttuwz]
inventory.set('x', 5);
LetterInventory other = inventory.subtract(new LetterInventory("ee"));
System.out.println(other); // [acghhprttuwxxxxxz]
}
}
Let that sink in for a minute… I didn’t write a single line of code for this assignment, I just pasted the spec into a free online tool and compiled the result. Like we saw with our warmup example, I could always elaborate to get ChatGPT to add comments, write unit tests, and make other modifications to satisfy any other constraints of the assignment.
This is incredible to me. Especially considering it uses the same language model as Copilot, the advancement made in the past year just shows how quickly the field of AI is progressing. Just like our Copilot exercise, it raises even more pressing questions about academic integrity. This model is not limited to coding either, I’ve successfully gotten it to produce satisfactory answers to all sorts of “homework” questions like:
ln(x - 1) / x^2.In fact, ChatGPT generated some of those questions as well, I’ll let you guess which.
Lets see what ChatGPT thinks about itself:
Me: What are some pros and cons of AI assistants, format the response as a table.
ChatGPT: Here are some pros and cons for AI-based assistants:
Pros Cons - Can perform tasks quickly and accurately - May not understand complex or abstract tasks - Can operate 24/7 without needing breaks or vacation time - May not be able to handle unexpected situations or problems outside of its programmed capabilities - Can provide personalized experiences by learning an individual’s preferences and habits - May not be able to replicate the intuition, creativity, or empathy of a human - Can improve over time as it processes more data and becomes more sophisticated - May be expensive to develop and maintain, depending on the complexity of the AI and the amount of data it needs to process - Can reduce the need for human labor, potentially leading to cost savings for businesses - May raise ethical concerns, such as the potential for AI to displace human workers or the fear that AI could become too advanced and potentially pose a threat to humanity
I guess we can even outsource ethics to AI now ;)
I’ll leave you with this Haiku, courtesy of ChatGPT, and an accompanying painting by OpenAI’s DALLE-E 2
The ocean’s depths blue
Waves crash against the shoreline
My heart is at peace.
