DEV Community: Alexander Przemysław Kamiński

Elegant Rust with proc macros

Alexander Przemysław Kamiński — Thu, 02 Apr 2026 13:04:44 +0000

When writing immediate mode (egui) applications it comes to me quickly that nigh all logic computations should be done off the UI thread. There are many ways to approach it, however as a fan of event-based systems sooner or later I implement some kind of event handling. The pattern is almost the same with minor differences and looks like this:

#[derive(Clone)] pub struct ProcessorConfig { pub id: String }
#[derive(Clone)] pub struct TaskResult { pub success: bool }
pub struct State { pub active_tasks: Vec<u32> }

#[derive(Clone)]
pub enum Event {
  ProcessorStart { config: ProcessorConfig },
  ProcessorStop,
  LongRunningTask { id: u32 },
  LongRunningTaskComplete { task_result: TaskResult },
}

struct EventHandler {
  state: Arc<RwLock<State>>,
  tx: tokio::mpsc::Sender<Event>,
}

impl EventHandler {
  fn handle(&self, event: Event, event_queue: &mut VecDeque<Event>) {
    use Event::*;
    match event {
      ProcessorStart { .. } => self.process_processor_start(event, event_queue),
      ProcessorStop => self.process_processor_stop(event, event_queue),
      LongRunningTask { .. } => self.process_long_running_task(event, event_queue),
      LongRunningTaskComplete { .. } => self.process_long_running_task_complete(event, event_queue),
    }
  }

  fn process_processor_start(&self, event: Event, _event_queue: &mut VecDeque<Event>) {
    let Event::ProcessorStart { config } = event else {
      return;
    };
    println!("Starting processor with config: {}", config.id);
    // ...
  }

  fn process_processor_stop(&self, event: Event, _event_queue: &mut VecDeque<Event>) {
    let Event::ProcessorStop = event else {
      return;
    };
    println!("Stopping processor...");
    // ...
  }

  fn process_long_running_task(&self, event: Event, _event_queue: &mut VecDeque<Event>) {
    let Event::LongRunningTask { id } = event else {
      return;
    };

    println!("Starting task {}", id);
    if let Ok(mut state) = self.state.write() {
      state.active_tasks.push(id);
    }
  }

  fn process_long_running_task_complete(&self, event: Event, _event_queue: &mut VecDeque<Event>) {
    let Event::LongRunningTaskComplete { task_result } = event else {
      return;
    };

    println!("Task completed. Success: {}", task_result.success);
    if let Ok(mut state) = self.state.write() {
      state.active_tasks.clear(); 
    }
  }

...

Design rationale

Code above has some design decisions that were developed over the years and it has specific needs "baked in" as a result. E.g.:

Serialization/deserialization and clone for Event is very important. I want to save stream to be able to: recreate the state, re-run event, create an event log etc. Starting with serialization and clone requirement makes sure that all events have adequate shape.
Arc<RwLock<State>> allows to defer processing to background threads and make a callback with state modification. It also keeps Sender<Event> for interacting with event system.
&mut VecDeque<Event> is an event pushback, it works with following loop pattern:

   loop {
       let first = rx.recv().await?;
       queue.push_back(first);

       while let Ok(ev) = rx.try_recv() { 
           queue.push_back(ev); 
       }

       while let Some(ev) = queue.pop_front() {
           self.handle(ev, &mut queue).await;
       }
   }

Doing self.tx.clone().send(...) in the same thread could end up deadlocking receiver and the whole application. To avoid deadlock same-thread processor can send event directly to queue instead. Another feature coming from the pattern is also an in-place event transformations. For example it allows for upgrading events without changing processing order (by event_queue.push_front during processing logic).

I'll note that in example I didn't use Envelope pattern - even though in final code I do. In a nutshell: Envelope replaces Event with a wrapper-like structure, i.e. Envelope { event: Event, ...}. Extra data can be included in envelope, a data that doesn't impact on processing but provides useful information. Such data can be, for example, a tracing::Span (for telemetry it is almost required) or (in distributed systems) origin system, timestamps, correlation etc. Envelopes should be processed in a same way by processors and they add to boilerplate. EventEnvelope processor could like like this:

#[tracing::instrument(skip_all, parent: &envelope.span)]
fn process_some_task(&self, envelope: EventEnvelope, event_queue: &mut VecDeque<EventEnvelope>) {
  CustomCounter::count_origin(envelope.origin);
  let Event::SomeTask { value } = envelope.event else { return ; };

  // ...
}

A Perfect World

After implementing same thing thrice I was ready to make a macro for it. I love macros, even though I understand that they shadow the code and add to complexity. This is the same code as the initial example, but in proc-macro version.

#[derive(Clone)] pub struct ProcessorConfig { pub id: String }
#[derive(Clone)] pub struct TaskResult { pub success: bool }
pub struct State { pub active_tasks: Vec<u32> }

struct EventHandler {
    state: Arc<RwLock<State>>,
    tx: tokio::mpsc::Sender<Event>,
}

#[event_macros::event_processor]
impl EventHandler {
    #[handler(ProcessorStart)]
    fn process_processor_start(&self, config: ProcessorConfig) {
        println!("Starting processor with config: {}", config.id);
        // ...
    }

    #[handler(ProcessorStop)]
    fn process_processor_stop(&self) {
        println!("Stopping processor...");
        // ...
    }

    #[handler(LongRunningTask)]
    fn process_long_running_task(&self, id: u32) {
        println!("Starting task {}", id);
        if let Ok(mut state) = self.state.write() {
            state.active_tasks.push(id);
        }
    }

    #[handler(LongRunningTaskComplete)]
    fn process_long_running_task_complete(&self, task_result: TaskResult) {
        println!("Task completed. Success: {}", task_result.success);
        if let Ok(mut state) = self.state.write() {
            state.active_tasks.clear(); 
        }
    }
}

I really, really like it. Transformed code from that example is the same as the initial code.

What transformations are doing?

On the top there's:

#[event_macros::event_processor]
impl EventHandler {
  // ...
}

That's an actual entry point in the macro, it gathers all the information needed and from that it outputs:

Full pub enum Event { ... } definition
run(&self, event: Event, event_queue: &mut VecDeque<Event>) implementation (listen, add to queue, handle from queue)
impl Debug for Event (for debugging purpose it's helpful to know the name of current event)
transformed fn process_ ... functions

Visualized, this is how transformation happen:

Why proc-macro at all

If I'd try hard enough I could (probably) achieve similar result with macro_rules! macro. And I tried!

There is however one thing that I really hate when working with such macros: rust-analyzer and rust-fmt giving up on everything. I don't get inspection, I don't get completion, I don't get formatting. For simple macros that's fine - I can live with a couple non-completed arguments. Yet, with event-driven architecture, the core logic actually lives in handlers, so I didn't want to be deprived of these helpers.

When switching to proc-macros an interesting part is that processor functions are perfectly valid ones! rust-analyzer sees input and output types. I also do some magic (that I don't like but hey...): when EventEnvelope or VecDeque<EventEnvelope> is in function inputs I forward the variable name to body processing, i.e.

#[handler(WithEnvelope)]
fn process_with_envelope(&self, my_envelope: EventEnvelope) { ... }

becomes:

fn process_with_envelope(&self, env: EventEnvelope, event_queue: &mut VecDeque<EventEnvelope>) {
  let my_envelope = env;
  // ... rest of the code
}

Production code

You can see implementation of (macroized) code at one of my open source projects.

There are however, some notable differences.

As I mentioned before: I'm using EventEnvelope and tracing for telemetry, so the actual code is slightly more complex:

  fn process_my_event(
    &self,
    env: EventEnvelope,
    queue: &mut ::std::collections::VecDeque<EventEnvelope>,
  ) {
    let Event::MyEvent { item, value } = env.event else {
        unreachable!();
    };
    {
        println!("Hello from MyEvent");
    }
  }

handle and run functions are asynchronous (because my spawned processor is asynchronous one)

...implementation?

It's here. I won't go into implementation itself, but I need to say that TODAY it's easier than it was some time ago.

LLMs are quite capable in generating proc-macro code given simple instructions, and once I grasped the main concept it was actually quite easy (especially using proc-macro, proc-macro2 and syn crates). In case you wonder, the most important pieces are:

proc-macro is the only crate that can produce proc-macros and it must produce proc_macro::TokenStream as output
proc-macro2 provides many utilities, but outputs proc_macro2::TokenStream - incompatible, but easily convertible to and from proc_macro::TokenStream
syn is creating structs of actual code - things like FnItem or Variant for enums, you can construct them by hand
syn is using proc-macro2 for utilities
code pieces can be generated using quote! (or quote_spanned! if you want to hint user of what is actual source of errors)
parse_quote! can be used to fill in syn structs, e.g.

  method.sig = parse_quote! { fn some_func(a: u32, b: u32) -> u32 };

Once I internalized, used some help from LLMs implementation was quite smooth.

At the end of the day

...I'm really happy with the result. Adding new Events was a chore, usually required at least for places to put the code in:

call site
Event enum
handle function
boilerplate heavy processor_ function

After the change it became only 2, much simplified and deprived of boiler plate.

I considered packing this into a crate (because I KNOW this pattern is good and reusable) but I have some doubts about it.

I don't know if there's any audience: would I use such crate? No idea. Maybe they exist. It's also opinionated - using tracing and serde for serialization. Also it raw crates Event and EventEnvelope in the current namespace, which might be conflicting. Then I require async processing run to dispatch events to handle.

So maybe someday, but if anyone stumbles upon it, the proc-macro implementation is only 300 lines of code (excluding tests) and is pretty straightforward to modify. Maybe it's enough?

I hate Github Actions with Passion

Alexander Przemysław Kamiński — Wed, 14 Jan 2026 23:00:00 +0000

I can't overstate how much I hate GitHub Actions. I don't even remember hating any other piece of technology I used. Sure, I still make fun of PHP that I remember from times of PHP4¹, but even then I didn't hate it. Merely I found it subpar technology to other emerging at the time (like Ruby on Rails or Django). And yet I hate GitHub Actions.

With Passion².

Road to Hell

Day before writing these words I was implementing build.rs for my tmplr project. To save you a click - it is a file/project scaffold tool with human readable (and craftable) template files. I (personally) use it very often, given how easy it is to craft new templates, by hand or with aid of the tool, so check it out if you need a similar tool.

The build.rs used CUE to generate README.md, CHANGELOG.md and also a version/help file to guarantee consistency. It was fun thing to do, it took approx. 1.5h and I even wrote an article about it. For myself and future generations.

I was happy with the results and didn't check CI output which, quite unsurprisingly, failed. I was using cue binary inside build.rs and without it build simply couldn't progress. When I woke up next day and saw e-mail from CI notifying me about failed build I immediatelly knew my day isn't going to start with puppies and rainbows.

It took couple attempts to search and push GitHub Action that would install CUE and then I got the worst of the worst results: One system in matrix failing to build.

A word of explanation. I'm building tmplr for 4 platforms:

Linux ARM
macOS ARM
Linux x86_64
macOS x86_64

Makes sense, right? Even though my user base can be counted on a fingers of one-arm-less and second-arm-hook-equipped pirate, it's still a thing "One Should Do".

And with all that - Linux ARM failed with "command can't be found". CUE installed and ran nicely for all other 3 targets, but for some reason it failed for Linux ARM.

In case you don't care about why I hate GitHub but your mind started to wonder to "what went wrong" let me tell you; because I know.

So supposedly cross build that happens in matrix is heavily isolated. When I install CUE I install it only on x86_64 Linux host and macOS ARM host. macOS has zero issues running x86_64 binary and no issues are raised when Linux x86_64 tries to run x86_64 binary. But GitHub Actions is nice enough to hide x86_64 binary from arm64 runner, so that it won't break.

Thank you GitHub Actions. What would've I done without you.

Broken Loop

And so my least favorite feedback loop started and went like this:

Search for possible fix
Change ci.yml
jj squash --ignore-immutable && jj git push ³
Open "Actions" tab
Open latest run
Open Linux ARM run
Wait couple of seconds
Hate Life
Offer the Universe choice words it won't soon forget
Rinse & repeat

I got quite efficient when it comes to points 8 and 9 but otherwise the whole loop still took around 2-3 minutes to execute.

FOR. A. SINGLE. CHANGE.

Yes. For a single change. Like having an editor with 2 minute save lag, pushing commit using program running on cassette tapes⁴ or playing chess over snail-mail. It's 2026 for Pete's sake, and we⁵ won't tolerate this behavior!

Now of course, in some Perfect World, GitHub could have a local runner with all the bells and whistles. Or maybe something that would allow me to quickly check for progress upon the push⁶ or even something like a "scratch commit", i.e. a way that I could testbed different runs without polluting history of both Git and Action runs.

But no such perfect world exists and one is at the whim of heartless YAML-based system.

Breaking off

I suffered only 30 minutes of such loops. Could've done it for longer but I was out of colorful language to use and felt without it the process just isn't the same.

There is a wise saying in the internet that goes like:

For the love of all that is holy, don't let GitHub Actions manage your logic. Keep your scripts under your own damn control and just make the Actions call them!

This is what everyone should do. This is what I did.

I deleted build.rs (with a sliver of sadness because it was really nice - but sacrifices had to be made). I moved all the generation from build.rs to GNU Makefile, committed the darn files into repository, reverted changes to CI and called it a day. Problem solved.

Exit Code: 0

GitHub Actions, Friends & Gentlefolk, is the reason why we can't have (some) nice things. I can't count how many hours I've lost debugging the runners or trying to optimize the build process. It's a sorry process every single time, a time that would be better spent elsewhere.

And yet there are some benefits, like macOS builds that would be quite hard to get otherwise. I don't know any other system that would be easier to setup than GitHub Actions (if you know one, let me know) but it seems there's no escape.

We are all doomed to GitHub Actions.

...but at least I dodged the bullet early.

And "PHP: Training Wheels Without a Bike" is still in Top 10 of my favorite memes. ↩
That's a capitalized Passion which is one degree above regular passion. ↩
I'm using Jujutsu, this command effectively merges changes in the latest commit (master in my case) and then pushes it out. ↩
Long time ago, in Atari times, loading programs (and games) was done from cassette tapes. It took couple minutes and process was so temperamental that breathing or any movement in the room were strictly verboten. ↩
By "we" I mean "I". But what would be a drama without little dramatism? ↩
It is possible to script gh to do exactly that, but that means another piece of code I need to write ↩

Build.rs-ing Documentation with Cuelang

Alexander Przemysław Kamiński — Wed, 14 Jan 2026 09:06:45 +0000

I have a little utility called tmplr which purpose is to generate files/file sets from a human-readable templates (check it out, it's neat!).

It is at amazing version 0.0.9, and one thing that annoyed me every single time was the need of using version information in few places:

HELP showed on -h or --help
README.md (that included copy of help text)
Cargo.toml
Local git tag (git tag v0.0.9)
Pushed tags it to the GitHub

It's not that bad but it's an overhead I wanted to eliminate. Since I'm a huge fan of CUE and I generate most of the configs/data I need with it I thought - heck, why not?

Thankfully Rust provides ability to have a pre-build "scripts" (it's actually full Rust program) which allowed me to do not only version injection but also:

Generate full README.md
Generate CHANGELOG.md based on smarter entries
Inject Rust code into src/main.rs (that was really neat)
Reuse part of the documentation in other places

Long story short, let me show you my build.rs:

use std::env;
use std::fs;
use std::path::Path;
use std::process::Command;

fn main() {
    // Injects "HELP" into src/main.rs
    prepare_documentation_code();

    generate_doc("README.md", "readme.full");
    generate_doc("CHANGELOG.md", "changelog.text");

    println!("cargo:rerun-if-changed=cue");
}

fn generate_doc(file_in_manifest: &str, eval_command: &str) {
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
    let readme_path = Path::new(&manifest_dir).join(file_in_manifest);
    let output = Command::new("cue")
        .args([
            "export",
            "-e",
            eval_command,
            "--out",
            "text",
            "./cue:documentation",
        ])
        .output()
        .expect("Failed to execute cue command");

    if !output.status.success() {
        panic!(
            "Cue {} generation failed:\n{}",
            file_in_manifest,
            String::from_utf8_lossy(&output.stderr)
        );
    }
    fs::write(&readme_path, &output.stdout).expect("Failed to write generated file");
}

fn prepare_documentation_code() {
    let out_dir = env::var_os("OUT_DIR").unwrap();
    let dest_path = Path::new(&out_dir).join("generated_docs.rs");

    let output = Command::new("cue")
        .args([
            "export",
            "-e",
            "help.code",
            "--out",
            "text",
            "./cue:documentation",
        ])
        .output()
        .expect("Failed to execute cue command");

    if !output.status.success() {
        panic!(
            "Cue generation failed:\n{}",
            String::from_utf8_lossy(&output.stderr)
        );
    }
    fs::write(&dest_path, &output.stdout).expect("Failed to write generated file");
}

Documentation code is bit different because it's a source code that's going to be injected into main.rs using following code:

include!(concat!(env!("OUT_DIR"), "/generated_docs.rs"));

This generated_docs is actual build artifact I don't want to submit to VCS thus I don't plainly generate it. Changelog and Readme is another story, this should be checked in, so I generate them direclty in MANIFEST_DIR (i.e. Project's root).

I won't show my CUE files this time, as they're mostly filled with data and split across multiple files. Here's how my cue/ directory looks like:

cue
├── changelog.cue
├── documentation.cue
├── help.cue
├── LICENSE.cue
└── readme.cue

documentation.cue is a root package file - help, changelog and readme are files containing data (with some smart transformations)

One piece you might be interested in is the final README.md outline:

// ...rest of file, sections etc.
full: """
  # tmplr
  \(sections.tmplr)
  ## Why tmplr?
  \(sections.why_tmplr)
  # Quick Start
  \(sections.quick_start)
  # CLI Help
  ‎`‎``
  \(help.text)
  `‎``
  # Installation
  \(sections.installation)
  # Usage (extended)
  ## .tmplr files
  \(sections.tmplr_files)
  ### Section Types
  \(sections.section_types)
  ### Magic Variables
  \(sections.magic_variables)
  ## CLI
  \(sections.cli)
  ## Templates directory
  \(sections.templates_directory)
  # TODO
  \(sections.todo)
  """

Here you can clearly see that "CLI Help" section is reading directly from the help.text. Neat, right? No more updating README.md by hand, I just need to make sure I build before I push :)

btw. final result is already pushed to the root repo where you can see the end result and full .cue files for inspection. Project extension (see commit for full scope) took around 1.5h to develop, most of the time was spent porting the data from .md to .cue files

CUE Does It All, But Can It Literate?

Alexander Przemysław Kamiński — Tue, 13 Jan 2026 09:07:22 +0000

CUE is the Swiss Army knife of file generation. It is the tool you grab when you need to generate complex JSON, validate YAML, or generally stop configuration files from ruining your life. It slices, it dices, it ensures your integers are actually integers. But guess what else it can be? It turns out, it is also a surprisingly effective *Literate Programming* tool.

This is important because, let’s be honest, the current king of this hill is org-mode. And while org-mode is powerful, it is also a bit of a golden cage. It works perfectly as long as you never leave the Emacs ecosystem. But the moment you try to export a workflow to a colleague who uses VS Code, you realize you have accidentally signed up for vendor lock-in. You want your documentation - your "literate code" - to be portable, not a magic spell that only works inside one specific editor.

The "Frankenstein" Problem

When you write about code - whether it is a blog post, a tutorial, or internal docs - you rarely show one giant, boring file. That puts people to sleep. Instead, you break it down. You show a snippet of the logic. Then a snippet of the config. Then maybe a piece of the CSS. You stitch these disparate body parts together with prose.

The problem is what I call the "Copy-Paste Tribute".

Let's say you write a brilliant tutorial. You copy your working code into the Markdown file. Then, three days later, you realize you named a variable t instead of timeout. You fix it in the source code. But did you fix it in the Markdown file? Probably not. Now your readers are copying broken code, your tutorial is lying to them, and you look like you don't know what you are doing.

CUE solves this by letting us define "parts" and then stitching them together programmatically. It does not just hold the text; it validates that the pieces actually fit. It ensures that the code in your explanation is the exact same code in your final build. It is like having a Lego set where the bricks refuse to click if you are building something structurally unsound ¹.

The Basic Engine

So, how do we stop paying this tribute? We treat our document like a build target.

We can use CUE's tool/file to create the document and tool/exec to run commands. The beauty here is that we are not just templating strings; we are defining a dependency graph. If the dependencies (the code snippets) aren't valid, the document doesn't exist.

package example

import (
  "tool/file"
  "tool/exec"
)

// This is our "build" command. It tells CUE:
// "For every file defined in the 'files' struct, please create it"
command: example: {
  for k, v in files {
    "(k)": file.Create & {
      filename: k
      contents: v
    }
  }
}

// Imagine this is calling a script to get a version number.
// We aren't guessing the version; we are asking the shell for it.
data: exec.Run & {
  cmd: ["sh", "-c", "echo '1.2.3'"]
  stdout: string
}

// Our final document, stitched together.
// The '(data.stdout)' isn't just a placeholder; it's a promise
// that 'data' will run before this string is finalized.
files: {
  "output.md": """
My Awesome Project

Current version: (data.stdout)
"""
}

In a normal editor, that version number 1.2.3 would just be static text I typed in while caffeinated. If the underlying logic changed to 1.2.4, the document would lie to the reader until I manually updated it. With CUE, if data.stdout fails to populate - say, if the shell command crashes - the file simply doesn't generate. The build breaks, protecting the user from bad info.

The Ignition Key: `cue cmd`

There is a catch, though. If you just stare at the code above or run a standard cue eval, nothing happens. CUE is declarative by nature; it describes the state of the world, it doesn't inherently change it. Your file.Create and exec.Run blocks are just data sitting there, looking pretty.

To actually turn that potential energy into kinetic energy, you need cue cmd.

cue cmd is the built-in task engine. It is the part of CUE that is allowed to have side effects. It looks for those command: blocks we defined earlier and executes the tasks inside them sequentially. It is the crucial bridge between "I want a file" (the definition) and "Here is your file" (the reality). Without invoking cue cmd, your literate programming setup is just a very fancy, inert config file.

Crucial Detail: There is a trap for the uninitiated here. For cue cmd to actually pick up your file, the filename must end with _tool.cue (e.g., build_tool.cue). If you name it just example.cue, CUE will ignore your commands completely, and you will be left wondering why your genius code is doing absolutely nothing.

The Polyglot Pipeline

Once you have the engine running, you might realize that simple shell commands aren't enough. echo '1.2.3' is fine for toddlers, but what if you need to compile a Haskell module or render a diagram?

The real magic happens when you realize CUE is incredibly easy to extend. It isn't limited to its own syntax. You can define your own "renderers" using tool/exec, essentially building a tiny, custom CI runner inside your config file.

Here is how you can teach CUE to speak multiple languages by wrapping standard CLI tools. Note the trick with the Haskell renderer: we aren't just passing raw code; we are wrapping it in a module structure so it compiles standalone.

package example

import (
  "tool/exec"
)

// Define our "renderers" -- wrappers around CLI tools.
// Each renderer takes a 'code' string and pipes it into a command.

renderers: pikchr: exec.Run & {
  cmd: ["pikchr", "--svg-only", "-"]
  code:   string
  stdin:  code
  stdout: string
}

renderers: haskell: exec.Run & {
  code:   string
  stdout: string
  cmd: ["stack", "runghc"]
  // Here we wrap the snippet in a module so it compiles standalone
  stdin: """
module Program where
(code)
"""
}

renderers: bash: exec.Run & {
  code:   string
  stdout: string
  cmd: ["bash", "-e"]
  stdin: code
}

// Just for good measure, ZSH too.
// Why? Because sometimes Bash isn't hipster enough.
renderers: zsh: exec.Run & {
  code:   string
  stdout: string
  cmd: ["zsh", "-e"]
  stdin: code
}

Now, when I want to include a diagram or a code output, I just pass my snippet through the appropriate renderer. CUE handles the heavy lifting of calling the shell, piping the input via stdin, and capturing the stdout. It turns your documentation into a living program.

Testing the Narrative

The best part? You can "test" your article. By running cue cmd example, CUE actually executes the shell commands, compiles the Haskell, renders the Pikchr diagram, and generates the final files.

If your code snippet has a syntax error, the generation fails. If your Haskell code doesn't compile, the generation fails. If you try to create a Pikchr diagram with invalid coordinates, the generation fails. It turns "writing a blog post" into "passing a CI/CD pipeline".

It is a bit like having a proofreader who is also a very strict compiler ². It ensures that every diagram in my post was actually rendered from the code right next to it. No stale images, no manual exports, and no "magic" steps I forgot to write down. It is independent of any specific editor ecosystem, effectively solving the "works on my machine" problem for documentation. You aren't just writing; you are engineering the text.

Or if you are trying to put a Megablok on a Lego. CUE has high standards and will not hesitate to judge your poor structural choices. ↩
And unlike a human proofreader, CUE doesn't ask for a salary,
drink all your coffee, or complain about your excessive use of puns. ↩

RwLock HashMap Arc Mutex File

Alexander Przemysław Kamiński — Sun, 04 Jan 2026 09:38:35 +0000

pub struct Context {
    pub(crate) tools: HashMap<String, Option<PathBuf>>,
    pub(crate) fifos: tokio::sync::RwLock<HashMap<String, Arc<Mutex<File>>>>,
 //                                ^                      ^   ^
}//          many fifos, but only  |    async ref counter |   | but only one will
 //           one active at a time |    because many file |   | be active at a time
 //                                |    refs could exist

The Four-Language Waltz: A Tale of Allocators and Regret

Alexander Przemysław Kamiński — Thu, 01 Jan 2026 00:00:00 +0000

The Definition of Insanity

They say the definition of insanity is doing the same thing over and over again and expecting different results. In software engineering, we call this "benchmarking." Or, in my specific case, "rewriting a template utility four times because I am spiritually incapable of settling."

The goal was simple. Deceptively so. I wanted a tool called tmplr. Its job? To take a template, sprinkle in some variables, and spit out a file. It is the sort of task that a shell script could do if you didn't value your sanity, or that Python could do if you didn't value your startup time.

I wanted it to be like Haskell's Stack Templates—human-readable, elegant—but without the requirement that the output be a valid Cabal project. I wanted the freedom to template anything. A grocery list. A love letter. A ransom note. The possibilities were endless.

So, naturally, I decided to write it in every language I could get my hands on until one of them didn't make me cry.

Attempt 1: Haskell (The Mathematical Elephant)

I started with Haskell. It was a smooth ride. Haskell is like a very expensive, very comfortable armchair that you can never actually move out of the room.

The code flowed. The types aligned like the stars in a favorable horoscope. But then came the compilation.

I wanted this tool to be shareable. Portable. I wanted binaries. Haskell looked at me, adjusted its monocle, and handed me a 30MiB executable. Thirty. Megabytes. For a text replacement tool. That is not a utility; that is a piece of furniture.

And cross-compilation? Forget it. I had a binary for Linux Debian. If you were on Windows or MacOS, you were essentially dead to me. Haskell is a language of pure thought, and apparently, pure thought is very heavy to carry around on a USB drive.

Attempt 2: Go (The Beige Cardigan)

I fled to Go. Go is the language you use when you want to get work done and you don't care if you feel anything while doing it.

I had just written a stream sorter (ssort) with the help of an LLM, and the experience was... fine. It was "boring productive."¹.

The binaries were slimmer. The cross-compilation actually worked.

But I missed the types. Oh, how I missed them. Going from Haskell to Go is like going from playing 4D chess to playing Checkers with rocks. It works, but you spend a lot of time checking if rock != nil. I yearned for structure. I yearned for the compiler to judge me more harshly.

Attempt 3: Zig (The Icarus Maneuver)

And so, I asked the oracle (the LLM) for a middle ground. It suggested Rust.

Naturally, I ignored it and picked Zig.

Zig is seductive. It promises you the control of C without the decades of psychological trauma. It promises binaries so small they could fit in a text message. For a while, it was paradise.

Then I hit The Segmentation Function.

This was the core logic: taking the template, splitting it, managing the variables, and dealing with branching logic. It was a complex, 200-line beast. I wrestled it into submission. It worked!

But then, the Debug Allocator cleared its throat.

“Excuse me,” it whispered, “but I believe you have leaked memory.”

I had forgotten to release intermediate objects. I stared at the leak report. The leak report stared back. My head began to throb in that specific way that suggests your brain is trying to physically reject the concept of manual memory management.

I looked at the code. I looked at the headache medicine. I chose life.

Attempt 4: Rust (The Strict Librarian)

I crawled back to Rust.

I don't love Rust. I don't wear the socks. I don't attend the crab-themed parties. But at that moment, I needed a babysitter. I needed a compiler that would grab me by the wrist and say, “No, Alexander. You cannot drop that reference there. Pick it up.”

I rewrote the Segmentation Function. It was still difficult. I still had logic errors. But here, the types and the robust testing framework acted as guard rails. When I made a mistake, the compiler didn't just segfault and laugh; it gave me an essay on why I was wrong.

The Verdict

Is it the Holy Grail?

No. The binary is 350KiB. I wanted under 100KiB. But compared to the 30MiB Haskell Leviathan, it is a feather.

It is fast. It is correct. It runs on Linux. It does not run on Windows, because including pathing libraries would add bloat, and I have principles².

I have come to an understanding with Rust. I don't have to be a fanboy to appreciate that sometimes, it’s nice to have a tool that stops you from shooting your own foot off, even if it forces you to ask permission before loading the gun.

It works. And I am never rewriting it again. Probably.

"Boring Productive" is the highest compliment you can pay a language in a corporate environment, and the worst insult you can pay it on a weekend. ↩
Also, Windows paths use backslashes, which are clearly an abomination against god and nature. ↩