Jack Sometimes Writes

Today, I’m announcing scoped-trace, a crate for capturing scoped, tree-like execution traces.

Here are the crate’s important links:

• https://crates.io/crates/scoped-trace
• https://docs.rs/scoped-trace
• https://github.com/jswrenn/scoped-trace

As my first full calendar year in the Rust Platform Team at AWS draws to a close, I thought it might be illuminating to reflect on what I worked on. The breadth of crates I released or contributed to surprised me! Time really does fly when you’re having fun.

Today, I’m releasing deflect, an implementation of reflection for Rust. Deflect can be used to recover the concrete types of trait objects, inspect the internal state of async generators, pretty-print arbitrary data, and much more.

With my PhD drawing to a close, I’m on the job market! I’ll need a slick resume ASAP, but how to typeset it?

Microsoft Word?

...don't have it.

LaTeX?

...don't have the patience for it.

HTML + CSS?

...now that could work!

(Part of an ongoing series!)

In the last two posts, repr(transparent) provided an unusual mechanism by which safe, downstream code could inadvertently rely on the size and alignment of an upstream type. In this post, I’ll recap the issue and discuss why it is tricky to fix.

(Part of an ongoing series!)

In Rust, changes to a type’s alignment are not usually understood to be Breaking Changes™. Of course, that isn’t to say you can’t break safe, downstream code by changing the alignment of a type…

(Part of an ongoing series!)

In Rust, changes to a type’s size are not usually understood to be Breaking Changes™. Of course, that isn’t to say you can’t break safe downstream code by changing the size of a type…

At the heart of Semantic Versioning is a distinction between incompatible API changes (“breaking” changes) and backwards-compatible API changes (“non-breaking” changes). When you make a change that could break existing code, you must increment the MAJOR component of its version number. Since failing to do this correctly may cause builds or tests to fail seemingly-spontaneously, knowing what kinds of changes are breaking and which are not is crucial to good crate hygiene.

In September 2020, Brown University accused students of lying about their location; e.g.:

What was Brown’s basis for these accusations?

• What’s the most expensive required textbook at Brown?
• What’s the most expensive class?
• What’s the most expensive department?

To de-densify campus, Brown University moved to a three-term model in which students take courses for two of three possible terms. This third term will be carved out of the summer months of 2021, during which an unlucky subset of the student body will swiftly discover that Brown does not air-condition its dorms. So, who are these unenviable souls? Well, first-years, obviously, who will begin in the spring semester and continue through the summer.

To compensate them for this inconvenience, Brown has extended all first-years the opportunity to remotely take one course this Fall, for free! How many took Brown up on this offer?

University Admissions departments love to brag about their schools’ small class sizes. Brown University, for instance, boasts a 7:1 student–faculty ratio (so “you’ll have a lot of face-to-face time with some of the best researchers and teachers in academia”) and that “72 percent of our undergraduate classes have fewer than 20 students.” These claims invite prospective students to daydream of cozy, intimate classrooms, and personalized learning experiences — dreams quashed (or perhaps squished?) on one’s first day of classes.

Nobody is lying, per se — this is merely an instance of the “class size paradox”: the size of the average class is relatively small, but the experience of the average student suggests otherwise.

In Rust, the impl keyword doesn’t have an associated visibility; there’s no such thing as pub impl. However, that isn’t to say that implementations don’t have visibility—they do! Enter: RFC2145 - Type Privacy.

In Rust, the methods of a trait inherit the visibility of the trait itself:

pub trait Foo<Arg> {

    pub(self) fn foo(&self, arg: Arg);

    /* other public methods */

}

error[E0449]: unnecessary visibility qualifier
 --> src/lib.rs:7:3
  |
7 |   pub(self) fn foo(&self, arg: Arg);
  |   ^^^^^^^^^

At minimum, we should hide this method from our documentation:

pub trait Foo<Arg> {

    #[doc(hidden)]
    fn foo(&self, arg: Arg);

    /* other public methods */

}

…but this doesn’t actually prevent outsiders from calling our method! Fortunately, there are at least three other patterns #[doc(hidden)] can be combined with to make foo externally unusable.

Nalgebra is a powerhouse of functionality, but its documentation can be overwhelming—the documentation for Matrix lists over 600 methods. Your documentation endeavors might not be quite so overwhelming, but you still could benefit from these three tricks nalgebra uses to improve its docs.

What’s up with transmutation stability?

Rust’s include_bytes! macro lets you statically include the contents of a file into your executable’s binary. The builtin is a quick-and-dirty solution for packaging data with your executable, and perhaps even helping the compiler optimize your code! Unfortunately, it’s difficult to use correctly.

Using Generators to Modernize a Geriatric Javascript API for $CURRENT_YEAR