DEV Community: Eduardo Pinho

A new milestone: what's new in DICOM-rs 0.6.0

Eduardo Pinho — Sun, 23 Jul 2023 15:55:39 +0000

I recently released DICOM-rs v0.6.0. DICOM-rs is an implementation of the DICOM standard for the next generation of medical imaging systems. Comprising a total of 71 pull requests, there is so much in this version that I felt the need to make a blog post to further expand on its major changes and talk about some cool new features.

So what's new?

Attribute selectors

It was not a secret that accessing specific elements from a DICOM object could get tricky, especially when working with nested data sets. In fact, accessing nested data set elements is not part of an obscure use case. This happens to be a common necessity, from working with various kinds of multi-frame instances, to structured reports.

For instance, this code snippet brought up to discussion tries to retrieve the Referenced SOP Instance UID from a Referenced Image Sequence, as part of the Shared Functional Groups Sequence. This means navigating two levels of nested sequences.

let obj = open_file("../dicoms/my_dicom_path.dcm")?;

let referenced_sop_instance_uid = obj
    .element(tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE)?
    .items()
    .unwrap()
    .first()
    .unwrap()
    .element(tags::REFERENCED_IMAGE_SEQUENCE)?
    .items()
    .unwrap()
    .first()
    .unwrap()
    .element(tags::REFERENCED_SOP_INSTANCE_UID)?
    .to_str()?;

Handling each error case possible when accessing deeply nested attributes becomes unwieldy and prone to mistakes, as evidenced by this example. In this case, an error is correctly raised when either of the three data elements requested do not exist, or when the Referenced SOP Instance UID value could not be converted to a string (e.g. if it turns out to be a sequence itself). However, this code panics if either of the two data set sequences do not contain any items, or if the data happens to be malformed and the sequence element does not really have a sequence. These situations might seem unlikely in a controlled scenario, but it opens room for attackers to feed meticulously crafted inputs which take down the whole thread or process!

The main difficulty comes from the fact that items() and first() return an Option, which can only be raised with the ? operator in a function context which also returns an Option. Since these methods are chained in methods returning a Result, these options need to be transformed to a Result.

With Snafu, this can be done by adding context methods to the chain, either with a new custom error type or with the dynamic Whatever error:

let referenced_sop_instance_uid = obj
    .element(tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE)
    .whatever_context("Missing Shared Functional Groups Sequence")?
    .items()
    .whatever_context("Shared Functional Groups is not a sequence")?
    .first()
    .whatever_context("No items in Shared Functional Groups Sequence")?
    .element(tags::REFERENCED_IMAGE_SEQUENCE)
    .whatever_context("Missing Referenced Images Sequence")?
    .items()
    .whatever_context("Referenced Images Sequence is not a sequence")?
    .first()
    .whatever_context("No items in Referenced Images Sequence")?
    .element(tags::REFERENCED_SOP_INSTANCE_UID)
    .whatever_context("Missing Referenced SOP Instance UID")?
    .to_str()
    .whatever_context("Referenced SOP Instance UID cannot be converted to a string")?;

Needless to say, even the more correct version of the snippet continues to be very verbose.

The attribute selector API has come to change this, while also bringing new ways to edit and build DICOM objects. A new key component in the dicom-core crate is the AttributeSelector, which uniquely describes a specific attribute in a DICOM object, even if they are nested, by composing a list of sequence items and attribute tags. Attribute selectors can be constructed from tuples of tags, or tuples of interleaved tags and item indices. The following two selectors are equivalent:

use dicom_core::ops::AttributeSelector;

let selector: AttributeSelector = (
    tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE,
    0,
    tags::REFERENCED_IMAGE_SEQUENCE,
    0,
    tags::REFERENCED_SOP_INSTANCE_UID
).into();

// or omit the item indices to assume the first item
let selector: AttributeSelector = (
    tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE,
    tags::REFERENCED_IMAGE_SEQUENCE,
    tags::REFERENCED_SOP_INSTANCE_UID,
).into();

And the example above can now be written like this:

let referenced_sop_instance_uid = obj
    .value_at((
        tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE,
        tags::REFERENCED_IMAGE_SEQUENCE,
        tags::REFERENCED_SOP_INSTANCE_UID,
    ))
    .whatever_context("Could not retrieve Referenced SOP Instance UID")?
    .to_str()
    .whatever_context("Referenced SOP Instance UID cannot be converted to a string")?;

Plus, there is a text syntax for turning strings into attribute selectors, so that tools may benefit from user-input attribute selectors. dicom-findscu already uses it for building the C-FIND query object based on user input.

# retrieve the modality worklist information
# for scheduled procedures where the patient has arrived
dicom-findscu INFO@pacs.example.com:1045 --mwl \
    -q ScheduledProcedureStepSequence \
    -q ScheduledProcedureStepSequence.ScheduledProcedureStepStatus=ARRIVED

Improved object and value ergonomics

Construction of objects from scratch also had a few unnecessary pain-points sometimes. Here is another example from discussions:

let start_date_sequence: DataElement<InMemDicomObject, InMemFragment> = DataElement::new(
    tags::SCHEDULED_PROCEDURE_STEP_START_DATE,
    VR::LO,
    PrimitiveValue::from("19951015"),
);
let scheduled_procedure_step_sequence = DataElement::new(
    tags::SCHEDULED_PROCEDURE_STEP_SEQUENCE,
    VR::SQ,
    Value::new_sequence(smallvec![start_date_sequence], Length::UNDEFINED),
);
obj.push(scheduled_procedure_step_sequence);

This attempt failed with a compile time error due to the inflexible type parameters of Value::new_sequence. In general, building up a DICOM value was a bit troublesome when dealing with data set sequences or pixel data fragment sequences. With the new version, the base DICOM value type DicomValue was further decomposed so that data set sequences now have their own type DataSetSequence, which not only has nicer conversions from sequences of items, it can also be passed instead of DicomValue directly to DataElement::new. In addition, string types &str and String were granted a privileged conversion path to DicomValue.

let scheduled_procedure_step_sequence = DataElement::new(
    tags::SCHEDULED_PROCEDURE_STEP_SEQUENCE,
    VR::SQ,
    DataSetSequence::from(vec![
        DataElement::new(
            tags::SCHEDULED_PROCEDURE_STEP_START_DATE,
            VR::LO,
            "19951015",
        )
    ]),
);
obj.push(scheduled_procedure_step_sequence);

There are a few other breaking changes which were made either to fix existing problems, reduce building costs for unused features, or increase convenience of use. A few examples follow.

The type parameter P in DataElement<I, P> and DicomValue<I, P> now defaults to the current definition for an in-memory pixel data fragment, which is an alias to Vec<u8>.
It is no longer possible to compare a Tag for equality against a [u16; 2] or a (u16, u16). This was a bit of an obscure capability which was bringing issues when trying to use assert_eq! in places where inference to Tag was expected, and developers are expected to convert those to Tag first anyway.
Some type name changes were made in dicom-dictionary-std to accommodate other kinds of dictionaries.
Error types coming from operations in dicom-ul and dicom-object have been redesigned to be smaller in size and more focused on the operation at hand. Any code which mentioned the specific error type by name may need to be updated accordingly.
A bug was fixed in AbortRQServiceProviderReason, which had two different errors combined into the same variant by mistake.
dicom-pixeldata now puts conversion of DICOM objects into dynamic image values behind the "image" feature, and to a multi-dimensional arrays behind the "ndarray" feature. The "rayon" feature can also be excluded for use in an environment which does not support Rayon right off the bat.

Operations API

Still speaking of ergonomics, creating new objects is even easier with the attribute operations API! dicom-core now comes with ApplyOp trait, a common API for manipulating attributes in several ways. Thanks to attribute actions such as Set, we can build the same example above with less lines and less chances of making mistakes.

// create an empty sequence
obj.apply(AttributeOp::new(
    tags::SCHEDULED_PROCEDURE_STEP_SEQUENCE,     
    AttributeAction::Set(PrimitiveValue::Empty)
))?;
// create item and add procedure step start date
obj.apply(AttributeOp::new(
    (tags::SCHEDULED_PROCEDURE_STEP_SEQUENCE, tags::SCHEDULED_PROCEDURE_STEP_START_DATE),
    AttributeAction::SetStr("19951015".into())
))?;

UID constants and SOP class dictionary

The existence of constant declarations is a noteworthy improvement to developer experience. IDEs prepared for Rust development will index them and provide listings of constants to the developer automatically as they look for that specific attribute or abstract syntax.

DICOM-rs v0.4 brought constants for DICOM tags. With DICOM-rs v0.6, we now have constants for various normative DICOM unique identifiers (UIDs), spanning from SOP classes and transfer syntaxes, to even the so-called Well-known SOP Instances. No more copying around non-descriptive string literals when wishing to grab Patient Root Query/Retrieve Information Model - MOVE.

use dicom_dictionary_std::uids;

// old
let sop_class_uid = "1.2.840.10008.5.1.4.1.2.1.2";
// new
let sop_class_uid = uids::PATIENT_ROOT_QUERY_RETRIEVE_INFORMATION_MODEL_MOVE;

On top of this, dicom-dictionary-std also provides a run-time dictionary of SOP classes, so that applications can translate UIDs to their description. This is already in place in dicom-dump, so that the Media Storage SOP Class UID is presented with a human readable description next to the UID.

DICOM JSON support

As the world is unquestionably connected through the World Wide Web, many medical systems already rely on DICOMweb to communicate. Much of the efforts in the project have been around working with standard DICOM data representations and the good ol' upper layer network protocols, but DICOM-rs 0.6 now brings one piece of the bridge to Web oriented development.

dicom-json implements DICOM JSON with the ability to serialize DICOM data into JSON and JSON data back to DICOM data. This allows for an easy translation from types found in dicom-object and dicom-core to the textual representation that dominates most of the web nowadays.

let json = r#"{
    "00080021": { "vr": "DA", "Value":["20230610"] },
    "00200013": { "vr": "IS", "Value":["5"] }
}"#;
let obj: InMemDicomObject = dicom_json::from_str(&json)?;

Internally, serialization/deserialization is backed by Serde, a mature, well-established serialization framework. An added benefit of its use is that converting DICOM data to a JavaScript value via wasm-bindgen becomes available for free.

Pixel data adapter API redesign

One of the open challenges in DICOM-rs is transcoding DICOM data sets between transfer syntaxes. While this is mostly trivial for transfer syntaxes of non-encapsulated uncompressed pixel data, existing tools in the project will choke if they need to decode or encode the pixel data in some way, such as decoding JPEG compressed imaging data into its native pixel data form.

While this will continue to be the case in v0.6.0, this version brings a more complete API for building pixel data readers and writers (also known as pixel data adapters), which are bound to transfer syntax implementations for the ability to convert pixel data in both directions. The old PixelRWAdapter trait was removed and two new traits took their place, with a new set of methods which can even work with individual frames. This change will mostly affect transfer syntax implementations and components relying on middle-level APIs.
Support for decoding RLE Lossless and decoding/encoding some JPEG-based transfer syntaxes, is already available, with more to come.

With this new API just published, this makes a foundation for the next steps towards DICOM data transcoding, hopefully with the efficiency and performance that some users have come to expect.

There is a lot that I could cover here, but at the risk of making this post more exhausting than it already is, this is where I stop. 😅 Have a look at the full changelog for the full listings if you are interested.

New website

I also took this opportunity to announce the new website for DICOM-rs, although it has been online for a few months. It is a seemingly simple one-page site published with GitHub Pages using Zola, and contains a quick overview of the project, as well as a few examples of what it can do.
A small surprise can be found in the middle: a live example of a DICOM dump application, which reads the user's DICOM file in the browser and shows some of its attributes.
All source code of the website, including the live example, is available here.

What's next?

Without replicating what's in the roadmap, I can point out some of the things that I have in mind for the next milestones.

As already mentioned above, an API for transcoding DICOM objects will be an early feature to focus on, possibly in the next minor release. This will then be integrated into the storescu tool to enable an automatic object conversion if requested by the service class provider.
The lack of high level constructs for writing DICOM network services is one of the most frequent concerns raised so far. The UL association API helps to accept and establish associations with other DICOM nodes, but there is still little hand-holding for sending and receiving commands and data in conformance with the intended DICOM Message Service Elements (DIMSE), and components to assist in compliance with the DICOM upper layer protocol state machine. There is also not a clear direction on how to make network services asynchronous, although this is in the project's plans. Making network operations non-blocking is important for a better usage of the computational resources available.
Already in my thoughts, I believe that there is an opportunity to revamp DICOM object reading and construction by declaring modules from Information Object Definitions (IODs) as specially annotated Rust types. It will be a great undertaking, but it will bring immense gains to the library in multiple ways when it's done.
Lazy DICOM object loading has been in my head since the beginning of the project, but it has been constantly set aside due to its difficulty to get right while maintaining usability. This still ought to be tackled sooner or later. To help drive this forward, I am likely to take it in a different direction, by first implementing a separate API for reading and writing DICOM data in independent chunks.

Discussion is open through the respective GitHub discussion thread.

Timely wrap-up: some (not so) quick notes on Timely Defuse

Eduardo Pinho — Sat, 03 Dec 2022 16:32:00 +0000

Preface

Building a video game during November has become a yearly tradition to me. Save for 2019, I've been casually participating in the GitHub Game Off game jams since 2017. And each time I do, I have so far brought along a different set of technologies to learn and apply in the development of a new video game.

Before I dive in to some notes about this year's game, here is a quick history of my past works:

GitHub Game Off 2017: Propan, written in Rust with the Piston game engine, is a 2D topdown game inspired by another game from the early 1990's, Helious.
GitHub Game Off 2018: Pkay is a pong/tower-defense hybrid made in Godot. It also featured a two-mode music loop comprising a combination of synthesised instruments with my own guitar recordings.
For GitHub Game Off 2019, I had already started working on a one-button platform game with code name "vivo", but the core game mechanics were not all complete, and I got sick during that month, which made me lose valuable time. The unexpected illness and lack of motivation towards the game made me unable to finish it.
Still, I grabbed Phaser.js again in the following year to make Win in Space, a turn-based physics game for Game Off 2020 written in TypeScript. Fun fact: This one featured a full-length background music with the same name, and I named the game after the track rather than the other way around.
Last year, for Game Off 2021, I went for quite a different vibe with a full Web experience: 10x Sprint Master is a simulation strategy game where you pretend to be a lead software engineer, written in HTML, CSS, and Rust for WebAssembly. I wrote more about this one here.

Introducting Timely Defuse

In Timely Defuse, dynamites and bombs 💣 are thrown onto the game environment out of nowhere, and your job is to control the hero to defuse the dynamites and disarm the bombs before they explode. Dynamites are defused by grabbing them within reach. Bombs are disarmed by letting the hero tinker with the bomb for a few seconds 🤔. As you successfully stop these from exploding ✂, you gain points. Let bombs explode on you 🤯, and you lose points. The game proceeds in waves of increasing difficulty, as the explosives appear faster and in greater numbers. As a boost bonus, you can grab randomly thrown coffee mugs ☕ for a temporary increase of speed and disarming efficiency ⏫. After the final wave, a summary of your performance appears, including the final score 🏆.

Conceiving the idea

The theme for GitHub GameOff 2022 is cliché. Participants are free to interpret it the way they want.

So how did I get from cliché to the game that we have here? Well, it was far from trivial. The official page provided a link to a comprehensive list of clichés, but I tried to write down a short list of my own:

Where do you keep your inventory?: a very common question in point-and-click adventures.
Jump onto enemies to kill them
flappy bird clone (FWIW would provide a good mobile game experience)
break things to get money
"press start to play"
mute protagonist (and the talkative sidekick who says everything for you, of course!)
miraculous food (have a burger, it'll seal that stab wound in no time)
Saved at the last moment

And not long after, I felt like reflecting deeper into the last one: a very common cliché in films and games, sometimes some characters are saved just before something bad happens. The associated TV trope is Just in Time.

So at this point I kept thinking about some mechanics in which the player had to act at the last second. I even pondered turning this into a puzzle game, where you are expected to push buttons and drag boxes until you could finally disarm a bomb one second before it explodes. However, I did not pursue this idea, for a puzzle game would have required me to devise each level manually with intricate pieces that I did not even know what they were in order to make the game interesting.

By making it more action oriented, the game idea was starting to direct itself towards the player having to touch lit explosives before they blew up. Pretty much like a point-and-click reaction game. But I still did not know how to make it interesting from here.

I had already tinkered with the game engine so as to understand whether I would be able to implement a mobile Web game with touch recognition easily. The answer was yes, the game engine allowed this with ease. And only after I had this answer, I came up with the idea of the player not being the one grabbing the explosives, but handing that job to an in-game protagonist instead! This made room for noteworthy mechanisms:

By letting the player tell where the protagonist should move, actions on any object would take additional time depending on the distance between the protagonist and an object, so the player had to act fast and decide which objects to take care of first, at the risk of not being able to handle others on time.
The protagonist would have a set of characteristics, namely maximum movement speed and bomb disarming efficiently, which could be temporarily boosted using power-ups.
The protagonist would also be vulnerable to explosion damage, affecting the hero by blasting them away from the explosion and needing time to recover. I had thought of having a life counter which would decrease when taking a hit, but I felt that the game was fun enough to play with just the stunning effect.
As a "stress" mechanism, the protagonist disarms bombs substantially faster if they are very close to exploding, making it sometimes advantageous to disarm them later.

With this, most of the idea had been set. It was time to get my hands dirty.

Technical notes

Next I will just write an assortment of topics about the development of Timely Defuse.

Mobile first

This time, after the disappointment of making a game which was not mobile friendly (also too philosophical, but I digress...), I had decided that this time I wanted the game to be not only Web first, but also mobile first. Picking a fixed resolution in (scaled) pixels which would fit on the great majority of devices seemed to do it well, although one cannot be fully certain of complete compatibility with all devices in this manner. For what it's worth, there were no complaints so far from close relatives and friends.

Using Bevy

I added an extra pinch of challenge and learning opportunities by trying out the Bevy game engine. Bevy has been rising in popularity in the Rust game development circles as a simple but capable data-driven engine, with support for many platforms, including WebAssembly, backed by its own Entity Component System (ECS) framework. I had heard many times about ECS, even back in 2017 after I had finished Propan, but this was my first hands-on experience in this pattern.

Easy to bootstrap

Setting up a barebones Bevy application was easy, especially considering that the official site provides a small book so many examples to experiment with, including ones covering full Web support. What may take longer to process is how one should develop complete projects in Bevy from start to finish, and for that we would need more references than just the book, which is still a bit thin at the moment. The Bevy Cheatbook ended up being a very valuable resource, which I kept some tabs open most of the time. Despite not being official, I really cannot understate how important this cheatbook was in working with Bevy.

Systems, systems, syssytsetmsems

In ECS, game logic is extended by adding systems. In Bevy, systems are plain functions receiving an assortment of compatible parameters, in a way that reminds me of dependency injection systems. It was very clever of Bevy to take advantage of Rust's trait system to describe system functions. They can even describe whether components are to be queried with immutable or mutable access. Whenever we had to adjust a system function, changes to the system inclusion point were seldom needed. We would just change the signature and use it accordingly within the function.

However, using ECS was not always a walk in the park.

Systems can be pretty powerful in describing game logic, and I quickly ended up writing a bunch of common patterns:

Removing a component from an entity after some time;
Removing the whole entity after some time;
Sending an event after some time;
Adding a component to a specific entity after some time.

And yet, I must have overlooked something, as there didn't seem to be an easy construct for creating these kinds of systems other than just a Timer. This means that a lot of these systems ended up looking like this:

/// system: do stuff when the time is right
pub fn do_stuff(
    mut commands: Commands,
    time: Res<Time>,
    mut query: Query<(
        Entity,
        &mut DelayedStuff
    )>,
) {
    for (entity, mut delayed_stuff) in &mut query {
        delayed_stuff.timer.tick(time.delta());
        if delayed_stuff.timer.just_finished() {
            // do stuff

            // destroy entity for example
            commands.entity(entity).despawn();
        }
    }
}

The repetition is something I would not encourage, but it was how I got by.

Granted, it is possible to write generic functions as systems. Here is a real example. Given structs ScheduledEvent<E> and DespawnOnTrigger, describing components:

/// component to fire an event after some time
#[derive(Component)]
pub struct ScheduledEvent<E: Send> {
    timer: Timer,
    event: E,
}

/// component to despawn the entity
/// when the trigger in `ScheduledEvent` is fired
#[derive(Default, Component)]
pub struct DespawnOnTrigger;

I had this system:

/// system: run scheduled events if it's their time to trigger
pub fn run_scheduled_events<E: 'static + Send + Sync + Clone>(
    mut commands: Commands,
    time: Res<Time>,
    mut query: Query<(Entity, &mut ScheduledEvent<E>, Option<&DespawnOnTrigger>)>,
    mut event_writer: EventWriter<E>,
) {
    for (entity, mut scheduled_event, despawn_on_trigger) in &mut query {
        scheduled_event.timer.tick(time.delta());

        if scheduled_event.timer.just_finished() {
            event_writer.send(scheduled_event.event.clone());
            if despawn_on_trigger.is_some() {
                commands.entity(entity).despawn();
            } else {
                commands
                    .entity(entity)
                    .remove::<ScheduledEvent<E>>()
                    .remove::<crate::spawner::SpawnerCooldown>()
                    .remove::<crate::spawner::PendingThrow>();
            }
        }
    }
}

It's incredible how I am just now seeing the Swiss cheese full of holes that this system is. When the DespawnOnTrigger component is not present, it will remove the scheduled event component. This is so that the component doesn't stick around long after it's no longer needed, and so that it can eventually accept a new scheduled event in the future. But not only that, the function will also remove a bunch of other components pertaining to specific game logic. This is not as generic as I had envisioned.

Not to mention that generic systems cannot be included in the application as is. They need to be instantiated first. In this case, one for each possible event. One can imagine how easy it is to forget to instantiate the system for a new event.

app.add_system_set(
    SystemSet::on_update(AppState::InGame)
        .with_system(run_scheduled_events::<DynamiteThrownEvent>)
        .with_system(run_scheduled_events::<BombThrownEvent>)
        .with_system(run_scheduled_events::<CoffeeThrownEvent>)
        .with_system(run_scheduled_events::<NextWaveEvent>)
)

(I would be thrilled to be told "You're doing this wrong", so long as there really is a better way!)

There's more about this ECS implementation. The non-deterministic order between systems by default was also a nasty source of bugs. Passing a series of systems like this:

app
    .add_system(progress_bar::clear_progress_bar)
    .add_system(progress_bar::update_progress_bar)

Means that the two systems can run in any order, and that order can even change between update frames! In this case, updating the progress bar would also make it visible, thus cancelling the effect of clearing it in the first place. I had to explicitly require one to be executed after the other.

app
    .add_system(progress_bar::update_progress_bar)
    .add_system(
        progress_bar::clear_progress_bar
            .after(progress_bar::update_progress_bar),
    )

Unless you are careful about organizing your systems from the start through labelled system sets and whatnot, inconsistencies could happen, since they can just run in any order.
In hindsight, I would have resorted to tighter categorization of systems and possibly a much tighter execution order from the start, and perhaps relax the constraints selectively at a later stage. In any case, it feels unlikely that I would benefit a great deal from loose system order constraints in this scenario.

I also read that the Bevy CheatBook recommends iyes_loopless, but this is something which should probably be added from the start rather than having to adapt an existing application. For me, it was too late to make that shift by the time the game was practically done.

My kingdom for an essential resource

Aside from the concept of entity, component, and system, we can have resources! These are intended for things which exist globally in the application, akin to singletons. Examples of resources from the standard bevy crates include the asset loader (AssetLoader), event readers and writers (EventReader<E>/EventWriter<E>), and the application time tracker Time. Like for entities and components, they can be retrieved from any system.

Remember when I mentioned that system function signatures can just be tweaked to gain access to other components? Well, this applies to system functions only. I often had functions which looked like this:

pub fn spawn_dynamite(
    commands: &mut Commands,
    texture_atlas: Handle<TextureAtlas>,
    bounce_sound: Handle<AudioSource>,
    pos: Vec3,
    velocity: Vec3,
) -> Entity {
    // ....
}

This is not designed like a system because it isn't one. It is a function to be called inside another function, with the following caveats:

It had to be called with the right set of parameters. texture_atlas had to be a handle the texture atlas containing the animation frames of the dynamite, and bounce_sound had to be a handle to the sound that the dynamite does when it bounces. Each of these are nothing but global dependencies with only one possible (correct) value.
Any dependency in this function needs to be passed along the callers. As such, any system which needed to spawn a dynamite had to declare the need for a dynamite texture atlas resource and for the handles sound effects (which in the latter case I coupled together into a single resource for convenience), so that the handles could be passed here.

/// system: on dynamite thrown, spawn it
pub fn throw_dynamite(
    mut commands: Commands,
    mut rng: ResMut<Rng>,
    texture_atlas: Res<DynamiteTextureAtlas>,
    sound_sources: Res<GameSoundSources>,
    mut event_reader: EventReader<DynamiteThrownEvent>,
) {
    for _ in event_reader.iter() {
        let pos = random_xy_position(&mut rng);

        crate::dynamite::spawn_dynamite(
            &mut commands,
            texture_atlas.0.clone(),
            sound_sources.thwack3.clone(),
            pos.extend(1200.),
            random_velocity_variations(&mut rng),
        );
    }
    event_reader.clear();
}

This was awkward in some place, where I even needed to inject not only resources but also specific query objects.

It might be that one could work around this by using system chaining, something which I may have understated when working on the game.

UI nodes

I can appreciate the fact that the engine comes with a user interface module, also running through ECS. With it, you can declare a graph of UI nodes by spawning entities with the right set of components so that they become frames, buttons, and so on.

Timely Defuse was thin on UI, but it was helpful to have a straightforward way to make text appear in the way that was predictable. The use of Flexbox from the CSS world to describe node styling was peculiar, but a good decision overall. It does not mean that you will always get the presentation that you hoped for the first try, but heh.

Safety obstacles

I wouldn't expect to stumble upon such a problem, but it may happen that the game starts with no audio. The latest browser security mechanisms imposes that audio contexts must only be created after user interaction. This means that if you enter the game page through GitHub without clicking on anything, you might get no sound at all.

I did some checking and it's true that even my other Web based submission, Win in Space, will only have sound and music playing as soon as I interact with the page. The difference was that Phaser.js has a mechanism to resume the existing audio context if it was create too soon to be able to engage, but Bevy as of v0.9.0 does not. Maybe I should file an issue.

Compilation times

Bevy boasts having achieved quick compilation times in development mode in comparison with other frameworks, going as far as to suggest that "you can expect 0.8-3.0 seconds with the "fast compiles" configuration".

It is good that the project goes to great lengths to reduce compile times. However, to test the WebAssembly build, some of the options suggested to improve compilation performance are not available. With opt-level = 1 and dynamic linking, it would take at least 10 seconds to build this application with a single change to the source code on my 2019 laptop. I could only get the alleged compilation times by only optimizing the dependencies and leaving the end crate at opt-level 0. The other suggestions to change the linker may be also important, but again, they may be out of reach when working for the Web.

Ultimately, optimization options for release were focused on reducing size. The WebAssembly file for production was 17 MiB large. In-game performance was mostly OK.

Conclusion

As typical in a GitHub Game Off submission, the full source and assets are available. Many of the graphics and sound effects were retrieved and adapted from free sources. You can play the game in a modern browser, using a mobile device or desktop, from GitHub or from itch.io.

Just keep defusing and nobody explodes.

Writing bindings to `dos-like` for Rust: some lessons learned

Eduardo Pinho — Tue, 15 Mar 2022 18:23:53 +0000

My childhood included a fair share of MS-DOS games from the early to mid 1990's. And even decades later, I appreciate looking back to the games and studying the technologies surrounding them, such as Sound Blaster audio and the various VGA graphics modes of the time, honorably mentioning mode 13h.

Now, being both a Rust enthusiast and MS-DOS nostalgic, I have, multiple times, tried closing the gap on writing applications for real DOS systems in Rust. Unfortunately, this is not without issues, and there is not a clear path on how to go with this yet. More on existing efforts here.

So when I had some spare time the past weekend, I decided to do something a bit different: bring to Rust an existing framework that lets you write applications which look like they are DOS applications.
dos-like, made by Mattias Gustavsson, is like a small engine for writing modern applications with the look & feel of MS-DOS programs. So basically, when using this framework, we end up with applications that run on modern hardware and operating systems all the same, but with deliberate video effects and audio that bring us back to that era, including large pixels, CRT distortion, text and graphics video modes, and synthesized (Sound Blaster 16) or MIDI (Sound Blaster AWE32) music. It was written in C, mostly as a single file with some other statically linked dependencies. The project also comprises a few fun examples, such as a proof-of-concept FPS inspired by Wolfenstein 3D, a point-and-click adventure, a voxel renderer, and even a music tracker.

By creating direct bindings to the C interface (dos-like-sys), followed by a more high-level abstraction, it becomes possible and (hopefully) intuitive to write applications of this sort in Rust! So I did that!
In this post, I will now share a small collection of technical topics that I felt worth sharing about the conception of these bindings.

Compiling and static linking

Although I've had the experience of writing bindings to dynamically linked libraries in the past, this one blatantly called for direct static linking to a C object compiled on the spot. By following the documentation of cc and observing some build.rs files from other bindings, I managed to make compilation and linking work on Linux and Windows, straight from the original sources, fetched using a git submodule. A few extra steps were needed on Linux, since it depends on SDL2.

Alas, although there is WebAssembly support in the original dos-like, it is still not supported in the bindings for Rust. It would require a Rust toolchain to integrate with WAjic, which I am pretty much unfamiliar with. If you have any idea on how to achieve this, I would love to know.

Is this a library?

One of the most interesting things about the final dos-like package delivered to crates.io is that, while it is indeed declared as a Rust library, it has a strong caveat that needs to be considered whenever it is added to a project: it provides its own main function!

What makes dos-like so easy to create applications is that it takes care of all application bootstrapping by itself. When writing a new program in C or C++, this is what would happen:

In a new C file, the user includes dos.h and writes a main function definition as usual.
That C file is linked alongside dos.c, which reassigns the main function to a function named dosmain.
The framework replaces the main function definition with its own function, which does, among other things, call dosmain.

In a plain C environment, it is possible to do this kind of symbol reassignment with macros. But in Rust, there are no C macros! The library has no way of knowing that we have declared a main function in C land! As a consequence, the Rust linker would find two main function declarations and fail to link.

So the solution to making this work is this:

Add the no_main attribute, so that Rust does not try, nor demand you to declare a main function;
Declare an extern C function called dosmain instead.

#![no_main]

extern "C" fn dosmain() -> i32 {
    0
}

I also added a Rust macro to assist in this last declaration, but I don't find it very usable nor idiomatic.

Since the bottom part of the program is a C function, stack unwinding also does not work. I chose to recommend users to abort on panic instead, by writing this in their Cargo.toml file:

[profile.dev]
panic = "abort"

[profile.release]
panic = "abort"

Is that an `int`?

The majority of functions in the framework were pretty easy to translate to Rust. With the low-level bindings already built automatically from the C declarations via bindgen, all that was left was to encapsulate them in non-unsafe functions with idiomatic parameter types. A great deal of these functions received plain C ints as parameters. Instead of those, the parameter types were chosen based on what they represented:

u8 is great for color identifiers, since the application is limited to a 256 color palette. It was also used for the RGB value components of each color, in which functions expected integers between 0 and 255 anyway (although in the end they would be artificially trimmed to a precision of 6 bits per color, thus replicating the 18-bit palette of the time).
u16 was used for x and y coordinates, both in graphics mode and in text mode. 16 bits was a pretty common integer size back then, and the screen width or height would never be larger than this.
Where a 0 or 1 were expected for stating whether something should be on or off, a bool is used instead. Easy peasy.
Some functions expected a C string, as in a pointer to a null-terminated sequence of characters. Creating a function that receives a standard Rust string slice &str requires a new string to be allocated with a null character \0 appended at the end. To assist those who might already have a null-terminated string in handy, a separate function was created that receives a slice of CStr instead.
Certain resource identifiers were replaced with their high level abstraction, such as the Soundbank.

Since I often had to look into how each function was implemented, this was also an opportunity to document them. Maybe one day someone can pass along some of these texts into the original dos-like, if they still apply there.

Exclusive, safe video memory access? Pick one.

Now, dos-like is pretty usable with the various drawing primitives, such as line, bar, blit, circle, outtextxy, ... But dos-like also gives you a way to directly manipulate the video memory buffer to be written to the screen:

unsigned char* screenbuffer(void);

The output is a plain pointer to width * height bytes. If double buffering is enabled, swapbuffers passes that data to the display and gives you another buffer to write to. Both buffers are pieces of memory created once at boot, the library just gives one or the other in turns, on each call to swapbuffers.

unsigned char* swapbuffers(void);

These functions are often used in practice like this:

setvideomode(videomode_320x200);
setdoublebuffer(1);

unsigned char* buffer = screenbuffer();
while (shuttingdown() == 0) {
    waitvbl();

    // write things to buffer
    for (int i = 0; i < 320*200; i++) {
        buffer[i] = (i & 1) * 15;
    }

    // swap buffer
    buffer = swapbuffers();

    // ... handle user input
}

Now, so long as you do not write beyond the boundaries of any of the given memory buffers, you are safe and have nothing to worry about. But how can we make this both easy and safe to use in Rust?

The easiest way to use a writable memory buffer in Rust is with a mutable byte slice: &mut [u8]. We could think of a function done like this:

unsafe fn screen_buffer() -> &'static mut [u8] {
   let len = get_screen_resolution();
   std::slice::from_raw_parts_mut(screenbuffer(), len)
}

But this is completely memory unsafe! Mutable slices expect exclusive access to that piece of memory, with no aliasing of any kind. Unlike raw pointers, having more than one mutable slice to this video buffer is instant undefined behavior. And this function makes that as easy as calling it twice without swapping the buffers first.

unsafe {
    let buffer = screen_buffer();
    let buffer_copy = screen_buffer(); // UB :[
}

In addition, calling any other drawing function while we have a hold of this slice is undefined behavior as well.

unsafe {
    let buffer = screen_buffer();
    circle(120, 100, 16); // also UB :[
    buffer[0] = 1;
}

I did try to think of other ways to make exclusive access verified at compile time, such as creating a static global instance with a phantom lifetime to serve as a lock. But this wasn't enough to simulate double buffering, as it would prevent a legitimate use of swapping buffers and fetching a slice to the new buffer. Even with both functions returning mutable slices, they would be exclusive, and it would be safe to use the same variable, since a reassignment would drop the previous slice before there is a chance for aliased slices:

set_double_buffer(true);

let mut buffer = unsafe {
    screen_buffer() // slice to buffer0
};
while !shutting_down() {
    wait_vbl();

    // use buffer

    buffer = unsafe {
        swap_buffers() // slice to buffer1 (iteration #0)
    }; // slice to buffer0 (iter #0) dropped immediately
}

A safe abstraction for access to the two video buffers (let's call them buffer0 and buffer1) would:

allow the user to retain at most one mutable slice to buffer0 and at most one mutable slice to buffer1;
let the user seamlessly switch between the two in the main application loop, with a reassignment or something equally usable;
AND prevent calls to any other drawing primitives for as long as any of the slices are held.

I couldn't come up with this yet, but feel free to reach out if you have a better idea!

In the end, the two functions were exposed as unsafe, with detailed safety guidelines documented. Those who which to avoid direct video buffer access can still use the various drawing primitives and achieve the same thing with only a bit of extra overhead, which seems unlikely to become a problem in my opinion.

I am also not sure whether any of this is memory safe with double buffering disabled. Oh boy.

Returning small arrays? One simple trick.

With the elephant in the room pointed out, let's go back to easier challenges. We also have a few functions to provide a list of user input events:

keycode_t* readkeys(void);
const unsigned char* readchars(void);

The returned pointers are also null-terminated, where the first is for key codes and the second one is for characters. For instance, if the user held Shift and pressed A, the first function would give us the SHIFT key code and the A key code, whereas readchars would give us an upper-case A.

Keyboard and mouse events are accumulated in an internal buffer. When one of these functions are called, the recorded keycodes or characters are flushed into a separate buffer and a pointer to that buffer is returned. One may feel tempted to write a high-level function with this signature:

fn read_keys() -> &'static [KeyCode];

But doing this would not be memory safe! Rust requires that data behind a reference never mutate, but with subsequent calls to read_keys, the contents in the same buffer could change as part of the implementation.
On the other hand, unlike screenbuffer, this pointer is only intended to be read from, and as such it is a fairly good candidate for copying over to an owned vector. Here is the complete implementation:

pub fn read_keys() -> Vec<KeyCode> {
    let mut keys = Vec::new();

    unsafe {
        let p = dos_like_sys::readkeys();
        for i in 0..=255 {
            let c = *p.offset(i);
            if c == 0 {
                break;
            }
            keys.push(KeyCode(c));
        }
    }

    keys
}

A copy is free to be read and manipulated in consumer space without any risk of breaking memory invariants. Unless you're into keyboard smashing or only rarely call these functions, we expect them to return a very small number of events each time, often 0 to 2 values, making the copy pretty fast anyway. Moreover, if we replace Vec<_> with, say, a small_vec, we're avoiding heap allocations when the number of events in queue does not justify it. The final signature of the high level function is the following:

pub fn read_keys() -> SmallVec<[KeyCode; 2]>;

Validated resource identifiers

dos-like allows you to load custom fonts from .fnt files for text output in graphics mode, and custom soundbanks for synthesized music. When the functions below succeed, they save those resources in the framework and return a positive integer which identifies that resource for the rest of the application's lifetime.

int installuserfont(const char* filename);
int installusersoundbank(const char* filename);

Some functions would then accept an integer to identify the font or soundbank to use:

void settextstyle(int font, int bold, int italic, int underline);
void setsoundbank(int soundbank);

Technically, these identifiers are checked by the implementation, so it is not undefined behavior to pass an invalid ID. Still, a type safe abstraction around it prevents misuse by expecting an instance to be created first.

let font = install_user_font("files/volter.fnt")?;
set_text_style(font, 0, 0, 0);

This may seem oddly equivalent to what would be done in C, but there's a neat safeguard in the function signatures:

pub fn install_user_font(filename: impl AsRef<str>) -> Result<Font, FileError>;

pub fn set_text_style(font: Font, bold: bool, italic: bool, underline: bool);

The first one returns an identifier of type Font, only if the operation was successful. The second one will not accept anything else other than a font identifier, all of this checked at compile time. And an instance of this type can be passed just as easily as an int, because it's just a NonZeroU32 underneath! A NonZeroU32 is an unsigned 32 bit integer which is sure to never be zero. The compiler can take advantage of this to represent derivative types in less bytes (i.e. Option<NonZeroU32>).

For other resources, such as music and sound, such resource loading functions would yield their output via returned pointers to static memory or by output pointers. Sound, Music, and Image were created with an object oriented design. One advantage of this is that some of the functions can be intuitively made into methods.

let music = load_opb("files/doom.opb")?;
// play music, no looping, maximum volume
music.play(false, 255);

So this was an aggregation of tricks through which a C framework can be suited for writing applications in Rust. dos-like for Rust is freely available on crates.io and on GitHub. The GIF below shows an example that can be written in 60 lines of Rust code.

10x Sprint Master: a technical and social experiment

Eduardo Pinho — Sat, 18 Dec 2021 18:49:31 +0000

I recently wrote a game for the GitHub GameOff jam, which has been a fairly common practice of mine for a while. 10x Sprint Master is about software development, team coordination, quality assurance, bug fixing, workplaces, and taking breaks for coffee every once in a while. In other words, this game is about work. The tech work that so many developers out there have, except that it's intended to be fun.

The next section of this post is a description of the game. Afterwards, there will be a more technical section, in which I will cover the technologies that were used, as well as personal notes and expectations about their use. Finally, the third section makes an introspection into the social aspects that give the game a personality of its own.

Description

The game puts You in the shoes of a development lead engineer, who has just arrived into a fictional company, and will soon become responsible for creating tasks to perform, specifying what each task entails, and assigning them to members of the team, while managing the life cycle of each task.

You don't have a name (the caption "You" appears below your avatar), but you are given the opportunity to name the product or project to whatever you want (even though the company is nameless). And oddly enough, all your team members have actual names.

The entirety of the game takes place in front of a project workboard, consisting of 5 columns, each representing a stage:

The Backlog stage is where new tickets arrive.
The Sprint Candidate stage turns stub tickets into well specified tasks.
The In Progress stage is where the actual coding takes place to fulfill the task's acceptance criteria.
The Under Review stage is where tasks are checked for bugs. If bugs are found, moving them back to In Progress allows you to fix them.
Once ready to go upstream, tasks are moved into the Done stage, and can no longer be interacted with.

As you start the game, and if you kept the Onboarding option checked, you will meet with the former lead engineer, who will explain you how to do things. But that mentor will also leave you at the end of the month, and so you will be forced to inherit the entire knowledge and workload during that time! To the player though, it amounts to knowing how to drag and drop tickets around with the mouse.

You start the game severely understaffed: only you as the developer. A few months in and new hires arrive. However, they will not have the same experience as you, so they will work slower until they get better over time. And speaking of time, some tasks have a deadline, and sometimes you are given some final hour feature requests.

Every while that a developer writes code under a task, they may be introducing bugs. 🐛 The review stage is the place where they are hopefully found. 👀 ...that is, before it is too late and they are merged. Irrespective of that, each contribution brought upstream increases the complexity of the software, which can be mitigated with chore tasks. As time passes, the tasks to fulfill become more and more demanding.

Occasionally, you will receive random messages from your peers for the full workplace experience. They will complain during their coffee breaks ☕ about the excessive number of meetings. You will receive reminders to pick the toppings for your pizza lunch. 🍕 You may also be asked to help the DevOps team, which is almost always in trouble.

And yet, the game actually does not mention how much these developers get paid. There is no salary negotiation, no distribution of dividends, not even a worthy mention of how well received your product is.

What exactly drives the player to continue going, then? Well, there is a score. Merge tasks, and it goes up. Mistreat your software with too many bugs and technical debt, and it will slowly linger over time. Make it too difficult to work on your projects, and your team members will give up and leave, only making things worse. Ultimately, optimizing for score requires you to strike a balance between feature delivery, bug fixing, and technical debt mitigation.

Do this well enough and you will receive a special call from the CEO! Well, this might not actually be possible though. Please let me know if you ever manage to achieve this.

A technical experiment

Primary tooling

I decided to write this game in HTML, CSS, and... that's right, Rust via WebAssembly.

It was never a matter of whether these were the right tools for the job. It was about gaining experience in a field which I only had minimal grasp of, and about understanding how far one could go in frontend development for the Web using Rust, a programming language which I enjoy and am already well fared in outside web front-end development.

In the process, I picked Yew as the Web framework. There wasn't too much thought put on this decision, but I felt that it was the most mature Rust solution for dynamic web applications. Trunk was used for building the project, which is apparently a common choice here. It is far from being as complete as Webpack or Parcel, but it did the job as intended:

trunk serve would continuously build and refresh open pages on any source changes;
trunk build would do the process once.

Combine that with additional options and Cargo tweaks, and that would give me all resources, optimized, hashed and ready to be published.

There was only one relevant tweak I had to make in the distributed index HTML file in order to make it work on itch.io: the paths to the various assets had to be modified to be relative paths instead of absolute paths. This is because itch.io provides the games' assets in a cross origin which will not sit in the root path.

Graphics and design

I have also been taking Josh Comeau's CSS for JavaScript developers course, and I took this jam as an opportunity to apply my new skills. Even though I have only completed the first few modules, it has so far enabled me to have a much better grasp of CSS, instead of just blindly messing around with properties until I got what I wanted. If you are interested in knowing how to write modern CSS, there is no other course I could recommend but this one.

As such, the game's design was primarily driven by CSS, with some emojis to serve as memorable icons. Even the characters and the cute little bug presented in the tickets were made with a bunch of styled divs. Keeping that part of the application away from Rust felt ideal, so as to reduce DOM manipulations to the minimum necessary. Even the animations in the onboarding phase demonstrating how to move tasks around were completely devoid of JavaScript or WebAssembly to function. I liked them pretty much.

There's even an easter egg: stay in the main menu for a while to see something cute. All in pure CSS. 😬

I added PostCSS so that I could use @import statements and incorporate automatic prefixing. One of the minor nuisances that I could not resolve was to join PostCSS and Trunk together when serving the application locally. I ended up creating an npm project with multiple scripts to run all the necessary steps, and I would just run a CSS watcher alongside trunk serve in another terminal.

Using Rust

But to speak of nicer things now. Thanks to the use of Rust, working on certain features was a breeze.

Game state

The game's state was serialised and deserialised back using serde, achieved with little more than a few automatically derived trait implementations. With the use of a textual representation, it was possible to rely on the standard Web local storage to save the game. It wouldn't always work when hosted on itch.io, unfortunately. Browsers are finicky when you depend on storage for a cross-origin resource, and might block it completely. I had to tell players to disable their browser shields in order to save their progress.

There were a few other pieces of information which were passed around in a serialised form through the Drag and Drop API. This in particular felt like a great achievement, as I had to include a custom helper abstraction for access to data transfer properties. This is what made dragging and dropping work. Alas, this API would have required a lot of work in order to support touch events and other forms of feedback that I was hoping to obtain, but were not possible through data transfer alone.
The constraints caused by this were:

The game does not work on mobile devices, although this support would have been wonderful to have.
Feedback about an operation would only appear after the fact: instead of the workboard stage column appearing with a different style when hovering a task over it, I added a message in red at the top of the workboard whenever the player tried to make an invalid move for a task , such as from Backlog directly to Done.

Random stuff

Random events of various sorts were triggered with the help of rand. I found rand_pcg to be nice and fast for the purpose. The ugly story here is that the odds of something happening at a game update tick (be it whether a bug is introduced, a new task should appear, etc.) was achieved with a mishmash of formulae combining a variety of in-game parameters in a very creative way. This came with the problem that they were quite hard to tune, 🔧 which in a way contributed to the game's notably high difficulty. Note to self: create better abstractions for random events next time.

With these events and other game entities generated, the elegance of Rust enabled me to manipulate the game's task in ways which I was already well versed in. Iterators were employed throughout when transforming tasks and updating state based on them.

Yew

Last but definitely not least, I will talk about Yew.

It required me to perform many more .clone()s than the ones I would usually do. This is mostly because component properties had to be owned by each instantiation, although I did not get into whether they this was always necessary. In any case, there were a significant bunch of clones.
The macro based syntax for declaring virtual DOM nodes did the job, but it was quite verbose and a bit tricky to get the hang of. It was annoying that all hardcoded text strings inside had to be enclosed in quotes as well as an expression block (e.g. <div>{"Something"}<\div>), although this may have to do with a limitation of the macro system. As part of a macro, syntax highlighting was constantly broken.
It further reinforced my idea that working with callbacks in Rust is a mess. It is already a paradigm which I strive to avoid, but there is no way to avoid it here. Closures had to capture context in a special way, and interfacing with the JavaScript environment required a bunch of conversions to make things work. There were helper methods to create callbacks interfacing with Yew, but it was still a bit surprising when the program failed to compile once I tried to use some component state without cloning it beforehand. That pattern became clearer, but it still put me to the test of how much I knew about ownership, borrowing, and non-lexical lifetimes.
It was not always clear how one is expected to manage the game's state and trigger changes from user interactions down the tree of elements. I ended up implementing a global event dispatcher that the main game component would listen and handle immediately (e.g. for pop-up messages) or pass on to a game update routine. It was a weird piece, and the primary game component was much more complex than the other ones because of it, but it did just what I was looking for.
It was fast enough. It would have been nice for me to say that it was blazing fast, but I don't have a point of comparison. That would require me to rewrite the whole thing in JavaScript. 🤢 Still, even though the DOM had to be updated around once every 50 ms, this was far from becoming a problem. Most updates would take less than 3 ms each (compiled in release mode) in my personal laptop, 9 ms in debug mode worst case.

The source code is available on GitHub, as is typical in GitHub GameOff. Enjoy.

A social experiment

The idea of making such a nerdy strategy game that puts you in the role of a software engineer wasn't very new. I had kept a similar idea for the right time to work on it, but 10x Sprint Master, albeit just as nerdy an idea as I could come up with, was on a whole different subject: treating the project workboard as the center of all attention in software engineering.

It is worth noting that this game was never meant to make an accurate portrayal of any well known agile methodology, such as Scrum. There may indeed be similarities, but ultimately, this is not Scrum, and I definitely wouldn't depict this game as educational. For all intents and purposes, it was just some method what the fictional company decided to stick to.

Most importantly, this game subjects the player to the encumbering of technical debt in a way which could never happen in real life. Time goes fast, and once you reach unbearable levels of complexity, you are submerged in a pool of deadlines impossible to meet. There is no actual losing condition, but I find it perfectly normal for anyone to give up and exit the game at that point, thus emulating a losing condition all the same.

It is a bit brutal, even if not on purpose. All with the primary goal of accumulating points which don't translate to promotions, raises, or any other kind of advancement or compensation. In retrospective, this game feels like a prank on myself. A self satire of engineering endeavours under the narrow mindset of testing a software project as the means to further work on the same project, where the goal is to optimize for more features, more quality, and less technical debt, all under the guise of a seemingly familiar daily routine.

Maybe next time I'll just build a platformer or something. 😐

You can play 10x Sprint Master on a modern web browser here.

Migrating from quick-error to SNAFU: a story on revamped error handling in Rust

Eduardo Pinho — Fri, 28 Aug 2020 18:36:19 +0000

This post describes my more-than-a-month long story of refactoring existing error definitions and error handling code in my largest project written in Rust. DICOM-rs is a pure Rust implementation of the DICOM standard, the near-ubiquitous standard for representing and communicating medical imaging data. The refactor hereby described on this project was an immediately apparent improvement, enabling me to track down the cause of a recently discovered bug in one of its crates. Read on to learn more!

Note: Basic understanding of error handling in Rust is expected, as the post will be specifically about the thought process of refactoring all error handling from one library to another. Moreover, for a wider overview of modern error handling, I greatly recommend watching Jane Lusby's talk from RustConf 2020.

Why change this?

quick-error served its purpose when it was used in the DICOM-rs ecosystem, which was to facilitate the declaration of multi-variant error types, without the hassle of adding the necessary impl boilerplate of an error type.
It also made it easy (and as we'll see, too easy) to convert a source error into a dedicated variant of our own error type, so that such an error could be automatically converted when necessary.

A quick example (no pun intended):

quick_error! {
    pub enum Error {
        BadIo (e: std::io::Error) {
            display("I/O error: {}", e)
            from()
        }
    }
}

fn do_things() -> Result<(), Error> {
    // now if any function returns a standard I/O error,
    // `?` will just convert it to our `Error` type
    let data = read_my_file()?;                   // here
    std::fs::write("out.bin", processed(data))?;  // and here too
}

It turns out that this approach to error handling has a damaging side-effect: error values E in a Result<T, E> only hold the data that we put in them. They do not keep track of any places where the error was raised with the ? operator, unless we introduce that as part of the conversion into new error types. In this case however, the conversion made in this code introduces no additional information about the context where the operation failed, as I/O errors are always put into the same top-level error variant BadIo. The problem becomes evident when we run our do_things and the only error information we get is the following:

I/O Error: Permission denied

This could well be the display output of an Error::BadIo where the inner error has the kind PermissionDenied. Since this could happen either when reading from a file or when writing to "out.bin", we remain clueless about where the error truly happened.

This error provides poor informative value, which only gets worse as the number of layers in the program increases. The current top layer in DICOM-rs is dicom-object, then followed by two layers of abstraction in dicom-parser, then another one in dicom-encoding. dicom-core is at the bottom, and also has error types of its own. The way these errors were built led to very poor quality error outputs when errors occurred (e.g. PrematureEof could be the full error output when trying to read a file). Worse, since they did not contain a backtrace, the program would not give us the lines of code that led into the error, much unlike in a panic, where by default it would be provided, usually by setting the RUST_BACKTRACE environment variable.

It was clear enough for me that the error types in DICOM-rs
should be more informative, and should contain a backtrace if desired.

What else then?

The world of error handling in Rust has seen substantial
changes. In its early stages, quick-error and error-chain were commonly employed to create errors with ease. error-chain in particular was known for its emphasis on chaining error causes, pretty much as the name implies. failure emerged with a new error interface that would allow users to cast down the cause of an error, something which was missing in the standard definition. Eventually, std::error::Error was in fact updated to accommodate this major benefit from failure.

In recent times, error handling libraries aim to provide utilities for:

declaring structural error types with automatic trait implementations, (usually via procedural macros, which were unstable back in 2016);
easier fact checking and/or error throwing through the program stack;
presenting errors to the user in a human readable fashion;
adding compatibility layers to the generation of backtraces, even with a stable Rust toolchain;
an alternative error handling syntax.

Some libraries are intended to be used exclusively, whereas others can complement with existing code (e.g. fehler). The ones most commonly heard about these days are thiserror, anyhow, eyre, and snafu.

Why SNAFU?

thiserror provides similar benefits to quick-error, with the plus that it uses nicely integrated procedural macros instead of rule-based macros. Those who have played with them a lot will often find diagnostics to be substantially better in the former. It also means that we do not need to increase the compiler's recursion limit whenever our error type increases in size, a consequence of the quick_error! macro being defined in a recursive fashion. On the other hand, there isn't much else about it, so I could easily be taking the risk of simply rewriting errors without gaining the intended enhancements.

anyhow and eyre are mostly designed for applications, as they facilitate the aggregation of multiple error types into a single source of information about the error. This error can be expanded across the program stack via the extended context operator, hence gaining additional information. They deliberately employ a "kitchen-sink" error type, which is more complicated to take part in code flow if necessary. When it comes to libraries, structured error types are usually preferred. Using one of these in CLI tools under the domain of DICOM-rs (such as dcmdump) is not out of the question, but is currently left as a backlog task.

And then there's SNAFU, which comes with:

an opinionated procedural macro for declaring error types and variants;
compile-time generated constructs for context building and automatic backtrace generation;
support for both standard (unstable) and stable (crate-based) backtraces;
and a well established philosophy on how error types should be designed.

As a project which may grow in unexpected ways, I wanted a library which could also adapt to that scale. Although opinionated, SNAFU incentivizes all the way towards well structured and useful errors.

Things to keep in mind

Next is a set of topics which will hopefully transmit the experience that I gathered while doing this rewrite,
and may help bring new ideas into your own error handling strategy.

Follow the guidelines

This one is the most obvious. To make error types with SNAFU, one will have a better experience if you follow the advice given in the documentation.

One of the most relevant topics is to prefer module-level error types over crate-level error types. If your code is well organised in its module hierarchy, then it is also likely that those modules will face a different set of errors. For example, the dicom-encoding crate is focused on decoding and encoding primitive DICOM data structures from/into a medium (often a file or the network).
In either case, a std::io::Error could be the root cause of the error, but the circumstances of reading and writing are distinct and may often have their own kinds of errors (e.g. invariant checking when reading data headers). By creating an error type for decoding and another one for encoding, errors will be more focused and only need to be as complex as they need to be.

Go top-down, not bottom-up

When rewriting existing code, it is much easier to start with errors which emerge at a higher abstraction level. Every change in a crate's error types needs to be propagated into its dependents. If the same dependents are not structured in a way as to be prepared for this change, the amount of code that needs to be rewritten at the top will increase.

At some point during this refactor, I had something like the error type below at the DICOM object file reading module level. This is a high level abstraction over DICOM data sets, so as to be perceived as a dictionary of attributes.

#[derive(Debug, Snafu)]
pub enum Error {
    // ...
    #[snafu(display("Could not read data set token"))]
    ReadToken {
        source: dicom_parser::error::Error,
    },
    // ...
}

dicom_parser::error::Error is the crate-level error for the mid-level parser and printer of DICOM data, yet to be refactored. dicom-parser actually gathers two levels of abstraction here, something which definitely does not favour the decision to use a single error type for all modules in the crate.

Once we follow the advice of keeping one or more errors per module, we'll have more specific errors and the code above will fail. However, if the variants were well defined, the error to choose for the variant ReadToken will be quite intuitive, requiring no further changes other than the source type.

#[derive(Debug, Snafu)]
pub enum Error {
    // ...
    #[snafu(display("Could not read data set token"))]
    ReadToken {
        #[snafu(backtrace)]
        source: dicom_parser::dataset::read::Error,
    },
    // ...
}

I had tried to convert dicom-core to use SNAFU at least twice until I admitted that this wasn't the right way. It would blow up most of the other crates in the project and require me to either change the entire thing at once or make changes that would eventually be rewritten anyway.

Work with the error type selectors, not against them

Some parts of the documentation may be easy to miss out, because some of the methods do not exist in a single struct or trait. Rather, error type selectors are procedurally built, and hidden behind the Snafu macro.

As for a concrete example, if we have this:

#[derive(Debug, Snafu)]
pub enum Error {
    #[snafu(display(
        "Undefined value length of element tagged {} at position {}",
        tag,
        position
    ))]
    UndefinedValueLength {
        tag: Tag,
        position: u64,
        backtrace: Backtrace,
    }
}

One might think that we need to write this to build the error:

header
    .length()  // custom length type
    .get()     // Option<_>
    .ok_or_else(|| Error::UndefinedValueLength {
        position: self.bytes_read,
        tag: header.tag,
        backtrace: Backtrace::generate(),
    })

When in fact the same process is substantially easier and less error prone with selectors:

header
    .length()
    .get()
    .context(UndefinedValueLength {
        position: self.bytes_read,
        tag: header.tag,
    })

The context method encapsulates information about a specific error variant, while optionally encapsulating an error and generating backtraces. And all it takes to have this context method is to have our Snafu-built error type and import snafu::ResultExt and/or snafu::OptionExt.

Even when context isn't suitable (which is when you don't have a result nor an option), you can call .build() or.fail() on top of a selector.

let string = date_str();
if !is_valid_date(&string) {
    return InvalidDateValue {
        position: self.bytes_read,
        string,
    }
    .fail();
}

In fact, you should never really need to create errors manually.

Libraries, stabilize your APIs

As an ecosystem mostly comprised of libraries, it is admitted that changing any of these public error enum types leads to a breaking change, which would introduce a barrier to an eventual upgrade.

One easy step that gives more freedom to public error types is adding #[non_exhaustive]. This makes it so that matching on the value requires a "catch-all" match arm, which means that introducing new variants will not break existing code.

There usually isn't a need to exhaustively consider each error variant, so this change brings immediate benefits with little undesirable consequences. The same attribute can be applied to the struct variants themselves, so that adding more contextual fields to an error variant also does not lead to a major breaking change.

#[derive(Debug, Snafu)]
#[non_exhaustive]
pub enum Error {
    // ...
    #[snafu(display("Could not read data set token: {}", source))]
    #[non_exhaustive]
    ReadToken {
        #[snafu(backtrace)]
        source: dicom_parser::dataset::read::Error,
    },
    // ...
}

You can also choose to make an error opaque. Opaque errors are reported with the same information, except that their implementation is behind private constructs, therefore purposely limiting the interactions possible with that error. As users of the API cannot touch the implementation details of the error, any change will not break existing code, although it may change the errors displayed.

#[derive(Debug, Snafu)]
pub enum Error(InnerError);

#[derive(Debug, Snafu)]
#[non_exhaustive]
enum InnerError {  // no longer public
    // ...
}

Backtrace? What backtrace?

At some point before this refactor, I had this shallow idea that all I was missing in an error report was the backtrace to the part of the code that constructed the error. However, SNAFU advocates for semantic backtracing: to have good enough error types and variants, conveying enough information so that you don't need a backtrace in practice.

The current recommendation would be to introduce a backtrace on leaf error variants, either always generated or conditionally generated (by wrapping an Option around it), and see for yourself how useful they are. My early experience so far is that a backtrace makes reaching the problematic code a bit easier, but semantic backtracing already provides an outstanding clue of what the issue might be.

Ready to report?

Consider thinking about how you are going to report the errors to the user, and adjust your display implementations accordingly.

Most examples in the SNAFU guide show the following pattern:

#[derive(Debug, Snafu)]
#[non_exhaustive]
pub enum Error {
    #[snafu(display("Could not read data set token: {}", source))]
    #[non_exhaustive]
    ReadToken {
        #[snafu(backtrace)]
        source: dicom_parser::dataset::read::Error,
    },
}

Notice how the source field is chained to the tail of
the type's display implementation. This makes it so that a single line print is enough to present all information about the error (minus the backtrace).

eprintln!("[ERROR] {}", e);

One possible output:

[ERROR] Could not read data set token: Could not read item value: Undefined value length of element tagged (5533,5533) at position 3548

However, this will not integrate well with other error reporting facilities, such as anyhow or eyre, which are already prepared to traverse the chain of error causes and show them individually.

If we were to turn our error into an eyre::Report and print that:

eprintln!("[ERROR] {:?}", eyre::Report::from(e));

We get these maddening repetitions:

[ERROR] Could not read data set token: Could not read item value: Undefined value length of element tagged (5533,5533) at position 3548

Caused by:
   0: Could not read item value: Undefined value length of element tagged (5533,5533) at position 3548
   1: Undefined value length of element tagged (5533,5533) at position 3548

In this case, we would want a display message that does not print its source error.

This issue is not necessary specific to eyre, but will emerge any time that you use a different kind of error reporter. An equivalent report function in SNAFU would be quite similar:

fn report<E: 'static>(err: &E)
where
    E: std::error::Error,
    E: snafu::ErrorCompat,
    E: Send + Sync,
{
    eprintln!("[ERROR] {}", err);
    if let Some(source) = err.source() {
        eprintln!();
        eprintln!("Caused by:");
        for (i, e) in std::iter::successors(Some(source), |e| e.source()).enumerate() {
            eprintln!("   {}: {}", i, e);
        }
    }

    if let Some(backtrace) = ErrorCompat::backtrace(err) {
        eprintln!("Backtrace:");
        eprintln!("{}", backtrace);
    }
}

(Note: This reporter will always try to print an existing backtrace, regardless of environment variables set.)

So yes, you need to define upfront how your errors are supposed to be reported:

Implement error displays that show the full chain of errors, so that consumers only have to call a standard print function;
Or leave the task of showing the list of causes to a reporter, hence giving more flexibility to the consumer of the API.

There currently isn't an easy way to switch from one to the other. I chose the latter for DICOM-rs because I am interested in maintaining control of how errors are reported
in the project, and I can easily adjust all application crates accordingly. There are also chances of this pattern to become more common place in the wider Rust ecosystem.

Conclusion

In the end, I cannot claim that this was simply the best rewrite one could do, but I can say that rewriting it was a good decision. With a pull request comprising +4,694/−2,900 lines in 23 commits, the quick-error dependency was removed and snafu took over, much to the delight of future users of the DICOM-rs ecosystem.

As DICOM-rs may one day be a cornerstone of future generations of medical imaging software, this refactor came not a moment too soon. Future work will concentrate on other important matters that might be worth communicating as well. Among the topics in the project's roadmap, there is logging, lazy file loading, a data-oriented test harness, and a higher-level image abstraction.

Rust 2020: Tropes and Jargon

Eduardo Pinho — Tue, 12 Nov 2019 23:37:02 +0000

Dear Rust community,

I am writing this to announce a lame, but hopefully fruitful confession through this post. I had originally intended to make this a Twitter thread, but eventually the Rust 2020 call for posts emerged, and I saw it as an opportunity to expand this.

It's not that much of a surprise when I say that there is a time and place for everything. Even a community in tech, such as the Rust community, may not only be concerned about the next generation of software, but may also be interested in establishing grounds for creativity and room for inside jokes. One day, while writing .map(|_| ()), I realised how the closure inside looked like a toilet rotated 90 degrees counter-clockwise. So I tweeted this in May 2017, and started using the expression since.

// Detect dark theme var iframe = document.getElementById('tweet-869303385513656320-735'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=869303385513656320&theme=dark" }

On the other hand, most of those who already knew about the toilet closure might have seen it from Reddit, around June 2018. Yup, that was also me. Memes will slowly and softly deduct my sanity.

And yet this toilet is as pertinent in Rust code as it was 2 years ago, perhaps even more due to the latest advances in asynchronous programming with Rust. And it is very often preferred over drop.

// Detect dark theme var iframe = document.getElementById('tweet-1156577337204465664-148'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1156577337204465664&theme=dark" }

So yes, I was likely the one who coined "toilet closure". Although I agree we should be grabbing our leads tighter ("less jargon", as suggested by Llogiq), this process is almost organic and not entirely avoidable on the behalf of a community presenting superior levels of enthusiasm.

Nonetheless,the part that worries me most is how hard it is to search about these things. We happen to have great technical resources out there, but not for such a jargon as "toilet closure". This one is particularly tricky to search about, as you end up with public plumbing issues instead.

So I came up with this idea of uniting all this jargon, tropes, acronyms, and other expressions into an open-source repository. Rust Tropes intends to be a community-curated list of expressions and concepts which may emerge when talking about Rust or when engaging with other Rustaceans, some of which are not necessarily technical.

This is a work in progress, and I hope to receive some assistance. Feel free to contribute with more content, better styling, and other things. https://github.com/Enet4/rust-tropes
Your assistance in spreading and expanding this source is much appreciated, and it's one of my wishes for Rust 2020 for this resource to have some usefulness to all the confused people out there wondering what pre-pooping your pants is, or why unsafe code attracts laundry connoisseurs.

Also, we could really use GATs.

DEV Community: Eduardo Pinho

A new milestone: what's new in DICOM-rs 0.6.0

So what's new?

Attribute selectors

Improved object and value ergonomics

Operations API

UID constants and SOP class dictionary

DICOM JSON support

Pixel data adapter API redesign

New website

What's next?

Timely wrap-up: some (not so) quick notes on Timely Defuse

Preface

Introducting Timely Defuse

Conceiving the idea

Technical notes

Mobile first

Using Bevy

Easy to bootstrap

Systems, systems, syssytsetmsems

My kingdom for an essential resource

UI nodes

Safety obstacles

Compilation times

Conclusion

Writing bindings to `dos-like` for Rust: some lessons learned

Compiling and static linking

Is this a library?

Is that an int?

Exclusive, safe video memory access? Pick one.

Returning small arrays? One simple trick.

Validated resource identifiers

10x Sprint Master: a technical and social experiment

Description

A technical experiment

Primary tooling

Graphics and design

Using Rust

Game state

Random stuff

Yew

A social experiment

Migrating from quick-error to SNAFU: a story on revamped error handling in Rust

Why change this?

What else then?

Why SNAFU?

Things to keep in mind

Follow the guidelines

Go top-down, not bottom-up

Work with the error type selectors, not against them

Libraries, stabilize your APIs

Backtrace? What backtrace?

Ready to report?

Conclusion

Rust 2020: Tropes and Jargon

Is that an `int`?