Lesley Lai's Blog

A Love Letter to Flashcards

Tue, 05 May 2026 00:00:00 GMT

This piece is a submission for IndieWeb Carnival May 2026: Write a love letter.

For a long time, flashcards were not on my radar for effective learning. I used it for English vocabulary when I was learning English as a teen, but I never considered using it for subjects that require deep understanding. When thinking about flashcards, an image that swiftly sprang to mind was of someone who mechanically memorizes definitions and equations, brute-forces through exams without comprehension. Such rote memorization is indeed detrimental to learning. This sentiment is common in STEM fields. A quick search leads to reddit posts like this where higher upvoted answers dismiss the value of flashcards.

My perception changed through the learning how to learn course, where I relearned about Spaced repetition, the technique of reviewing topics at increasing intervals. Using spaced repetition as a general-purpose learning tool (rather than just for rote memorization of vocabulary) was perhaps the most important thing I learned from that course. The course also specifically mentioned Anki, perhaps the most famous flashcard software, as a way to facilitate spaced repetition.

I had a particular reason to take this seriously: my memory is terrible. I often even forget what I did the day before, and the same goes for things I’ve studied. Math is the worst. I learned it in intensive bursts, but I rarely use it day to day, and what I study now might not be useful for another five years. Naturally, calculus, linear algebra, probability, and even high school trigonometry have all quietly slipped away.

It turns out that math is very cumulative: theorems built upon theorems. If I am not fluent in the basics, I will quickly be inundated with all the new material. There is a psychological concept called chunking that describes the inverse of this: once one internalizes the basics, they can think at a higher level of abstraction. From this perspective, fields that require deep understanding, like math, require memory just as fields with a breadth of shallow knowledge do, though in different ways.

Now you may think that with today’s abundance of information, we can look up everything pretty quickly. That is true. But the quickest search is slower than your brain. Moreover, not everything can be easily looked up, especially what falls into insights rather than definitions. When you look it up, you will only find lengthy articles to impart their wisdom, and that will take weeks to digest (again, if you have learned but forgotten).

How do I actually use flashcards? My software of choice is Anki. I am not completely satisfied with it. The UI looks dated, the WYSIWYG HTML editor is clunky, and the undocumented file format makes potential porting and interoperability tricky. However, its ability to have a flexible card format is unparalleled. I’ve tried a few plain-text-based alternatives like Obsidian’s Spaced Repetition plugin, but they are not even remotely close to what I need.

I don’t use spaced repetition to replace traditional learning. In fact, it takes up only a small portion of my total learning time. One thing that’s right about the “common sense” in the STEM fields is that without understanding, flashcards are useless. You need to understand the materials first, and reading flashcards written by others is a really poor way to do that. Two corollaries follow:

don’t memorize what you don’t understand
prefer your own flashcards to other people’s flashcards, at least for fields that require deep understanding

But once I understand something, flashcards are effective to keep the understanding alive.

When I started making flashcards, I looked at many flashcard decks from other sources, such as Anki’s Shared Decks and Quizlet, for inspiration. I found that most decks floating around on the Internet are of poor quality. They are usually definitions and facts semi-mechanically transcribed from a textbook.

I do something different. Most of my cards are handwritten by me and accommodate my brain.

While I have definition and fact cards, I also have many cards on intuition and “A-ha moments”. Those fade from memory, too, so it’s worth preserving them. Here is an example (feel free to skip if you are not familiar with the topic, but I intentionally picked something that I hope is easy to understand):

Q: What is the intuition that two reflections gives a rotation?

A: Both reflection and rotations are orthogonal transformations. The difference is that rotation preserves orientation while reflection flips it. If we apply the reflection twice, the first reflection flips the orientation and the second reflection flips it back. Also, if we apply multiple orthogonal transformations, the combined transformation is still orthogonal. Thus, at the end we get an orthogonal transformation that is orientation-preserving, which is a rotation.

See:

I add images whenever I can, and I often link back to the source materials where I learned the topic, in case I want to revisit. I also tie the flashcard-making habit with my note-taking habit. For example, the above card example is directly the result of the note on two reflections give a rotation in my digital garden.

Spaced repetition is not just for memorization; it can probably be viewed as a scheduled, recurrent task. So I put in things that people might not consider appropriate for flashcards. For example, I have a deck for math problems that I did wrong in the past. I use this basically to schedule practices. I put them into a separate Anki deck because I can only practice math with pen and paper, and definitely cannot do it outside.

The “recurrent tasks” perspective also gives me another insight: each card is a burden, so don’t be afraid to delete cards you don’t need. I generally spend around 1 to 30 minutes reviewing old Anki cards per day, depending on how many cards I added in previous days. I want to keep it as lightweight and low-overhead as possible, and that’s the only way I can keep this habit.

Nevertheless, the little time spent reviewing cards (and much more time writing them) is already worthwhile. I often pick up learning projects like a book and an online course, get busy with life, and pause them for a year. I used to forget everything. Now, after a year, I can still just pick up where I left off. How cool is that?

Is this all just illusion and confirmation bias? I don’t know. People are notoriously bad at judging their own learning and productivity. While there is an abundance of evidence on spaced repetition, the empirical evidence on Anki specifically is thin and drawn mostly from studies of medical students rather than from STEM fields. However, we make decisions with imperfect knowledge all the time. For me, this one has been worth it.

Resources

Effective Spaced Repetition - Give a lot concrete examples on how to make flashcards. This was one article I read to get started

Fifty Shades of OOP

Mon, 24 Nov 2025 00:00:00 GMT

OOP-bashing seems fashionable nowadays. I decided to write this article after seeing two OOP-related articles on Lobsters in quick succession. I’m not interested in defending or attacking OOP, but I do want to throw in my two cents and offer a more nuanced view.

The industry and the academy have used the term “object-oriented” to mean so many different things. One thing that makes conversations around OOP so unproductive is the lack of consensus on what OOP is.

What is Object-Oriented Programming? Wikipedia defines it as “a programming paradigm based on the concept of objects.” This definition is unsatisfactory, as it requires a definition of an “object” and fails to encompass the disparate ways the term is used in the industry. There is also Alan Kay’s vision of OOP. However, the way most people use the term has drifted apart, and I don’t want to fall into essentialism or etymological fallacy by insisting on a “true” meaning.

Instead, I think it is better to treat OOP as a mixed bag of interrelated ideas and examine them individually. Below, I will survey some ideas related to OOP and mention their pros and cons (in my subjective mind).

Classes

Object-oriented programming is a method of implementation in which programs are organized as cooperative collections of objects, each of which represents an instance of some class, and whose classes are all members of a hierarchy of classes united via inheritance relationships. — Grady Booch

Classes extend the idea of a “struct” or “record” with support for the method syntax, information hiding, and inheritance. We will talk about those specific features later.

Classes can also be viewed as blueprints for objects. It is not the only way to do that, and prototypes is an alternative pioneered by Self and, most famously, used by JavaScript. Personally, I feel that prototypes are harder to wrap one’s head around compared to classes. Even JavaScript tries to hide its usage of prototypes from newcomers with ES6 classes.

Method Syntax

In Japanese, we have sentence chaining, which is similar to method chaining in Ruby — Yukihiro Matsumoto

The method syntax is one of the less controversial OOP features. It captures common programming use cases involving operations on a specific subject. Even in languages without methods, it is common to see functions effectively serve as methods by taking the relevant data as their first argument (or last, in languages with currying).

The syntax involves method definitions and method calls. Usually, languages supporting methods have both, unless you consider the “pipe operators” in functional languages as a form of method call.

The method call syntax aids IDE autocompletion, and method chaining is often more ergonomic than nested function calls (similar to the pipe operator in functional languages).

There are some debatable aspects of the method syntax, too. First, in many languages, methods are often not definable outside of a class, which causes a power imbalance compared to functions. There are certain exceptions, such as Rust (methods are always defined outside of the struct), Scala, Kotlin, and C# (extension methods).

Second, in many languages, this or self is implicit. This keeps the code more concise, but it can also introduce confusion and increase the risk of accidental name shadowing. Another drawback of an implicit this is that it is always passed as a pointer, and its type cannot be changed. This means you cannot pass it as a copy, and sometimes this indirection leads to performance issues. More importantly, because the type of this is fixed, you cannot write generic functions that accept different this types. Python and Rust got this right from the start, and C++ just fixed this issue in C++23 with deducing this.

Third, in languages with both “free functions” and methods, they become two incompatible ways to do the same thing. This can cause problems in generic code. Rust addresses this issue by allowing fully qualifying a method name and treating it as a function.

Fourth, the dot notation is used for both instance variable accesses and method calls in most languages. This is an intentional choice to make methods look more uniform with objects. In certain dynamically typed languages where methods are instance variables, this is fine and pretty much not even a choice. On the other hand, in languages like C++ or Java, this can cause confusion and shadowing problems.

Information Hiding

Its interface or definition was chosen to reveal as little as possible about its inner workings — [Parnas, 1972b]

In Smalltalk, all instance variables are not directly accessible from outside the object, and all methods are exposed. More modern OOP languages support information hiding via access specifiers like private at the class level. Even non-OOP languages usually support information hiding in some way, be it module systems, opaque types, or even C’s header separation.

Information hiding is a good way to prevent invariant from being violated. It is also a good way to separate frequently changed implementation details from a stable interface.

Nevertheless, aggressively hiding information may cause unnecessary boilerplate or abstraction inversion. Another criticism comes from functional programmers, who argue that you don’t need to maintain invariants and thus don’t need much information hiding if data is immutable. And, in a sense, OOP encourages people to write mutable objects that must be maintained as invariants.

Information hiding also encourages people to create small, self-contained objects that “know how to handle themselves,” which leads directly into the topic of encapsulation.

Encapsulation

If you can, just move all of that behavior into the class it helps. After all, OOP is about letting objects take care of themselves. — Bob Nystrom, Game Programming Patterns

Encapsulation is often confused with information hiding, but the two are distinct. Encapsulation refers to bundling data with the functions that operate on it. OOP languages directly support encapsulation with objects/classes and the method syntax, but there are other approaches. Many modern languages also support closures (in fact, closures and objects can simulate each other). There are also other lesser-known approaches, such as the module system found in the ML family.

Data-oriented design has a lot to say about bundling data and functionality. When many objects exist, it is often much more efficient to process them in batches rather than individually. Having small objects with distinct behaviors can lead to poor data locality, more indirection, and fewer opportunities for parallelism. Of course, advocates of data-oriented design don’t reject encapsulation outright, but they encourage a more coarse-grained form of it, organized around how the code is actually used rather than how the domain model is conceptually structured.

Interfaces

“No part of a complex system should depend on the internal details of any other part.” — Daniel, Ingalls. “The Smalltalk-76 Programming System Design and Implementation”

Separation of interface and implementation is an old idea closely related to information hiding, encapsulation, and abstract data type. In some sense, even C’s header files can be considered an interface, but OOP usage of “interface” most often refers to a specific set of language constructs that support polymorphism (typically implemented via inheritance). Usually, an interface can’t contain data, and in more restricted languages (e.g., early versions of Java), they can’t contain method implementations either. The same idea of an interface is also common in non-OOP languages: Haskell type classes, Rust traits, and Go interfaces all serve the role of specifying an abstract set of operations independent of implementations.

Interface is often considered a simpler, more disciplined alternative to full-blown class inheritance. It is a single-purpose feature and doesn’t suffer from the same diamond problem that plagues multiple inheritance.

Interface is also extremely useful in combination with parametric polymorphism, since it allows you to constrain the operations a type parameter must support. Dynamically-typed languages (and C++/D template) achieve something similar through duck-typing, but even languages with duck-typing introduce interface constructs later to express constraints more explicitly (e.g., C++ concepts or TypeScript interfaces).

The interface as implemented in OOP languages often has a runtime cost, but that’s not always the case. For example, C++ concepts is an example that only supports compile-time, and Rust’s trait only has opt-in runtime polymorphism support via dyn.

Late Binding

OOP to me means only messaging, local retention and protection and hiding of state-process, and extreme late-binding of all things — Alan Kay

Late binding refers to delaying the lookup of a method or a member until runtime. It is the default of most dynamic-typed languages, where method calls are often implemented as a hash table lookup, but can also be achieved with other means, such as dynamic loading or function pointers.

A key aspect of late binding is that behaviour can be changed while the software is still running, enabling all kinds of hot-reloading and monkey-patching workflows.

Consider the following Python program:

def bar():
    return foo() + 1

def foo():
    return 42

print(bar()) # 43

def foo():
    return 100

print(bar()) # 101

Note that foo is not defined when bar is defined. The name lookup for foo happens when bar is called. The first call to bar is already interesting, though the same effect can still be achieved in other languages via constructs that makes functions mutually recursive (e.g. forward declaration or letrec).

The more crucial point is the second part of the example. Before the second call to bar, we changed foo’s implementation, and the call to bar automatically reflects that. This is not something achievable without late binding.

The downside of late binding is its non-trivial performance cost. Moreover, it can also be a footgun for breaking invariants or even interface mismatches. Its mutable nature can also introduce subtler issues, for example, the “late binding closures” pitfall in Python.

Dynamic Dispatch

A programming paradigm in C++ using Polymorphism based on runtime function dispatch using virtual functions — Back to Basics: Object-Oriented Programming - Jon Kalb - CppCon 2019

A concept related to late binding is dynamic dispatch, in which the implementation of a polymorphic operation is selected at runtime. The two concepts overlap, though dynamic dispatch focuses more on selecting multiple known polymorphic operations rather than on name lookup.

In a dynamically typed language, dynamic dispatch is the default since everything is late-bound. In statically typed languages, it is usually implemented as a virtual function table that looks something like this under the hood:

struct VTable {
  // function pointer to destroy the base
  void (*destroy)(BaseClass&);

  // function pointer to one method implementation
  void (*foo)();

  // function pointer to another method implementation
  int (*bar)(int);
};

struct BaseClass {
  VTable* vtable;
};

These languages also provide compile-time guarantees that the vtable contains valid operations for the type.

Dynamic dispatch can be decoupled from inheritance, whether by manually implementing a v-table (e.g., C++‘s “type-erased types” such as std::function) or an interface/trait/typeclass kind of constructs. When not paired with inheritance, dynamic dispatch alone is usually not considered “OOP.”

Another thing to note is that the pointer to the v-table can be directly inside the object (e.g., C++) or embedded in “fat pointers” (e.g., Go and Rust).

Complaints about dynamic dispatch are usually about its performance. Although a virtual function call itself can be pretty fast, it opens room for missing compiler inlining opportunities, cache misses, and branch mispredictions.

Inheritance

programming using class hierarchies and virtual functions to allow manipulation of objects of a variety of types through well-defined interfaces and to allow a program to be extended incrementally through derivation — Bjarne Stroustrup

Inheritance has a long history, way backed to Simula 67. It is probably the most iconic feature of OOP. Almost every language marketed as “object-oriented” includes it, while languages that avoid OOP typically omit it.

It can be damn convenient. In many cases, using an alternative approach will result in significantly more boilerplate.

On the other hand, inheritance is a very non-orthogonal feature. It is a single mechanism that enables dynamic dispatch, subtyping polymorphism, interface/implementation segregation, and code reuse. It is flexible, though that flexibility makes it easy to misuse. For that reason, some languages nowadays replace it with more restrictive alternative constructs.

There are some other problems with inheritance. First, using inheritance almost certainly means you are paying the performance cost of dynamic dispatch and heap allocation. In some languages, such as C++, you can use inheritance without dynamic dispatch and heap allocation, and there are some valid use cases (e.g., code reuse with CRTP), but the majority of uses of inheritance are for runtime polymorphism (and thus rely on dynamic dispatch).

Second, inheritance implements subtyping in an unsound way, requiring programmers to manually enforce the Liskov substitution principle.

Finally, inheritance hierarchies are rigid. They suffer from issues like the diagonal problem, and that inflexibility is one of the main reasons people prefer composition over inheritance. The component pattern chapter of Game Programming Patterns provides a good example.

Subtyping Polymorphism

If for each object of type there is another object of type such that for all programs defined in terms of , the behavior of is unchanged when is substituted for , then is a subtype of . — Barbara Liskov, “Data Abstraction and Hierarchy”

Subtyping describes an “is a” relation between two types. The Liskov substitution principle defines the property that safe subtyping relationships must uphold.

OOP languages often support subtyping via inheritance, but note that inheritance doesn’t always model subtyping, and it is not the only form of subtyping either. Various interface/trait constructs in non-OOP languages often support subtyping. And besides nominal subtyping, where one explicitly declares the subtyping relationship, there are also structural subtyping, where the subtyping is implicit if one type contains all the features of another type. Good examples of structural subtyping include OCaml (objects and polymorphic variants) and TypeScript interfaces. Subtyping also shows in all kinds of little places, such as Rust lifetime and TypeScript’s coercion from a non-nullable type to its nullable counterpart.

A related concept to subtyping is variance (not related to class-invariant), which bridges parametric polymorphism and subtyping. I won’t bother explaining variance here, as this topic probably needs an entire blog post to explain well. It is a great ergonomic boost (e.g., C++ pointers will be unusable for polymorphic use if they are not covariant), but most languages only implement a limited, hard-coded version, because it is hard to understand and also error-prone. In particular, mutable data types should usually be invariant, and Java/C#‘s covariant arrays are a primary example on this gone wrong. Only a few languages allow programmers to explicitly control variance, including Scala and Kotlin.

Type conversion via subtyping relationships is often implicit. Implicit conversion has a bad reputation. Though doing it with subtyping is ergonomic, and is probably the least surprising kind of implicit conversion. Another way to view subtyping is as the dual of implicit conversions. We can “fake” a subtyping relation with implicit conversion. For example, C++ templated types are invariant, but std::unique_ptr achieves covariance with an implicit conversion from std::unique_ptr<Derived> to std::unique_ptr<Base>. Does Go Have Subtyping? is a good article to further explore this idea.

One reason that language designers often try to avoid subtyping is the implementation complexity. Integrating bidirectional type inference and subtyping is notoriously difficult. Stephen Dolan’s 2016 thesis Algebraic Subtyping makes good progress addressing this issue.

Message Passing

I thought of objects being like biological cells and/or individual computers on a network, only able to communicate with messages — Alan Kay

Message passing means using objects that send each other “messages” as a way of execution. It is the centric theme of Alan Kay’s vision of OOP, though the definition can be pretty vague. An important point is that message names are late-bound, and the structures of these messages are not necessarily fixed at compile time.

Many early object-oriented concepts were influenced by distributed and simulation systems, where message passing is natural. However, in the era where most people work on single-threaded code, the message was gradually forgotten in languages such as C++ and Java. The method syntax only has limited benefit compared to the original message-passing idea (Bjarne Stroustrup was definitely aware of the idea from Simula, but there is practical constraint on how to make it fast). There was still some genuine message passing, but only in specific areas such as inter-process communication or highly event-driven systems.

Message passing gains a Renaissance in concurrent programming, ironically through non-OOP languages like Erlang and Golang, with constructs such as actors and channels. This kind of shared-nothing concurrency removed a whole range of data race and race condition bugs. In combination with supervision, actors also provide fault tolerance, so that the failure of one actor will not affect the entire program.

Open Recursion

In general, a rule of thumb is: use classes and objects in situations where open recursion is a big win. — Real World OCaml

Originating in the famous Types and Programming Languages, open recursion is probably the least well-known and understood term in this blog post. Nevertheless, it just describes a familiar property of object-oriented systems: methods for an object can call each other, even if they are defined in different classes in the inheritance hierarchy.

The term is somewhat misleading, as there may not be recursive function calls, but here “recursion” means “mutually recursive.” The word “open” refers to “open to extension,” typically empowered by inheritance.

It’s easiest to see with an example:

struct Animal {
  void print_name() const {
    // Note that we call `name` here, although it is not defined in Animal
    std::print("{}\n", name());
  }

  virtual std::string name() const = 0;
};

struct Cat: Animal {
  std::string name() const override {
    return "Kitty";
  }
};

int main() {
  Cat cat;
  // note we call print_name here, although it is not defined in Cat
  cat.print_name();
}

For anyone with some familiarity with OOP, we probably take open recursion for granted, even though we may not be aware of its name. However, not all language constructs have this property. For example, in many languages, functions are not mutually recursive by default:

// This won't compile in C++ because `name` is not defined
void print_name(const Animal& animal) {
    std::print("{}\n", name(animal));
}

std::string name(const Cat& cat) {
    return "Kitty";
}

Now, in languages with late-bound functions, functions in the same module can always call each other (e.g., Python, JavaScript). There are other languages where functions are mutually recursive by default (e.g., Rust), or have forward declarations (C) or a letrec construct (Scheme and ML family) to make functions mutually recursive. This solves the “recursion” part, but still not the “open” part yet:

std::string name(const Cat& cat);

void print_name(const Animal& animal) {
    // This still won't compile because we can't downcast an Animal to a Cat
    std::print("{}\n", name(animal));
}

std::string name(const Cat& cat) {
    return "Kitty";
}

Let’s fix this problem by using a callback:

struct Animal {
  std::function<std::string()> get_name;

  void print_name() const {
    std::print("{}\n", get_name());
  }
};

Animal make_cat() {
    return Animal {
      .get_name = []() { return "Kitty"; },
    };
}

int main() {
  Animal cat = make_cat();
  cat.print_name();
}

Tada, we just reinvented prototype-style dispatch!

Anyway, with my quick example above, I want to show that open recursion is a property that OOP gives for free, but reproducing it in languages without built-in support can be tricky. Open recursion allows interdependent parts of an object to be defined separately, and this property is used in many instances, for example, the entire idea of decorator pattern depends on open recursion.

OOP Best Practices

Perhaps the more common complaints about OOP are not about specific language features, but rather about the programming styles it encourages. Many practices are taught as universal best practices, sometimes with rationales, but their downsides are often omitted. Some examples popped into my mind are

Practice	Advantages	Disadvantage
preferring polymorphism over tagged union/if/switch/pattern matching	Open to extension, easier to add new cases.	Performance hit; Related behaviors get scattered in multiple places; harder to see the whole controll flow in one place; the expression problem means adding new behavior becomes more difficult
making all data members private	Protect class invariants	More boilerplates; Often unnecessary to hide data without invariants; Getter/setter pairs work less well compared to direct access in languages without property syntax
preferring small “self-managed” objects over central “managers”	Harder to violate invariants, cleaner code organization	Potential bad data locality, missing parallelism opportunities, and duplicated references to common data (“back pointer”)
preferring extension rather than modification	Prevent new features from breaking the old one. Prevent API break	No reason to “close” a non-public module where you own its usage. Leads to unnecessary complexity and inheritance chain; poorly designed interfaces are not changed; Can cause abstraction inversion
preferring abstraction over concrete implementations	Making more system swappable and testable	Overuse sacrifices readability and debuggability. Performance cost of extra indirection

This blog post is long enough, so I will not go into more details. Feel free to disagree with my “advantages and disadvantages”. What I want to convey is that almost all those practices come with trade-offs.

In the End

Congratulations on making it to the end of this article! There are other topics I’d love to discuss, such as RAII and design patterns. However, this article is long enough, so I will leave those for you to explore on your own.

See discussion on Lobsters

Self hosting comments with Comentario

Fri, 25 Apr 2025 00:00:00 GMT

Edit 2026-03-12: I just learned about some nasty security gotcha of Docker, so I changed the docker-compose snippet in this post.

One of the challenges of running a static-site blog is enabling comments. This blog initially used Disqus, but I migrated to Commento since Disqus served way too much ads and tracking. Compare to alternatives, Commento also had the set of features I want from a comment system:

Support comments without login, but also OAuth
Moderation dashboard
Threaded replies
Email notification
Custom user avatars
Markdown

For years, I used the cloud-hosted version of Commento. However, Commento had been unmaintained for a long time, and the $99 annual fee always feels too expensive. I’d been wanting to switch to something else for a while but never quite had the motivation. That changed this year when the cloud service start to fail sporadically, and I even thought I had lost all the past comments. I also happened to be redesigning my website around the same time, so it felt like a natural moment to make the switch.

Compare to years ago, nowadays there are much more options for comments, but I settled with Comentario, a fork of Commento, as it is easy to migrate and has all the features that I already used. The only issue is that Comentario only supports self-hosting, which is something I don’t have experience with.

Self-Hosting Setup

I am a self-hosting noob, who dreaded it so much that I even chosed a $99 annual solution a few years ago. Along the way to setting this thing up, I definitely learned a few things.

First, I picked a VPS service. There are a lot of cheap or even free options available online.

Nowadays it is pretty common to use Docker to self-host, and Comentario supports Docker Compose out of the box. Below are my docker configurations:

docker-compose.yaml

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: comentario
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "127.0.0.1:5432:5432"
    restart: always

  app:
    image: registry.gitlab.com/comentario/comentario
    environment:
      BASE_URL: <redacted domain>
      SECRETS_FILE: "/secrets.yaml"
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./secrets.yaml:/secrets.yaml:ro
    restart: always

Comentario stores “secrets” in a separate file:

secrets.yaml

postgres:
  host:     db
  port:     5432
  database: comentario
  username: postgres
  password: postgres

idp:
  github:
    key:    <redacted>
    secret: <redacted>
  # plan to add other providers later

Putting those two files in the same directory and I can start the app with docker compose up -d.

Custom Domain and DNS

Now I could access the app via the IP address. Since I already own a custom domain, all I need to do is to add an A record to point to the VPS.

Reverse Proxy

Now I have a web app that I can access via IP address and the port 8080, but that is far from ideal. I don’t want expose the port and I also need to support HTTPS. I learned something called reverse proxy to handle exact this kind of situation.

Initially I tried to use nginx, but I setted with Caddy for simplicity. All I need to do was to write a Caddyfile like this and start the Caddy server:

Caddyfile

<redacted domain name> {
    reverse_proxy localhost:8080
}

Yes, it is that simple!

Client-Side and CSS

Adding comments to this blog is trivial following the instruction:

<script defer src="<redacted domain>/comentario.js"></script>
<comentario-comments></comentario-comments>

Comentario includes its own CSS, but I needed to customize it extensively to match my site’s design. Rather than relying on CSS overrides, I chose to set css-override="false" on the <comentario-comments> tag and bundled the full CSS file myself in this blog.

Final Notes

During the migration, I also noticed a bunch of spam comments that were just copy-pasting my words verbatim. I’m not sure what their purpose was, but I deleted all of them.

Also, now that I know how to self-host, I’m planning to cut my subscriptions to some other cloud-hosted services. RSS reader and a read-it-later tool immediately comes to my mind.

Resources

I’ve browsed a lot of resources to set this up, here are the ones I found most useful (excluding documentation):

Site Update (April 2025)

Mon, 21 Apr 2025 00:00:00 GMT

I’ve done a complete rewrite of this site. My old version was made with Gatsby.js. While I liked the overall style, it had reached a point where I couldn’t even build it locally with a recent version of Node.js.

Since Gatsby is pretty much abandoned, I choosed a new static-site generator Astro.

Rebuilding this site was definitely a lot of work. The previous version had accumulated many small features over time, and reimplementing all those little details took quite a bit of effort. And while the design of this site is similar to the previous one, I still made extensive change to its layout and style. I also added some new things, such as the grid layout of the project page and a theme toggle.

There are still two major things I need to take care of. First, I don’t have comments set up yet. I previously used the cloud-hosted version of Commento, but I plan to migrate to self-hosting using Comentario. Second, my notes are still a seperate website under the subdomain notes.lesleylai.info. Migrating them over to this site will be a significant task, but I plan to do it in the future.

Update 2025-04-25: The comment system is alive again! I write about my setup in the following post.

Representing an Abstract Syntax Tree in C++: Variants

Mon, 22 Apr 2024 00:00:00 GMT

Exploring the representation of abstract syntax trees in C++ has been a long-standing fascination of mine. Over time, I’ve developed several interpreters/compilers in C++, each utilizing different approaches to representation. In this post, I aim to share the insights I wish I had when I start building language implementations in C++.

Frankly, if I start on a programming language project today, I’d likely opt against C++ unless there is a very compelling reason. Nevertheless, I hope this knowledge I’ve amassed proves valuable to others.

Before delving further, it’s worth noting that the question of “how to represent an AST” can be subdivided into two intertwined issues:

How to represent a variant
How to represent recursive data structure

In this post, we will mainly focus on the first issue.

What Do I Mean by Variant?

Variant, also known as a sum type, tagged union, or discriminated union, is a data structure capable of containing a fixed set of alternatives. If you’re reading this, chances are you’ve used variants before. The “fixed set” perspective is a limitation, but for AST we normally care more about the ease of extending behaviors rather than adding new node types.

Anyway, if there is any language with good support for language-level variants and pattern matching, I would go directly with those. But for C++, there are various alternative representations all with their tradeoffs and shortcomings.

`std::variant`

We’ll begin with std::variant, which is arguably the de facto “modern C++” solution for variants. It offers functionality and type safety, yet its ergonomics are debatable. It may also incur longer compile times compared to raw language solutions.

Using std::variant, we could write something similar to the following:

struct LiteralExpr;
struct VariableExpr;
struct UnaryExpr;
struct BinaryExpr;
struct IfExpr;

using Expr = std::variant<LiteralExpr, VariableExpr, UnaryExpr, BinaryExpr, IfExpr>;
using ExprHandle = std::unique_ptr<Expr>;

struct LiteralExpr {
  Literal lit;
};

struct VariableExpr {
  std::string ident;
};

struct UnaryExpr {
  UnaryOp op;
  ExprHandle expr;
};

struct BinaryExpr {
  BinaryOp op;
  ExprHandle lhs;
  ExprHandle rhs;
};

struct IfExpr {
  ExprHandle cond_expr;
  ExprHandle if_expr;
  ExprHandle else_expr;
};

Forward declaring everything is annoying, and we also probably want to put some common fields, such as the source location, into an AST node. This prompts the following adjustment:

struct Expr;
using ExprHandle = std::unique_ptr<Expr>;

// all kinds of of the Expr here

struct Expr {
  SourceSpan span;
  std::variant<LiteralExpr, VariableExpr, UnaryExpr, BinaryExpr, IfExpr> kind;
};

The above code looks alright, but the main ergonomics problem of the std::variant is how to visit them. C++ doesn’t have pattern matching, and we are given a companion funciton called std::visit, which accept a visitor as argument.

One way to define this visitor is to create a dedicated class:

[[nodiscard]] auto to_string(const Expr& expr) -> std::string;

struct ExprKindPrinter {
  auto operator()(const LiteralExpr& kind) const -> std::string {
      return to_string(kind.lit);
  }

  auto operator()(const VariableExpr& kind) const -> std::string {
      return kind.ident;
  }

  auto operator()(const UnaryExpr& kind) const -> std::string {
    return fmt::format("({} {})", to_string(*kind.op), to_string(*kind.expr));
  }

  auto operator()(const BinaryExpr& kind) const -> std::string {
    // ...
  }

  auto operator()(const IfExpr& kind) const -> std::string {
    // ...
  }
};

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
    return std::visit(ExprKindPrinter{}, expr.kind);
}

This looks verbose and boilerplaty, and another option is to use generic lambdas and if constexpr:

// Helper to catch unreachable branches at compile time
template<class> constexpr bool always_false_v = false;

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
    return std::visit([] (auto&& kind) {
      using KindT = std::decay_t<decltype(kind)>;
      if constexpr (std::is_same_v<KindT, LiteralExpr>) {
        return to_string(kind.lit);
      } else if constexpr (std::is_same_v<KindT, VariableExpr>) {
        return kind.ident;
      } else if constexpr (std::is_same_v<KindT, UnaryExpr>) {
        return fmt::format("({} {})", "+", expr_to_string(*kind.expr));
      } else if constexpr (std::is_same_v<KindT, BinaryExpr>) {
        ...
      } else if constexpr (std::is_same_v<KindT, IfExpr>) {
        ...
      } else {
        static_assert(always_false_v<KindT>, "non-exhaustive visitor!");
      }
    }, expr.kind);
}

I prefer this to the previous version.However, it still appears quite cumbersome with all the decltype, std::decay_t, and std::is_same_v incantations. Also, since generic lambda is template, we have worse IDE auto-completion/error detection support when writing this code.

Yet another option is to use the overloaded helper:

template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };

With that we could write code like the following:

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
    return std::visit(overloaded{
        [](const LiteralExpr& kind) { return to_string(kind.lit); },
        [](const VariableExpr& kind) { return kind.ident; },
        [](const UnaryExpr& kind) {
            return fmt::format("({} {})", "+", to_string(*kind.expr));
        },
        [](const BinaryExpr& kind) { /* ... */ },
        [](const IfExpr& kind) { /* ... */ }
    }, expr.kind);
}

This seems much cleaner compared to the previous solutions, but it still feels somewhat awkward compared to a language-integrated solution.

Discriminated Union

std::variant was intended to supersede the traditional practice of discriminated unions that has been in use since the days of C. With the classic discriminated union, we typically have something along these lines:

enum class ExprKind {
  literal,
  variable,
  unary,
  binary,
  if_
};

struct Expr {
  ExprKind kind;
  union {
    LiteralExpr literal;
    VariableExpr variable;
    UnaryExpr unary;
    BinaryExpr binary;
    IfExpr if_;
  } data;
};

We loss type safety since union access is not checked, but the upper side is that we can just use plain switch instead of doing gymnastics with std::visit:

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
  switch (expr.kind) {
    case ExprKind::literal: return to_string(expr.data.literal);
    case ExprKind::variable: return to_string(expr.data.variable.ident);
    ...
  }
}

Another major downside of raw union is that it can’t handle non-trivial types (e.g. std::string or std::unique_ptr). This is because the compiler has no idea which member’s destructor to call when destructing a union (similarly, copy and move will also be broken). If you require non-trivial types, you’ll have to write your own destructor for Expr, which can become tedious and error-prone.

If you opt to stick with trivial types, such as std::string_view for strings and Expr* for expression handles, you’ll need to consider resource management. A great strategy is to implement an allocation scheme like the arena allocator, where deallocation is unnecessary. This approach can provide a robust and reliable solution.

Enum Tag + Inheritance

One problem with the “tagged union” approach is that it can waste memory, especially if if some of your nodes are significantly larger than others, as the size of variant or union will always be the size of its largest alternative. We can address this issue by using inheritance:

struct Expr {
  ExprKind kind;
};

struct LiteralExpr : Expr {
  Literal lit;
};

Utilizing this type closely resembles the previous one, with the notable difference being the necessity for down-casting:

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
  switch (expr.kind) {
    case ExprKind::literal:
     return to_string(static_cast<const LiteralExpr&>(expr));
    case ExprKind::variable:
     return static_cast<const VariableExpr&>(expr).ident;
    ...
  }
}

The excessive amount of down-casting can be annoying, but we can mitigate this issue by writing some helper functions:

struct Expr {
  ExprKind kind;

  auto as_literal_expr() const & -> const LiteralExpr&;
};

struct LiteralExpr : Expr {
  Literal lit;
};

auto Expr::as_literal_expr() const & -> const LiteralExpr&
{
    return static_cast<const LiteralExpr&>(*this);
}

[[nodiscard]] auto to_string(const Expr& expr) -> std::string {
  switch (expr.kind) {
    case ExprKind::literal:
     return to_string(expr.as_literal_expr());
    ...
  }
}

I actually quite like this solution despite it violates “OOP best practices.” Though if you don’t have a virtual destructor, you face a similar issue of the previous solution.

A Virtual Function That Returns Enum Tag

If you don’t mind adding virtual functions, it gives us back type safety and also solves the problem of supporting non-trivial types. Additionally, the enum tag field becomes redundant, eliminating the need to store it within the Expr. Consequently, we can implement something akin to the following:

struct Expr {
    [[nodiscard]] virtual auto kind() const -> ExprKind;
    virtual ~Expr() = default;
};

struct BinaryOpExpr : Expr {
    auto kind() const -> NodeKind override { return NodeKind::BinaryOp; }
};

With virtual functions, we can also implement checked down-casting, unlike the previous version:

struct Expr {
  ...

  auto as_literal() const& -> const LiteralExpr* { return nullptr; }
};

struct LiteralExpr : Expr {
  auto as_literal() const& -> const LiteralExpr* { return this; }
};

Like the last one, this method still violates the “OOP best practice” of not using enum tags and inheritance together.

Inheritance with the Visitor Pattern Approach

Lastly, let’s look at the visitor pattern, the canonical OOP way to create and traverse variants. First, we need to define a visitor type:

struct ExprVisitor {
  ExprVisitor() = default;
  virtual ~ExprVisitor() = default;

  virtual void visit(const LiteralExpr&) = 0;
  virtual void visit(const VariableExpr&) = 0;
  virtual void visit(const UnaryExpr&) = 0;
  virtual void visit(const BinaryExpr&) = 0;
  virtual void visit(const IfExpr&) = 0;
};

Then we adds an accept method for Expr:

struct Expr {
  virtual void accept(ExprVisitor& visitor) const = 0;
};

struct LiteralExpr : Expr {
  double value;

  void accept(ExprVisitor& visitor) const override { visitor.visit(*this); }
};

struct VariableExpr : Expr {
  std::string id;

  void accept(ExprVisitor& visitor) const override { visitor.visit(*this); }
};

Note that even though all the implementation of accept looks identical, we need this duplicated code in each derived class of Expr because we are overloading on the type of *this. If you want to make this more explicitly, you can also change the name of the visit methods in ExprVisitor into something like visit_literal and visit_variable.

With all that boilerplate, we can start to use our visitor. However, we immediately face another significant annoyance: unlike in languages such as Java, there is no way to make a virtual function to return different types based on a template parameter:

// The following will not work!!!
template <typename T>
virtual auto visit(const LiteralExpr&) -> T = 0;

As a result, we need to save the result of a visitor into another variable:

struct ExprPrinter : ExprVisitor {
  std::string result;

  void visit(const LiteralExpr& expr) override
  {
    result = to_string(expr.lit);
  }

  void visit(const VariableExpr& expr) override
  {
    result = expr.ident;
  }

  ...
};

[[nodiscard]] auto to_string(const Expr& expr) -> std::string
{
  ExprPrinter printer;
  expr.accept(printer);
  return printer.result;
}

Another problem with visitor pattern is const-correctness. Although I believe that a mutable AST isn’t necessarily the best approach and there are superior alternatives, if you do need to mutate your AST, you need to define yet another mutable visitor base class to achieve that. Also don’t forget about all those accept member functions:

struct ExprMutableVisitor {
  ExprMutableVisitor() = default;
  virtual ~ExprMutableVisitor() = default;

  virtual void visit(LiteralExpr&) = 0;
  virtual void visit(VariableExpr&) = 0;
  virtual void visit(UnaryExpr&) = 0;
  virtual void visit(BinaryExpr&) = 0;
  virtual void visit(IfExpr&) = 0;
};

struct Expr {
  virtual void accept(ExprVisitor& visitor) const = 0;
  virtual void accept(ExprMutableVisitor& visitor) = 0;
};

struct LiteralExpr : Expr {
  double value;

  void accept(ExprVisitor& visitor) const override { visitor.visit(*this); }
  void accept(ExprMutableVisitor& visitor) override { visitor.visit(*this); }
};

struct VariableExpr : Expr {
  std::string id;

  void accept(ExprVisitor& visitor) const override { visitor.visit(*this); }
  void accept(ExprMutableVisitor& visitor) override { visitor.visit(*this); }
};

Of all the alternatives I’ve presented so far, the visitor pattern is likely the slowest, because it performs double dispatch (once at visit and once at accept) while all the other options perform a single dispatch. The boilerplate is also unwieldy. I would not recommend it if you don’t actually need double dispatch.

”Uber node” as an alternative to variant?

It is convinient to have one single “uber node” type that is flexible enough to accomodate for all different kind of AST nodes, and this way we don’t need variants at all. For example, we may have something like this:

struct Node {
  NodeKind kind;
  std::vector<Node> children;
  std::span<Token> tokens;
}

I have seen this approach used in “simple compiler” codebases such as 9cc. One of the main upside of this approach is that if you write some tree/graph algorithm on Node, it will automatically work for all nodes. The downside including performance and space waste. Also, this approach means it takes more effort to extract data from an AST node, and it is not clear whether a certain kind of node contains a certain field.

Conclusion

All of the above methods are used in the wild. So, YMMV. Nonetheless, it’s crucial to remain conscious of the available options and the trade-offs associated with each.

Online Courses that I Recommend

Sun, 17 Mar 2024 00:00:00 GMT

My journey of learning from online courses started in 2013, and over the years I took a lot of them, abandoning even more along the way. Nevertheless, I’ve found online courses to be far more accommodating for self-study compared to traditional books.

In this post, I’ve compiled a list of courses that I found memorable, enjoyable, and, in retrospect, actually convey high-quality information. While the selection is undoubtedly biased towards my personal interests, I hope you find them useful as well.

Do note that some courses that I recommend below are not MOOCs, but instead university courses that happened to have lecture recordings, assignments, and other course material freely available from past offerings. As a result, you may need to do some extra digging to locate the course material.

Meta-Learning

Learning How to Learn — “Learning how to learn” is an essential skill that I find people, including myself, quite lacking. Some people may consider this one offer pretty “obvious” advice. Indeed, most actionable advice taught in this course is not new. However, I don’t think it is right to dismiss the course as “common sense,” for common senses are often contradictory with each other. This course, instead, offers scientific validation for effective learning practices.

Math

Calculus

Calculus: Single Variable by Robert Ghrist [part 1] [part 2] [part 3] [part 4] [part 5] — A multi parts course on single variable calculus
MIT OCW Multivariable Calculus as main course and things below as supports
- Calculus Blue — Again by Professor Ghrist. The matrix calculus perspective is refreshing, but the pace is too fast to use as a standalone material imo
- Khan Acedemy

Linear algebra

MIT OCW Linear Algebra by Prof. Gilbert Strang as main course — If you spend some time doing online learning for math, it is likely you already heard the name of Prof. Strang.
- Essense of linear algebra by 3Blue1Brown

Differential Equations

MIT OCW Differential Equations — My only complaint is the low resolution of the video lecture
Khan Academy Differential Equations — Accessible though very incomplete

Discrete Math

MIT OCW Mathematics for Computer Science

Signal Processing

Wikipedia says that signal processing is an electrical engineering subfield, but in reality the same technique is used in various other fields as well.

MIT OCW 6.003 Signals and Systems — I enjoy the inereactive teaching style.

Logic

Stanford Introduction to Logic — I took a solid introductory logic course at university, but this course still introduces many new concepts or explains familiar ones from a fresh perspective.

Computer Science and Programming

Intro

Stanford CS106A, 106B, and 106L — These were course series that started my Computer Science Journey. The 2008 edition that I took was way too old and outdated, but there are newer versions of offering online.

Computer Graphics and GPU Programming

CMU 15-462/662 Computer Graphics — Great intro to Computer Graphics. And even experienced folks can learn a lot here.
CIS 5650 GPU Programming and Architecture — Project-oriented introduction of GPU programming in CUDA with a Computer Graphics flavor
CS 87/287 | Rendering Algorithms — Mainly focus on offline rendering. Unlike most courses I recommended here, this one doesn’t have lecture videos. Though following slides and doing homework are effective enough for me.

Programming Languages and Compilers

Programming Languages by University of Washington [Part A] [Part B] [Part C] — A three-part course on programming languages. I find the content quite shallow compared to the undergrad PL course I took at university, but it serves as a good introduction and Prof. Dan Grossman is enthusiastic about the topics.
CS 6120: Advanced Compilers by Cornell University — mainly talks about compiler optimization

System Programming

CMU 15-213/15-513 Introduction to Computer Systems
- The CSAPP textbook used by this course is a classic. However, do note that there are some serious misinfo regarding C
  - For years I thought signed-integer overflow has wrapping behavior in C because of this book
Nand2Tetris — If you want a single survey course that covers logic gates, computer architecture, assembly, and OS, then this is a course for you. Of course, it covers none of the topics in-depth, but still an awesome course nonetheless.

Misc

The Missing Semester of Your CS Education — talks about the usage of various important tools for software engineering

Psychology

Yale Introduction to Psychology — There is a new version by the same professor on Coursera

Physics

Understanding Einstein: The Special Theory of Relativity by Stanford — A (very) qualitative intro to the special theory of relativity that I think is accessible even for folks without a STEM background

Tips on finding good courses

My observation is that traditional university courses (such as the ones from MIT OCW) have higher quality on average than MOOCs. Unfortunately, most university courses lack lecture videos, which I consider indispensable. On the other hand, while lecture videos are invaluable, courses relying solely on videos—a common occurrence on YouTube—are not enough. Prefer courses with a lot of supplementary materials and homework.

Among Mooc platforms, I think Coursera and Edx are still the two major platforms that contain higher-quality courses on average. Where there are still tons of good stuff on other platforms, it can be more of a hit-or-miss experience.

Another tip: for courses on platforms with reviews, take a moment to read the 1-star and 2-star ratings. While most of these reviews are nonsensical, if you notice consistent red flags, then maybe this is not the right course for you. This same approach can also be applied when assessing whether a book is worth reading.

Highly Regarded Courses that I don’t recommend

Similar to university courses, the majority of online courses I’ve enrolled in have left much to be desired. Most were forgettable, filled with platitudes and lacking information density. Below are a few that were particularly problematic that I can still remember now.

Social Psychology by Wesleyan University — Presented lots of exaggerated claims and falsified theories such as “video game causes violence.” Also quoting controversial studies such as Stanford Prison and Milgram experiments. I guess this course can serve as a cautious tale of scientific progress and not everything you learn is true. Though since I took it in 2015, I am not sure if this course changes now.
Fundamentals of Music Theory By the University of Edinburgh — Rudimentary lectures followed by extremely hard quizzes that are impossible to complete without a lot of extra googling

Small Naming Tip: Use "from" Instead of "to" in Function and Variable Names

Sat, 10 Feb 2024 00:00:00 GMT

Today, I’m tackling a piece of code involving several mappings. Like many others, I typically label such maps as x_to_y, and that’s also what I’ve done here:

let mut value_to_var: HashMap<Value, (String, usize)> = HashMap::new();
let mut var_to_num: HashMap<String, usize> = HashMap::new();
// This is not a hash table but I use the index as the key
let mut num_to_canonical_var = vec![];

When I need to use those maps, my code often looks like this:

let canonical_variable = num_to_canonical_var[var_to_num.get(var).unwrap()];

As you can observe, the sequence isn’t particularly intuitive. The code executes a transformation from “variable -> number -> canonical variable,” but understanding it requires reading from the inside out, akin to unraveling a spiral. Reading inside out can be challenging. For example, despite my nearly decade-long experience with C and C++, I still sometimes struggle to decipher the inside-out syntax of C declarations. Others share this sentiment as well.

What if I change all the to to from?

let mut var_from_value: HashMap<Value, (String, usize)> = HashMap::new();
let mut num_from_var: HashMap<String, usize> = HashMap::new();
let mut canonical_var_from_num = vec![];

Now, we can write code like the following:

let canonical_variable = canonical_var_from_num[num_from_var.get(var).unwrap()];

This code is much easier to comprehend, as related names share physical proximity. Its transformation is also readily apparent just by reading from right to left.

The same idea can also be applied to functions. For instance, let shader = shader_from_file(file) reads better than let shader = file_to_shader(file). It isn’t a coincidence, considering that both functions (at least the pure ones) and a map data structure aim to create a mapping between data.

Update 2024-02-10: Several users on Mastodon have noted that they prefer to name their map variables as x_by_y, which shares similarity with the x_from_y I present here.

Update 2024-02-11: Another user on Mastodon mentioned that Joel Spolsky wrote about the exact same suggestion. The article also provides an excellent description of the “Apps Hungarian” notation and how it differs from the more cumbersome “Systems Hungarian” notation that most people are familiar with. Personally, I question the relevance of even Apps Hungarian in modern languages with expressive type systems. If something possesses unique semantics and is utilized frequently enough to warrant a naming convention, we should create a strongly typed wrapper for it.

What happened to Lesley in the last couple of years

Sun, 17 Dec 2023 00:00:00 GMT

TL;DR: I was forced to leave university without completing my degree due to unfortunate circumstances, and returning has proven unexpectedly challenging.

Update 2023/12/18: If you are reading this now, please refrain from DMing me and providing suggestions. While I appreciate your willingness to help, I find myself a bit overwhelmed at the moment.

If you’re looking for tech-related content, this article is not what you seek. There’s no tech information here, so feel free to stop reading. I just share my pain here because it’s too painful to bear the weight alone.

2021 Summer Fiasco

Until the summer of 2021, I was an international student at the University of Colorado Boulder, majoring in Computer Science and Applied Math.

Unfortunately, the summer of 2021 marked a significant downturn. I should have graduated at that time, but COVID-19 isolation and remote learning severely impacted my mental health and studying ability. Nevertheless, I have only a few credits left for graduation.

However, in June 2021, I misunderstood the CPT application process and unintentionally started my summer internship before obtaining authorization for my CPT. I did the same internship for two consecutive years with approval, but I got confused about the policy change that occurred in 2021, which made the process more complicated.

The Office of International Student & Scholar Services of CU Boulder immediately canceled my I-20 and asked me to leave the U.S. immediately ¹, so I purchased a flight ticket and planned to depart from the United States in June.

The situation got much worse when I realized that my passport had expired. As I didn’t have any travel plans that summer due to COVID, I hadn’t bothered to check its validity. Despite reaching out to various university offices, none provided meaningful assistance. Subsequently, I contacted the Embassy of China in Chicago, but they informed me that passport renewal would be delayed and advised me to get a Travel Document as an alternative. Even this process took an extended period, and I finally received my Travel Document in late September. Then I left the US in a few days.

After I went back to China

I was still optimistic when I went back to China. My COVID-induced mental health condition immediately improved as I reunited with my family. I also swiftly found a job (though officially an intern). I still wanted to stay connected with the programming community, so I tried my best to attend meetups and conferences. I even gave a lightning talk at CppCon 2021 despite the time difference. I also continue to organize my weekly Graphics Programming Virtual Meetup to this day.

Originally, I intended to return to the university in the summer of 2022. However, unforeseen family circumstances have compelled me to postpone my plans once again. At that time, I pondered the idea of not getting back at all. However, the university degree still needs to be solved. With the degree gatekeeping everywhere in China, it is hard for me to find any job besides “internships.”

First Half of 2023

I restarted my planning to return to university early this year and intended to return this Fall. I started to communicate with my universities, but the university’s international student office proved highly challenging to communicate with. I applied for my I-20 document, necessary for a U.S. student visa, in April. However, the university staff corresponding with me continually introduced new requirements, delayed responses for a week, and requested additional tasks.

The ongoing back-and-forth is exhausting. Over time, I began experiencing physical pain when reading and responding to their emails. I started to suspect that the university personnel did not want me to return at all; instead, they were only forced to process my documents out of obligation.

Upon receiving my I-20 in June, I discovered it only covered half a year, and my Computer Science major was dropped. Frustrated, I reached a breaking point and sent a blunt email, pointing out what I perceived as “gaslighting” by university personnel. I requested the cancellation of the I-20 form and contemplated giving up.

Restart Application Process

I was uncertain about my next steps and only vaguely entertained the idea of “transferring to another university to obtain a degree,” a process that could potentially take years. In October, I reluctantly chose to give my current university another chance and pleaded with them to readmit me. The process went surprisingly smoothly, and I got a new I-20 with four years of duration in a short period. During the whole process, I didn’t communicate with the university’s international student office directly.

US Visa Application

After receiving my new I-20 form, I applied for a US visa in early December. Upon hearing my condition, the visa officer said that they would check my application and decide later. I received a rejection based on section “214(b)” in a few days.

I am ready for the rejection of my visa application. After all, the entire visa application procedure operates on the “presumption of guilt”, requiring me to persuade them that I am rich and definitely harboring no immigrant intentions. ² My relatively older age compared to typical students and the overstaying history certainly does not work in my favor.

Following the rejection, I emailed the university for assistance, requesting a letter of support. However, instead of providing any help or at least expressing sympathy, the same individual from the university’s international student office responded by forwarding the complete content of a visa denial information page from the US government website and declined to offer any support. ³

I plan to reapply for a U.S. visa shortly. However, if I face rejection again, I won’t be able to return in the spring of 2024.

2023/12/24 Update: University’s Follow-Up

Another university personnel from its International Student and Scholar Service sent another email to me today after “come to my attention that you are frustrated with what you perceive as disinterest of the ISSS office at CU Boulder in helping you solve your visa challenges.” Someone probably forwarded this blog post to them. They “recommend that you focus on providing additional, new documents including a comprehensive explanation of your ties to home (e.g. family remaining in home country, bank accounts there, job prospects, etc.) and your intent to return there once you have completed your degree in the U.S.”

I have decided not to respond to the email.

It has become increasingly evident that this country and university do not welcome me. Worry not; I don’t plan to linger. At this point, even if I get a U.S. visa, I don’t intend to finish my Computer Science degree anymore⁴. I will just get my Apply Math degree done and yeet myself out of their sacred country ASAP.

2024/1/3 Update: Second Visa application

My second visa application was swiftly denied, indicating the likelihood of a negative record associated with my profile. To be honest, I couldn’t care less if I can’t set foot in that country ever again. Nevertheless, I must reconsider my options for pursuing a degree elsewhere.

Footnotes

COVID-19 travel advisories are not their problem, they said. ↩
Admittedly, a couple of years ago, I did want to stay in the U.S. I had a strong attachment to Boulder, having lived here for an extended period. However, my perspective has since shifted. Without a rose-colored glass, I now see institutional racism and injustices a lot clearer. ↩
I assumed this individual was no longer managing my case because there were no issues in September. How naive of me? ↩
I used to have a Computer Science and Applied Math double major. The university canceled my CS major and said that I could pursue it again after I graduate from the Applied Math one. ↩

Use ManuallyDrop in Rust to control drop order of structure fields

Mon, 06 Feb 2023 00:00:00 GMT

First, for some context: I wrote this blog post more than a year ago but have yet to make it public since my mental health greatly degraded while I was still editing it. Now that I want to go back into blogging, I decide to release this post in its current form, though I lost interest in editing it.

As programmers, “clean-up” always feels like the boring part of our code. Fortunately, in Rust, we have destructors that help us to automatically write correct, ergonomic clean-up code. However, in the rare case where the order of destruction matters, compiler-generated destructor calls can be a hindrance.

In this post, I will show you how to use the Rust standard library ManuallyDrop type to explicitly control how and when structure fields get dropped.

The problem

Rust drops fields in the declaration order¹. For example, considering the following structure:

struct Name {
    first: String,
    last: String,
}

In this case, first will be the first field to destroyed, followed by last.

This behavior, though unintuitive (especially if you come from a C++ background²), is fine for most of the time, as we programmers often don’t care about exactly order of things get freed. For example, in the above example, there are no dependencies between first and last fields, so destroying either of them first is fine.

However, there are cases where destuction-order do matters. Unless we are ok to order fields in our struct in a gratuitous reverse order, it is probably not worth relying on the compiler-generated destruction order. Worse, in some instances, we may want to interleave user code execution and the fields being dropped inside the drop method, and the compiler’s automatically generated destructor calls failed us here.

A Vulkan example

I met the problem when doing some Vulkan exploration in Rust via the excellent ash crate. I use another crate, gpu-allocator, to manage GPU memory.

The topic of this post is not about the Vulkan API. If you are not familiar with it, the only thing you need to know is that the time of destruction is very important in this API, and many entities in Vulkan have implicit dependencies. Before destroying anything in Vulkan, we need to ensure that the corresponding resource is not used on the GPU. Also, we can’t destroy an object if any other objects depend on it.

It is common in Vulkan applications to have a Renderer structure like the following:

use gpu_allocator::vulkan::{Allocator};

pub struct Renderer {
    entry: ash::Entry,
    instance: ash::Instance,
    ...
    physical_device: vk::PhysicalDevice,
    device: vk::Device,
    ...
    allocator: Allocator,
    ...
}

Since the allocator depends on instance and device, those two must be destroyed after the allocator. On the other hand, certain other resources, such as buffers allocated by the allocator, need to be destroyed before the allocator gets destroyed.

The ash crate abandons using destructors and RAII all thgether but instead relies on manual resource managements inside unsafe blocks. In ash, we are expected to write code like the following:

unsafe {
    instance.destroy_instance(None);
}

Even though non-idiomatic in Rust, ash’s approach is fine with me. RAII combines with the Vulkan API pretty poorly for multiple reasons ³. However, gpu_allocator, despite depending on the ash crate, decide to implement the Drop trait for its Allocator. And we are in a situation where we must call the destructor of the allocator in the middle of a chain of calls to ash’s clean-up functions.

In C++, we just manually call the destructors when meeting such a situation, and everything will work fine. Can we do that in Rust? Here is a try:

impl Drop for Renderer {
    fn drop(&mut self) {
        // ...

        // ... All the allocation must be freed BEFORE the allocator get dropped
        self.allocator.free(allocation).unwrap();
        unsafe { self.device.destroy_buffer(self.buffer, None) };

        // We try to drop our allocator here
        self.allocator.drop();

        // device and instance must be destroyed AFTER the allocator
        unsafe {
            self.device.destroy_device(None);
            self.instance.destroy_instance(None);
        }
    }
}

However, Rust forbids explicit destructor calls, and the above program fails to compile. The Rust compiler then gives this “helpful” message:

consider using drop function: drop(self.allocator).

So let’s try that:

impl Drop for Renderer {
    fn drop(&mut self) {
        // ...

        std::mem::drop(self.allocator);

        // ...
    }
}

Unfortunately, the above solution doesn’t compile either, and it gives the “cannot move out of self.allocator which is behind a mutable reference” error. The reason is that the drop method takes self by reference, while std::mem::drop tries to borrow its field self.allocator. Even though we know that our renderer will get destroyed after the drop method, from the Rust type system’s perspective, std::mem::drop is trying to “steal” one of its fields.

Using `Option` to circumvent the drop order

If you are an experienced Rust programmer, you have probably already come up with an idiomatic way to our problem: making the allocator field into an Option.

pub struct Renderer {
    ...
    allocator: Option<Allocator>,
    ...
}

Then when we want to drop self.allocator, we can assign it to None.

impl Drop for Renderer {
    fn drop(&mut self) {
        ...
        self.allocator = None;
        ...
    }
}

Alternatively, we can combine a std::mem::drop with a .take() call: std::mem::drop(self.allocator.take()).

The Option solution works, and many people will probably be happy with it. However, I am dissatisfied for several reasons. Probably most importantly, the usage of Option pollutes all the self.allocator usage with extra .unwrap() ceremony.

The Option usage here also violates Rust’s “zero-overhead abstration” principle, as we add runtime overhead purely to satisfy the type system. Though I consider this point less important since the performance overhead of using Option here is neglectable in the large picture on things.

Introducing `ManuallyDrop`

std::mem::ManuallyDrop is a type wrapper that inhibits the Rust compiler from automatically calling the underlying type’s destructor.

Let’s apply ManuallyDrop to our allocator:

pub struct Renderer {
    ...
    allocator: ManuallyDrop<Allocator>,
    ...
}

What makes ManuallyDrop a much more ergonomic choice than Option is its implementation of Deref, which makes it possible for us to use methods of Allocator directly. A bonus point is that, unlike Option, ManuallyDrop doesn’t add any performance overhead.

When we are done, we can use ManuallyDrop::drop to drop our field. This function specifically takes a mutable reference, so we won’t have the same problem we faced with the standard drop function before:

impl Drop for Renderer {
    fn drop(&mut self) {
        ...
        unsafe {
            ManuallyDrop::drop(&mut self.allocator);
        }
        ...
    }
}

Notice that ManuallyDrop::drop is an unsafe function since it makes self.allocator in a “zombie” state that shouldn’t be touched. But since the whole Renderer structure will no longer exist after being dropped, it is not likely to pose any problem in practice.

Drawback of `ManuallyDrop`

ManuallyDrop is perfect for the above use case, but it can cause some hassle when we can’t automatically dereference it. This case will only happen on assignment, so if we need to assign a new value to a ManuallyDrop variable, we need to dereference it with * explicitly:

let mut x = ManuallyDrop::new(42);
*x = 55;

This slightly annoying syntax is only a minor issue, but it does break the illusion that ManuallyDrop<T> behaves exactly like the underlying type T. However, the annoyance can add up if we have a lot of fields of type ManuallyDrop, for example, when generating binding with C++ libraries. The good news is that there is a proposal that aims to provide a more ergonomic solution in the future.

Conclusion

ManuallyDrop is a seldom necessary utility in normal Rust code. Nevertheless, it is currently the ideal solution when we want explicit control of how structure fields get dropped.

Footnotes

Destructors - The Rust Reference: “The fields of a struct are dropped in declaration order.” ↩
C++ calls destructor in reverse declaration order order ↩
In Vulkan, we don’t deleting an object until we are sure that the GPU is not using it. Deleting objects out-of-order is a big issue, and it may even crash your driver. ↩

CMAKE_SOURCE_DIR is probably not what you want

Thu, 17 Feb 2022 00:00:00 GMT

Today is the nth time I got bitten by CMAKE_SOURCE_DIR, so I will write it here. In short, there are two predefined variables in CMake: CMAKE_SOURCE_DIR and PROJECT_SOURCE_DIR. CMAKE_SOURCE_DIR refers to the top-level source directory that contains a CMakeLists.txt, while PROJECT_SOURCE_DIR refers to the source directory of the most recent project() command.

They are often the same, but a common workflow when using CMake is to use add_subdirectory to add libraries. And in that case, any CMAKE_SOURCE_DIR in that inner library will refer to the outer project’s root rather than the library’s own root directory! This behavior is wrong in the majority of cases, and thus we should use PROJECT_SOURCE_DIR instead.

VK_KHR_dynamic_rendering tutorial

Sun, 16 Jan 2022 00:00:00 GMT

Announced two months ago, the dynamic rendering Vulkan extension promises to get rid of the VkRenderPass and VkFramebuffer objects, which were parts of Vulkan that I “don’t understand and don’t really care about.”

To write a Vulkan renderer before the advent of dynamic rendering, we always needed to write a lot of boilerplate renderpass code. It is not an ergonomic API, nor is it often that we need the flexibility of multiple subpasses or input attachments. By contrast, the DirectX 12 API has render passes as an optional thing that is only used to “improve performance if the renderer is Tile-Based Deferred Rendering.”

Recently, I started writing a new Vulkan Renderer from scratch in Rust using the ash crate, and it was natural for me to try this shiny new dynamic rendering extension. The resources on this extension are still sparse, and there is no tutorial on using it. There is Sascha Willems’ example, though I only found it after I implemented dynamic rendering myself.

I ended up just reading the extension spec, which is readable enough to figure out its usage. I write this post, however, in a more tutorial-style approach to show how to use this extension. To make the post more accessible, I write it using the original C-API instead of the Rust bindings. It is good that the bindings in the ash crate are a straightforward mapping to the C-API, but if I made a mistake in code snippets during the “translation” process, please get in touch with me.

Initialization

VK_KHR_dynamic_rendering is a device extension, so when we create our logical device, we need to enable it with other device extensions such as VK_KHR_swapchain.

Check extension availability

Like all other extensions, we can check whether our physical device supports VK_KHR_dynamic_rendering via vkEnumerateDeviceExtensionProperties. If the result we get from vkEnumerateDeviceExtensionProperties doesn’t contain VK_KHR_dynamic_rendering, we will need to update the driver and Vulkan SDK and runtime.

Note: VK_KHR_dynamic_rendering is young at the time of this writing (January 2021), so there is a possibility that the latest driver on your hardware still doesn’t support it. When I wrote this article, I needed to install a “Vulkan Beta Driver” for my Nvidia card, though this is no longer the case now.

Enable feature and load the extension

Before we create our logical device, we also need to add VK_KHR_dynamic_rendering to our extension lists:

std::vector<const char*> device_extensions = {
  // ...,
  "VK_KHR_dynamic_rendering"
};

Additionally, dynamic rendering is hidden behind a feature flag, and we need to create a VkPhysicalDeviceDynamicRenderingFeaturesKHR structure and then pass it to the pNext chain when we create the logical device:

constexpr VkPhysicalDeviceDynamicRenderingFeaturesKHR dynamic_rendering_feature {
    .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DYNAMIC_RENDERING_FEATURES_KHR,
    .dynamicRendering = VK_TRUE,
};

const VkDeviceCreateInfo device_create_info = {
    .sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO,
    .pNext = &dynamic_rendering_feature,
    // ...
    .enabledExtensionCount = static_cast<unsigned int>(device_extensions.size()),
    .ppEnabledExtensionNames = device_extensions.data(),
};

Use dynamic rendering in command buffer

In your Vulkan renderer, you are likely to have code that looks like the following in your command buffer recording:

VK_CHECK(vkBeginCommandBuffer(command_buffer, &command_buffer_begin_info));

VkRenderPassBeginInfo render_pass_begin_info = {
    // ...
};

vkCmdBeginRenderPass(command_buffer, &render_pass_begin_info, VK_SUBPASS_CONTENTS_INLINE);

// Draw calls here

vkCmdEndRenderPass(command_buffer);

VK_CHECK(vkEndCommandBuffer(command_buffer));

With dynamic rendering, we need to replace the VkRenderPassBeginInfo structure and the vkCmdBeginRenderPass and vkCmdEndRenderPass calls. Instead of using VkRenderPassBeginInfo, we add a VkRenderingInfoKHR structure, which looks like the following:

typedef struct VkRenderingInfoKHR {
    VkStructureType                        sType;
    const void*                            pNext;
    VkRenderingFlagsKHR                    flags;
    VkRect2D                               renderArea;
    uint32_t                               layerCount;
    uint32_t                               viewMask;
    uint32_t                               colorAttachmentCount;
    const VkRenderingAttachmentInfoKHR*    pColorAttachments;
    const VkRenderingAttachmentInfoKHR*    pDepthAttachment;
    const VkRenderingAttachmentInfoKHR*    pStencilAttachment;
} VkRenderingInfoKHR;

You can see that some fields, like renderArea, were previously provided to VkRenderPassBeginInfo. Still, the majority of the information of this structure would be provided as a part of render pass creation. In particular, we have this new VkRenderingAttachmentInfoKHR structure instead of VkAttachmentDescription to describe attachments:

typedef struct VkRenderingAttachmentInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    VkImageView              imageView;
    VkImageLayout            imageLayout;
    VkResolveModeFlagBits    resolveMode;
    VkImageView              resolveImageView;
    VkImageLayout            resolveImageLayout;
    VkAttachmentLoadOp       loadOp;
    VkAttachmentStoreOp      storeOp;
    VkClearValue             clearValue;
} VkRenderingAttachmentInfoKHR;

Now we can replace our render pass code with the usage of the above structures. This change does mean that we will write more code in our command buffer recording, as some of the information we provided to render pass object are moved to here:

VK_CHECK(vkBeginCommandBuffer(command_buffer, &command_buffer_begin_info));

const VkRenderingAttachmentInfoKHR color_attachment_info {
    .sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO_KHR,
    .imageView = swapchain_image_views_[swapchain_image_index_],
    .imageLayout = VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR,
    .loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR,
    .storeOp = VK_ATTACHMENT_STORE_OP_STORE,
    .clearValue = clear_value,
};

const VkRenderingInfoKHR render_info {
    .sType = VK_STRUCTURE_TYPE_RENDERING_INFO_KHR,
    .renderArea = render_area,
    .layerCount = 1,
    .colorAttachmentCount = 1,
    .pColorAttachments = &color_attachment_info,
};

vkCmdBeginRenderingKHR(command_buffer, &render_info);

// Draw calls here

vkCmdEndRenderingKHR(command_buffer);

VK_CHECK(vkEndCommandBuffer(command_buffer));

Pipeline creation

Now we are at the point where we can scrape out all of the code initializing render pass and framebuffer objects! And when creating pipeline objects, we no longer need to specify a render pass, but instead, we need to create a VkPipelineRenderingCreateInfoKHR object to specify attachment formats:

const VkPipelineRenderingCreateInfoKHR pipeline_rendering_create_info {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR,
    .colorAttachmentCount = 1,
    .pColorAttachmentFormats = &swapchain_image_format_,
};

const VkGraphicsPipelineCreateInfo pipeline_create_info {
  // ...
  .pNext = &pipeline_rendering_create_info,
  // ...
  .renderPass = nullptr, // We no longer need a render pass
  // ...
};

Image layout transition

If everything were that simple, I would be very pleased with this extension. However, it turns out that the render pass object was doing something useful.

With our current code, the validation layer produces this warning every frame:

pSwapchains[0] images passed to present must be in layout VK_IMAGE_LAYOUT_PRESENT_SRC_KHR or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR but is in VK_IMAGE_LAYOUT_UNDEFINED. The Vulkan spec states: Each element of pImageIndices must be the index of a presentable image acquired from the swapchain specified by the corresponding element of the pSwapchains array, and the presented image subresource must be in the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout at the time the operation is executed on a VkDevice (https://github.com/KhronosGroup/Vulkan-Docs/search?q=VUID-VkPresentInfoKHR-pImageIndices-01296)

It says that our swapchain image is in VK_IMAGE_LAYOUT_UNDEFINED layout, but to present the image, it should be in either VK_IMAGE_LAYOUT_PRESENT_SRC_KHR or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR. We can manually transition the layout of swapchain image to VK_IMAGE_LAYOUT_PRESENT_SRC_KHR before presenting:

// draw calls here

vkCmdEndRenderingKHR(command_buffer);

const VkImageMemoryBarrier image_memory_barrier {
    .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
    .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,
    .oldLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .newLayout = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR,
    .image = swapchain_images[swapchain_image_index_],
    .subresourceRange = {
      .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
      .baseMipLevel = 0,
      .levelCount = 1,
      .baseArrayLayer = 0,
      .layerCount = 1,
    }
};

vkCmdPipelineBarrier(
    command_buffer,
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,  // srcStageMask
    BOTTOM_OF_PIPE, // dstStageMask
    0,
    0,
    nullptr,
    0,
    nullptr,
    1, // imageMemoryBarrierCount
    &image_memory_barrier // pImageMemoryBarriers
);

VK_CHECK(vkEndCommandBuffer(command_buffer));

But now VK_IMAGE_LAYOUT_PRESENT_SRC_KHR is not a layout fit for rendering in the next frame. So before rendering, we need to transition the image back into VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL:

VK_CHECK(vkBeginCommandBuffer(command_buffer, &command_buffer_begin_info));

const VkImageMemoryBarrier image_memory_barrier {
    .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
    .dstAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,
    .oldLayout = VK_IMAGE_LAYOUT_UNDEFINED,
    .newLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .image = swapchain_images[swapchain_image_index_],
    .subresourceRange = {
      .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
      .baseMipLevel = 0,
      .levelCount = 1,
      .baseArrayLayer = 0,
      .layerCount = 1,
    }
};

vkCmdPipelineBarrier(
    command_buffer,
    VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,  // srcStageMask
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT, // dstStageMask
    0,
    0,
    nullptr,
    0,
    nullptr,
    1, // imageMemoryBarrierCount
    &image_memory_barrier // pImageMemoryBarriers
);

// begin dynamic rendering here

// draw calls

Almost all Vulkan renderers have helper functions for these image layout transition functions to reduce verbosity, but it is still quite a hassle to specify all the parameters. And we also need to do a similar layout transition dance for the depth buffer and stencil buffer, with access masks, pipeline stage masks, and layout changes accordingly.

Final word

In this simple case, the dynamic rendering extension seems almost as verbose as creating render passes and framebuffer objects. Though I can see that dynamic rendering becomes more valuable in multi-pass rendering, whereas synchronization becomes complicated with the traditional render pass approach. Khronos may also improve the ergonomics of dynamic rendering somehow in the future.

Acknowledgements

Special thanks to my friend Charles Giessen for proofreading and editing this post!

After this post was initially released, many experienced graphics programmers provided valuable insight and feedback.

Jeremy Ong provides insightful Twitter feedback on this post.
Karn Kaul mentioned that it would be more precise if I said that image layout transition for depth buffer is slightly different from color buffers. And he also noted that on some hardware and drivers, using the automatic image layout transition provided by render pass causes artifacts, and manual image layout transition is the only way anyway.
Leon Brands points out that the initial post didn’t talk about pipelines, so I added a section about the change in pipeline creation.
Timmy on Twitter noted that Nvidia is now shipping VK_KHR_dynamic_rendering in their game-ready drivers.

How I create bilingual functionality of this blog in plain Typescript

Sat, 01 Jan 2022 00:00:00 GMT

Update 2025: I’ve since migrated this blog to Astro, but the implementation strategy of the translation remains largely unchanged.

Happy new year 2022, everyone! Today I want to talk about something different from most of my blog posts: how I implement my bilingual blog in pure Typescript.

Since I created this blog in 2015, I have always wanted to make it bilingual to reach a broader audience, and I finally implemented it at the end of 2019. My implementation of internationalization was probably different from most people, as I use plain Typescript without any third-party libraries such as i18next. And I heavily rely on Typescript’s remarkable features in its type system for my implementation.

My solution is probably not the most “proper” or scalable by professional standard, but I think it fits the particular use case of a personal blog well. It provides several significant advantages:

The type system guarantees that it is impossible to forget to translate an entry
It is very flexible as I can have arbitrarily different Javascript for different languages (Since this website is implemented in React, I can use arbitrary JSX). This is a useful property when I only want to render certain UI elements in a selected language.
I don’t need to learn an i18n library just for my blog

And thus, I recommend you use a similar approach if you want to create a multilingual personal website.

This blog uses the static-site generator GatsbyJS. If you are not familiar with static-site generators, one cool thing they can perform is to transform contents in formats such as Markdown into proper HTML pages with the help of a “template.”

For blog posts, I have separate markdown files for different languages. For example, the Chinese version of this post and the text you are currently reading are stored in different markdown files. However, there is still a lot of text in the “template” that needs to be translated. Examples include my bio at the right sidebar, different menu items, and blog post tags.

The “template” of GatsbyJS is in Javascript (and I decided to use Typescript, which transpiles to JS), particular React components. As a result, it is natural for me to try to develop a Typescript solution for the internationalization problem, and all those React components and translations will be built into static HTML. On the other hand, suppose you use a static-site generator using Python. In that case, ideally, you should implement internationalization in Python so the translation can be done at build time to avoid the overhead of dynamically loading translation for your website.

Most of my internationalization implementations are in the translation.tsx file:

First, I have an en object that stores every translation entry in English:

const en = {
  ai: "AI",
  algorithms: "Algorithms",
  archive: "Archive",
  ...
};

Since en is just a plain object, I can also store more exciting data such as jsx objects or even functions as entries:

  all_n_posts: (n: number) => (
    <>
      All <Link to={`/en/archive`}>{n} posts</Link>
    </>
  ),

With en as an object defined, we can query its type by the typeof operator:

export type Translations = typeof en;

This reflection ability is handy, and most programming languages don’t have it. Specifically, it saves us from defining the type ourselves. And it is a nice example of how a language feature helps us achieve the DRY principle.

Now with the Translations type, we can create another object that mirrors the structure of en object, but with an explicit type requirement:

const zh: Translations = {
  ai: "AI",
  algorithms: "算法",
  archive: "博文目录",
  ...
};

This way, the type system ensures that I don’t forget to translate any entries.

And then, we can assemble translations of all languages into a single object. This object serves as the main entry point in our template to query specific translation entries:

export const translations = {
  en: en,
  zh: zh,
};

Then we use the keyof operator to get a union type of the keys of translation: in this case, "en" | "zh". keyof is yet another excellent reflection feature of Typescript. But since it expects a type rather than an object, we need to apply another typeof operator before applying keyof:

export type Language = keyof typeof translations;

I use the above union type whenever I need explicit type annotation for languages, for example, when passing the current language as a parameter.

And finally, we use Object.keys to get a list of languages, so we can loop through all languages.

export const languages = Object.keys(translations) as Language[];

This website is only bilingual, and I don’t know how to write in other languages. Still, there is no hard-coding of particular languages on my implementation, except I treat English as the “default” language. Thus, it is trivial to extend this implementation to support more languages. The only thing need to do is to define another object with the Translations type and add it as an entry to translations.

To use translation, we first need to pass the current language of the page to its components. Then we can use translations[lang]["entry"] exactly where I need the translation (replace "entry" with the entry I need). This scheme works for functions too, as I can just call the function like translations[lang]["all_n_posts"](n).

That’s it! I implemented the whole internationalization logic! To add new entries, we just need to add translations to the en and zh object. However, the most challenging part of maintaining a bilingual blog is always translating actual blog posts. And I can’t say I did a perfect job, as indicated by the large number of English-only versions of posts on this site. But, I’m going to keep working on it, and I hope that the technical aspect of my approach will inspire you to give it a try too!

Little C++ Standard Library Utility: std::align

Mon, 13 Dec 2021 00:00:00 GMT

I recently learned about std::align, one of the lesser-known functions in the C++ standard library due to its limited use cases. Since it is hard to describe without a specific use case, I will use a simple implementation of an arena allocator as a motivating example.

Arena allocator

Arena, also called bump allocator or region-based allocator, is probably the most straightforward allocation strategy. It is so widely used that even the C++ standard library has an arena implementation called std::pmr::monotonic_buffer_resource.

With arena, we start with a large chunk of pre-allocated memory coming from either the stack or another allocator such as mmap or malloc. Afterward, we allocate memory from that chunk by bumping a pointer offset.

Figure.1 - Arena before allocation

Figure.2 - Arena after allocation

Arena allocator has exceptional performance characteristics, especially when compared to complicated beasts like malloc. Each allocation only requires a pointer bump, and the deallocation is almost free as long as the objects allocated are trivially destructible. If we need to call destructors, we must maintain a list of objects to destroy. Supporting destructors complicates arena implementation considerably and is beyond the scope of this post.

The downside of the arena is that you can only free all the allocated memory at once since the arena doesn’t track each individual allocation. Nevertheless, it is helpful in situations where we have a lot of heterogeneous allocations that only need to be freed together, and is widely used in application domains from compilers to video games.

A minimum implementation of an arena

A straightforward implementation of the arena looks like the following:

struct Arena {
  std::byte* ptr = 0;
  std::size_t size_remain = 0;

  [[nodiscard]] auto alloc(std::size_t size) noexcept -> void*
  {
    if (size_remain < size) return nullptr;

    auto* alloc_ptr = ptr;
    ptr += size;
    size_remain -= size;
    return alloc_ptr;
  }
};

We can also store an end pointer instead of size_remain and compare ptr + size to the end pointer, though that won’t change the overall picture too much.

To use our arena, we first construct the arena from a pre-allocated buffer. Then we can allocate raw memory from the arena and create objects on top of the allocated memory:

std::byte buffer[1000];
Arena arena {
  .ptr = buffer,
  .size_remain = std::size(buffer)
};

auto* ptr = static_cast<std::uint8_t*>(arena.alloc(sizeof(std::uint8_t)));
ptr = new(ptr) std::uint8_t{42};

auto* ptr2 = static_cast<std::uint32_t*>(arena.alloc(sizeof(std::uint32_t)));
ptr2 = new(ptr2) std::uint32_t{1729};

The placement news here are no-op since our types are integers, but they are required to start the object lifetime. Without placement new, doing assignments like *ptr = 42 directly is technically an undefined behavior in C++.

Alignment

The simple solution above would be perfect if alignment doesn’t exist. However, in the real world, the pointer returned by alloc may not be appropriately aligned for the object we want to create at that memory location.

In C++, every type and object has an alignment manually controlled by alignas and queried by alignof.

Starting the lifetime of objects on unaligned locations is undefined behavior. Depending on different architectures, you may get slow memory access or even a mysterious crash if you try to access a misaligned object.

We usually don’t care about alignment that much since the compiler can figure it out for us, and standard library functions such as malloc automatically provides sufficient alignment (alignof(std::max_aligned_t)) for all allocations. However, when we start to play with custom memory allocation strategies, alignment suddenly becomes essential to understand.

Consider what our previous usage of the arena does. At first, our arena is empty. Then we allocate a byte of memory and construct a std::uint8_t on it, and everything seems totally fine. However, when we allocate 4 bytes now, we will allocate it at the place off by one byte of the 4-bytes alignment boundary that required by std::uint32_t:

Figure.3 - Arena after two allocations

The above example should convince you the importance of alignment when we start to get adventurous and come up with custom memory allocation strategies.

Arena, fixed

To implement an arena that considers alignment, we first need to have a helper function align_forward that bump a given pointer forward to an aligned address given a specific alignment:

[[nodiscard]] inline auto align_forward(std::byte* ptr, std::size_t alignment) noexcept
  -> std::byte*
{
  const auto addr = std::bit_cast<uintptr_t>(ptr);
  const auto aligned_addr = (addr + (alignment - 1)) & -alignment;
  return ptr + (aligned_addr - addr);
}

We first cast our pointer into an integer and then round up our (integer) address to the alignment boundary with the expression (addr + (alignment - 1)) & -alignment.

To understand what this expression is doing exactly, you need to think about the meaning of the - on integers in a bit-wise setting: it flips all the bits and then adds one to the result. For example, let’s say our alignment is 4, it is represented as

0b00000100,

and when we apply negation, we get -4, which is represented in two’s complement as

0b11111100.

I omitted all the leading bytes, but you should be able to see the pattern: the negation of an alignment is precisely the bit-mask we want to mask out the lower bits.

Finally, we need to cast our aligned_addr back into a pointer. I choose to do some pointer arithmetic instead of doing another bit cast (std::bit_cast<std::byte*>(aligned_addr)) so we don’t get pointer provenance warning from clang-tidy.

With the helper function in place, we can now implement our Arena:

struct Arena {
  std::byte* ptr = 0;
  std::size_t size_remain = 0;

  [[nodiscard]]
  auto aligned_alloc(std::size_t alignment, std::size_t size) noexcept -> void*
  {
    std::byte* aligned_ptr = align_forward(ptr, alignment);
    const size_t size_for_alignment = aligned_ptr - ptr;
    const size_t bump_size = size_for_alignment + size;
    if (size_remain < bump_size) return nullptr;

    ptr = aligned_ptr + size;
    size_remain -= bump_size;
    return aligned_ptr;
  }
};

Notice that I changed the function name from alloc to aligned_alloc since we must explicitly pass an alignment argument to this function. First, we call align_forward to adjust our pointer to the alignment boundary in the function. And then, we calculate how many bytes we need for the allocation (which is the number of bytes used for alignment plus the actual size we need to allocate). And finally, if we have enough size to allocate, we need to bump our pointer, decrease the remaining size, and return the adjusted pointer.

To use this implementation, we need to explicitly pass alignment to our arena:

auto* ptr = static_cast<std::uint8_t*>(
  arena.aligned_alloc(alignof(std::uint8_t), sizeof(std::uint8_t)));
ptr = new(ptr) std::uint8_t{42};

auto* ptr2 = static_cast<std::uint32_t*>(
  arena.aligned_alloc(alignof(std::uint32_t), sizeof(std::uint32_t)));
ptr2 = new(ptr2) std::uint32_t{1729};

You can see that our client-side code becomes a bit more nuisance to write. However, in practice, we can hide calls to aligned_alloc behind a templated function. The important thing is that our allocations will be properly aligned:

Figure.4 - Alignment-aware arena after two allocations

If you still want the old alloc member function that doesn’t consider alignment, we can write it as a wrapper of aligned_alloc that takes the alignment of std::max_align_t:

[[nodiscard]]
auto alloc(std::size_t size) noexcept -> void*
{
  return aligned_alloc(alignof(std::max_align_t), size);
}

This version of alloc always returns pointers aligned as strictly as std::max_align_t, similar to std::malloc. This way also guarantees to have a correct alignment for each allocation, though it can waste space if we have many allocations for small objects.

Enter `std::align`

The above implementation of the arena is reliable. I use an essentially identical version of the arena in a bunch of C projects. However, with a little bit of help from the standard library, we can do better in C++.

std::align is a standard function defined in <memory>. It has the following interface:

namespace std {
  auto align(std::size_t alignment,
           std::size_t size,
           void*& ptr,
           std::size_t& space)
  -> void*;
}

It does the following:

Given a pointer ptr to a buffer of size space, returns a pointer aligned by the specified alignment for size number of bytes and decreases space argument by the number of bytes used for alignment. The first aligned address is returned. — cppreference.

The interface of std::align is undoubtedly not easy to grasp, mainly because it has two in-out parameters passed by reference. But it serves a similar purpose as our align_forward function. The first two parameters, alignment and size, are the same parameters we passed to aligned_alloc. And ptr and space is the state of our arena.

std::align starts by checking whether we have enough space to allocate size bytes after the alignment adjustment. If so, it adjusts our pointer ptr, decreases space by the number of bytes used for alignment, and returns the aligned pointer.

with std::align, our code can be greatly simplified:

struct Arena {
  void* ptr = 0;
  std::size_t size_remain = 0;

  [[nodiscard]]
  auto aligned_alloc(std::size_t alignment, std::size_t size) noexcept -> void*
  {
    void* res = std::align(alignment, size, ptr, size_remain);
    if (res) {
        ptr = static_cast<std::byte*>(res) + size;
        size_remain -= size;
        return res;
    }
    return nullptr;
  }
};

We no longer need our helper function, align_forward, since std::align serves a similar purpose. It is nice that we don’t need to write pointer-to-integer casting and bit manipulation ourselves. And our aligned_alloc function also looks almost as simple as our initial alloc function that doesn’t consider alignment.

Notice that since std::align only increases ptr to alignment boundary and decreases size_remain by the number of bytes used for alignment, we still need to change those two variables with the actual size of the allocation.

Another small change is that std::align requires us to use void* while our previous implementation uses std::byte*. Since we don’t need to do pointer arithmetics ourselves anymore, it is OK to use void*, which is also the type our aligned_alloc needs to return anyway.

Conclusion

I am not sure how many use cases std::align has outside of custom allocators. Maybe it is also helpful to implement flexible array members-like structures. Nevertheless, I am glad we have this little utility in the C++ standard library to save me from scratching head on manual alignment calculation.

Fun with Ternary Search

Tue, 07 Dec 2021 00:00:00 GMT

This year is my first year doing the Advent of Code challenge, and today (2021 Day 7)‘s challenge is a fun one.

I won’t go to the details, but the problem involves finding the minimum for a function. The function takes an integer and returns another integer. An interesting property of that function is that it has one “valley”: Everything at the left of the global minimal point monotonically decreases. Everything at the right of the global minimal point monotonically increases.

You can think the function output as a bunch of integers like

100, 81, 56, 32, 16, 33, 44, 78, 129

And we want to find out the value 16.

Naively we can evaluate the function at every point in the domain and then find the minimum, and a slightly better way is to evaluate the function until we find where the result starts to increase. Both strategies requires O(n) time, but since our data are nicely “sorted,” we can do better.

Ternary Search

Ternary Search, similar to binary search, expliots our data’s pattern, and can achieve O(log n) asymptotic time. Wikipedia describe it as a technique for “finding the minimum or maximum of a unimodal function,” which is exactly the function we want to solve. The basic idea is simple: if we partition our domain into three segment by two point: left and right, then we can evaluate the function at left and right and get several cases:

f(left) < f(right)
f(left) > f(right)
f(left) == f(right)

If f(left) < f(right), which means either both left and right points are greater than the position of the local minimum, or left is less than the position of local minimum and right is greater than the position of local minimum. In either case, we know that the local minimum is not at the right hand side of right, so we can discard that part of the domain.

If f(left) > f(right), similarly we can discard the left hand side of left. And if f(left) == f(right), we can discard both side and only keep the range [left, right].

We can equally trisect the domain into left and right, and then we can run the above process recursively or iteratively to solve the problem. We still need a terminate condition: since our left and right can be stuck if right - left <= 2, we stop there and then fall back to linear search. And we can have the following pseudocode:

var left = domain.min
var right = domain.max
while (right - left) > 3 {
  let left_third = left + (right - left) / 3
  let right_third = right - (right - left) / 3

  if f(left_third) < f(right_third) {
    right = right_third
  } else {
    left = left_third
  }
}

for i in left until right get the smallest f(i)

It is an elegent and fun algorithm, and I am suprised that today is the first time I hear about it. And hopefully now you also understand how and when to use this algorithm.

Don't automatically use auto parameters in C++

Tue, 09 Mar 2021 00:00:00 GMT

Since the advent of C++14, we can create lambda expressions that take auto parameters. And in C++20, we can even do the same thing for regular functions. With this feature’s advent, the programming style where all parameters are auto becomes popular among some C++ programmers. However, the feature is not always optimal, and, frankly, I don’t think we should use it more often than it needs to. In general, the more specific we make the type of a parameter, the better.

Why do people like it?

It is easier, right? Not everyone wants to write out the explicit parameter type.

This can be a valid excuse when doing template-heavy generic programming, but a lot of the time the “annoying to write” type is avoidable with some refactoring, and we will even have higher-quality code by doing so.

For example, the following is a modified version of some code I found online, and I agree that it is annoying to write out about the explicit type of pair:

std::vector<std::pair<double, double>> pairs;

return std::accumulate(
  pairs.cbegin(), pairs.cend(), 0,
  [](auto acc, const auto& pair) {
      return acc + pair.first * pair.second;
});

I would also be clueless about this code’s meaning by reading this snippet since there is no meaning attached to a pair’s first and second values.

What if we change the element of pairs into a named structure?

struct Outcome {
  double probability = 0;
  double value = 0;
};

std::vector<Outcome> distribution;

return std::accumulate(
  distribution.cbegin(), distribution.cend(), 0,
  [](double acc, const Outcome& outcome) {
      return acc + outcome.probability * outcome.value;
});

Suddenly, it is clear that this code tries to calculate the expectation of a discrete random variable!

Unfortunately, instead of trying to give their code better types, some people become so adapted to the auto parameter style that they start to use it everywhere, even in places where writing auto doesn’t save keystrokes much or at all:

const std::vector<int> v1 = ...;
const std::vector<int> v2 = ...;
std::vector<int> smaller_ones;

std::ranges::transform(v1, v2, std::back_inserter(smaller_ones),
  [](auto x, auto y) { return std::min(x, y); });

Auto parameters generate templates

In some programming languages such as ML or Rust, the type system can infer the exact type of a function or a lambda expression based on their definitions. Those languages also have different type annotation syntax, which makes type annotations in parameters optional. Thus, writing lambda expressions without parameter types in those languages is ergonomic and idiomatic. Once users become accustomed to those languages, they often come back to C++ with the same coding style.

However, in C++, unlike in those languages, the “type inference” of parameter types is just an illusion. Template, overloading, and ADL (Argument-dependent lookup) all make such type inferences impossible. As a result, auto parameter results in unconstrained templates. For example, we can use the amazing cppinsights website to see what [](auto x, auto y) { return x * y + 42; }); desuger into:

class __lambda_5_2
  {
    public:
    template<class type_parameter_0_0, class type_parameter_0_1>
    inline /*constexpr */ auto operator()(type_parameter_0_0 x, type_parameter_0_1 y) const
    {
      return (x * y) + 42;
    }
    private:
    template<class type_parameter_0_0, class type_parameter_0_1>
    static inline auto __invoke(type_parameter_0_0 x, type_parameter_0_1 y)
    {
      return (x * y) + 42;
    }

  } __lambda_5_2{};

The issue is that template programming does not have the same experience as “normal” programming. Compilers often detect type errors later than desired, and we have worse IDE auto-completion/error detection support in template contexts. This problem becomes more prominent when we start to write lambda expressions that are more than a one-liner and even more so when we use auto parameters for normal functions in C++20.

Unconstrained template can be dangerous

Even when we need templates, constraining them is a better idea to use them. In one of his talks, Bjarne Stroustrup mentioned that we should think about auto as a concept— the least constraint one.¹

When a template is unconstrained, it is easy to have types that accidentally match an interface. For example, let’s say that we have a 3-dimensional vector structure, and it is natural we would want to perform dot products on them:

struct Vec3 {
  float x = 0;
  float y = 0;
  float z = 0;
};

auto dot(auto v1, auto v2) {
  return v1.x * v2.x + v1.y * v2.y + v1.z * v2.z;
}

Later, if we decide to add another 4-dimensional vector, we can invoke the same version of dot that is prepared for three-dimensional vectors and get a completely unexpected result:

struct Vec4 {
  float x = 0;
  float y = 0;
  float z = 0;
  float w = 0;
};

dot(Vec4{1, 2, 3, 4}, Vec4{1, 2, 3, 4}); // expects 30, gets 14

The C++ Core Guidelines also mentioned the danger of unconstrained templates in a highly visible scope, especially in combination with ADL. ²

Explicit type annotation provides documentation value

Even in languages without C++-specific problems, explicit parameter types provide documentation purposes and act as “type-checking barriers” during refactoring. That is why in ML dialects and Haskell, top-level functions without explicit type annotation are considered bad style, and Rust does not even allow it!

When using an unfamiliar API in any statically typed language, the type annotation is probably the first hint of what a particular function call does. By using auto parameters, we give other people and our future selves no hint about the nature of those parameters.

Conclusions

It is not always possible to avoid auto parameters. However, you should think about avoiding them, especially when your rationale for using them is nothing but convenience.

Before C++20, there was no way to use concepts or explicit template annotation for lambda expressions. Also, in some cases, the convenience and productivity gain of using auto parameters outweigh its drawbacks. However, I think the downside is severe enough to consider auto parameters a code smell. When meeting code with auto parameters, we should always ask, “Is it possible to use a concrete type here?” And if it is not the case, then the next question is, “Is it possible to use a concept here?”

Footnotes

Using default parameters to circumvent the type system is an anti-pattern

Fri, 26 Feb 2021 00:00:00 GMT

I am doing some peer programming for a university course project today. In our codebase, we have a Ship class like the following:

public class Ship {
    private final String name;
    private final int length;
    private int hitCount = 0;

    public Ship(String name, int length) {
        this.name = name;
        this.length = length;
    }

    // other methods
    ...
}

Later, the new requirement of the course project requires us to add another field, what we called captainsQuertersHealth, to the class, so we made the following change:

public class Ship {
    private final String name;
    private final int length;
    private int hitCount = 0;
    // highlight-start
    private final int captainsQuertersHealth;
    // highlight-end

    // highlight-start
    public Ship(String name, int length, int captainsQuertersHealth) {
    // highlight-end
        this.name = name;
        this.length = length;
        // highlight-start
        this.captainsQuertersHealth captainsQuertersHealth;
        // highlight-end
    }

    // other methods
    ...
}

However, we had tons of unit tests that test against the old interface and they don’t care about the captainsQuertersHealth field. My partner suggested adding a default parameter. Since the course project is in Java, which doesn’t support default parameters by default, he recommends adding an overloaded constructor:

public Ship(String name, int length) {
  this(name, length, 1);
}

This constructor delegates to the previous constructor and always default captainsQuertersHealth to one. It is certainly convenient. However, adding this constructor means that the compiler will not be able to generate a compile-time error at places where we use this constructor, and at those places, we do care about captainsQuertersHealth. As a result, it would postpone a compiler catchable bug to runtime.

I convinced my teammate that it was a bad idea. And our final solution was to add a helper in unit tests:

private Ship createShip(String name, int length) {
  return new Ship(new, length, 1);
}

I am not saying that you shouldn’t use default parameters or function overloading, but do notice their shortcoming and use them judiciously.

What is std::function in C++, and why do we need them?

Mon, 18 Jan 2021 00:00:00 GMT

Yesterday, someone in the #include<C++> discord server asked the following question:

how std::function works with lambda captures and functions handling I still don’t understand

Below was my answer to the question, with some typo-fixes and expansions:

Invocables can have different types even if their parameter and return types are the same

In C++, lambda expressions can be considered syntactic sugar over classes with operator() defined. For example:

int x = 3;
auto lambda = [x](int y) { return x + y; };

is roughly equivalent to

struct __Lambda {
  int x;

  int operator()(int y) const {
    return x + y;
  }
};

int x = 3;
auto lambda = __Lambda { .x = x };

One consequence is that every lambda expression has a distinct type. For example, in the below snippet,

int x, z;

auto lambda = [x](int y) { return x + y; };
auto lambda2 = [x, z](int y) { return x + y + z; };

lambda and lambda2 have different types, even though they both take an int and return an int.

C++ also have functions, which are distinct from classes with operator().

The motivation for `std::function`

Then, how do we store such an invocable object that takes an int and returns an int disregard of its types?

We need std::function to accomplish such a task. For example:

struct S {
  std::function<int(int)> func;
};

A canonical use case for storing an invocable in this fashion is a task system, where you probably want to store callbacks in a container to execute later:

struct TaskQueue {
  std::queue<std::function<void()>> queue;
  std::mutex mutex;
  std::condition_variable ready;

  // member functions
  ...
};

Type Erasure

To make func accepts both lambda and lambda2, std::function needs to have constructors that take any function object or plain function that satisfies its signature. And we need to perform type erasure to achieve this behavior.

There are various techniques to implement type erasure in C++, and it is not a topic I can fit into this post. But the high-level idea is that std::function needs some function pointer that can invoke the invocable and some storage space to store lambda captures (or data members of a function object). The data need to be allocated on the heap since lambda expressions (or invocable classes) can have arbitrary sized capture. However, all major std::function implementations also perform small buffer optimization if your lambda is small enough to fit into a predefined capacity. In that case, all data can be allocated directly inside the std::function object itself, and no additional heap allocation is performed.

Resources that help you to delve into C++

Fri, 15 Jan 2021 00:00:00 GMT

I already received some great feedback for this post, and any further feedbacks, error-correction, and resource recommendation are welcome. One way to contact me is to direct message me (@lesley@mastodon.gamedev.place) on Mastodon.

Update 2021-03-29: Add a bunch of resources.

During the years, a lot of people ask me for help in learning C++. I am no C++ expert, but as a person who is doing C++ for years, I want to share a bunch of beginner-friendly C++ resources that are known to be of high quality. And hopefully this list of resources can help learners who are new to C++.

When anyone asks me for guidance about getting into C++, I always ask first about their existing experiences. Some people just start to learn programming and decide to learn C++ as their first language, some people have learned a limited amount of C++ and want to learn more, and some of them are already programming veterans in other languages. Depend on your experiences, you probably want to start with different materials, and I try to cater to each of those backgrounds in this post.

One thing I want to mention, though, is that reading books or watching videos all the time is not the best strategy to learn. Whatever stage you are in, it is much easier to learn when you apply ideas into code, so spending time on coding projects helps.

What if I just start learning to program and choose C++ as my first language?

For beginners, it is important to only “learn from the best” since it is hard to discern if your tutorial is making mistakes or encouraging bad practices.

For books, I recommend Bjarne Stroustrup (the creator of C++) ‘s “Programming: Principles and Practice Using C++ 3rd edition” as a starting point. The book is thick, so don’t feel guilty if you cannot finish the whole book.

If you are more inclined toward tutorial videos, look at Kate Gregory’s Learn to Program with C++. If you join the #include<C++> discord server, You can also message her there to get a trial code.

What if I already learned some C++ before and want to delve in deeper?

What if you have some limited C++ experience before? Maybe you already learned some C++ from your university data structure course, or perhaps you followed some online tutorials that use C++. From my personal experiences and what I heard, most university programming courses or those online tutorials teach problematic practices, and the instructors often do not have a good grasp of the language. Thus, “learn from the best materials” is especially important for you to offset prior misconceptions on C++.

For books, I will still recommend either Bjarne Stroustrup’s “Programming: Principles and Practice Using C++ 3rd edition”. And for video tutorials, you can try Kate Gregory’s C++ Foundations.

What if I am a veteran in another language and want to delve into C++?

If you are already a proficient programmer in some other languages and want to delve into C++, you can choose materials with faster pace.

As for book recommendations, Bjarne Stroustrup’s “The C++ Programming Language (4th Edition)” was one of the best-written books I ever read, though do notice that this book was written with C++11 and misses some of the later developments. The book is also very thick, so if you want a newer and shorter introduction, try ”)”.

I think that I have a decent grasp of C++. What’s next?

So you spend months with the above materials, and feel that you have a decent grasp of basic C++ concepts.

A sanity check to make sure about your understanding of C++ is whether you are familiar with the following topics, to name a few:

how to use const
templates
references and pointers
usage of the standard library, in particular, iterators and algorithms
RAII
destructor
copy and move constructor and assignment
move semantics
operator overloading
lambda expressions and function objects
undefined behaviors

Now it is time to put C++ into practical usage. C++ is used for diverse purposes, and using C++ in specific areas is probably more critical than the C++ language itself. It is perhaps also a good time to spend some time on the broader C++ ecosystems, like testing libraries such as Catch2, build system generators such as CMake, and package managers such as Conan or vcpkg.

Another thing to consider is to start learning another programming language, especially for folks who only know C++ at this point. Good next languages to pick are those very different from C++, for example, dynamically-typed languages such as Javascript, Python, or a Lisp dialect.

That being said, there is still a lot to learn about the C++ language itself. And I will try to list some resources that are still relative up-to-date and I enjoyed:

Books

If you haven’t read “The C++ Programming Language (4th Edition)”, I would still recommend it. And here is a bunch of other books I would like to recommend:

“Effective Modern C++” by Scott Mayer
“C++ Best Practices” by Jason Turner
“C++17 - The Complete Guide” by Nicolai M. Josuttis

Some books focus on specific areas of the language, such as:

“C++ Templates - The Complete Guide, 2nd Edition” by David Vandevoorde, Nicolai M. Josuttis, and Douglas Gregor
“Mastering the C++17 STL” by Arthur O’Dwyer
“Functional Programming in C++” by Ivan Čukić
“C++ Concurrency in Action, 2nd edition” by Anthony Williams

Conference Videos

Conference videos are also an excellent resource to learn more about C++. They focus on a diversity of topics; many of them are hard to find in books. And they also require low commitment (just spend an hour lunchtime watching some videos)

Here are some of my favorites that are also beginner-friendly:

Communities

Many people in the C++ community, and I am always willing to answer direct messaging questions. However, I, or most people you can contact online, have limited experiences.

To utilize the best wisdom of people, you need to join programming communities, and then you can ask questions in public and get a response from multiple people. ¹

Being active in programming communities also has numerous other benefits, including getting job information and having more social support.

#include<C++>

#include<C++> is a wonderful community to join. Its mission includes providing conference scholarship to people in need, but for most people, you can join its discord server to hang out and talk about C++.

Local Meetups

Joining North Denver Metro C++ Meetup was one of the best decisions for me during my college years. I understand that it is a hard time to pop into meetups at the time of writing since most of them are currently held online. Nevertheless, I urge you to try to attend some meetups if you have time. Online meetings also provide some advantages compare to physical ones. For example, they require low commitment, and you can choose from all of those meetups worldwide.

Attending Conferences

If you are serious about C++, then conferences are great places to meet like-minded people. There are C++ conferences around the globe.

Same as meetups, one difficulty at the time of writing is that most C++ conferences are hosted online, but they are still worthwhile to consider. Here are some of the recurring C++ conferences or conferences that heavily feature C++, with their Twitter handle and Youtube Channel:

CppCon [Youtube] (U.S.-based)
C++Now [Youtube] (U.S.-based, tuned toward a more advanced audience)
ACCU [Youtube] (UK-based, different programming languages, but has a lot of C++ contents)
Meeting C++ [Youtube] (German-based)
emBO++ [Youtube] (German-based)
C++ on Sea [Youtube] (UK-based)
Core C++ [Youtube] (Israel-based)
Code::Dive [Youtube] (Poland-based)
Code Europe [Youtube] (Poland-based, different programming languages)
NDC Conferences [Youtube] (Multiple locations, different programming languages) ²

There is a list of conferences on the ISO C++ website.

Listening to Podcasts

There are a bunch of C++ podcasts, including a few new ones appeared in 2020:

Following Blogs

I use RSS to keep track of the tech blogs, and I highly recommend you try out RSS too.

I follow hundreds of blogs ³, including C++ and various other topics. Here are some of the best C++ ones that pops into my head:

Do notice that blogs sometimes can talk about very advanced topics.

Misc resources

Here are some misc resources that are also worth mentioning. Some of those are great online tools, while others are video series.

cppreference should be your go-to site for C++ language and standard library reference, and it is usually a lot more accurate and up-to-date than its alternatives.
Compiler Explorer is an online coding environment that supports C++ and a dozen other languages. It can show the compiled assembly of your program and run your program. Unlike most online C++ coding environments, which often ship with an outdated compiler, there are many compilers to choose from in compiler explorer, including the most cutting-edge ones.
Quick C++ benchmark is an online tool to perform quick benchmarks on C++.
C++ Insights is an invaluable tool to show how compilers translation “syntactic sugar” such as lambda expressions and range-based for-loop behind the scenes. I used it in my C++ lambda tutorial post.
C++ Tips of the week
Kate Gregory’s STL Algorithms course is a great resource to learn more about and appreciate C++ standard algorithms.
C++ Weekly is a Youtube channel on various C++ topics, posted weekly.

References and further reading

“SG20 Education And Recommended Videos For Teaching C++”. Christopher Di Bella, 2021, https://www.cjdb.com.au/sg20-and-videos. Accessed 15 Jan 2021.
“References And Links”. #Include {’<‘}C++{’>’}, 2021, https://www.includecpp.org/resources/references/. Accessed 16 Jan 2021.
Yaghmour, Shafik. “Where To Get Started Learing C++ And What Resources To Use”. Shafik Yaghmour’s Blog, 2019, https://shafik.github.io/c++/learning/2019/09/05/getting_started_learning_cpp.html. Accessed 16 Jan 2021.

Footnotes

Asking questions online is an art, and a poorly phrased question makes people don’t know how to respond. Further, people are often too polite to point out that a question is poorly phrased. Kate Gregory’s How to ask for C++ coding help is an excellent read on how to ask for help online. ↩
Some of the links above are collected from shafik/cpp_youtube_channels ↩
If you want to see all the blogs I follow, visit this gist. ↩

Factual errors in "These Modern Programming Languages Will Make You Suffer", and why it is a suffer to read

Tue, 08 Dec 2020 00:00:00 GMT

Today I stumble upon an article These Modern Programming Languages Will Make You Suffer after Twitter outrage. The post is absurd and indeed a suffer to read for me. However, it also receives 1k+ medium claps at the time of writing, and I cannot stay silent.

In essence, this article tries to promote functional languages and list their advantages. As an FP fanboy myself, I love content that encourages the usage of functional programming. However, this article is so biased and full of factual errors, to the degree that it only shows the author’s lack of understanding in both the languages they hate and the languages they try to promote. And I am not even surprised to find that the author was behind another notorious medium clickbait, Object-Oriented Programming - The Trillion Dollar Disaster.

I will not focus on this article’s opinions. Various Twitter shitposts sometimes have more extreme views than this article. Also, it is hard to criticize objectively on buzzwords such as “bad” or “a mess.” Instead, let’s focus on the misleading factual errors. Though I am sure that there are still many more factual errors in the section I missed or in languages where I don’t have experience.

Pure functions

Functions that do not mutate(change) any state are called pure

Pure functions are deterministic and have no side-effect. “Do not mutate” is way not enough to make a function “pure.”

Surprisingly, the author has a correct description of pure function later in the post, and similar discrepancy also happened more than once, which made me wonder whether a large chunk of the article is “borrowed” from elsewhere.

C++

C++ is the perfect punch bag for a lot of reasons, but still, you shouldn’t bash on a language if you have no understanding of it.

The developers have to worry about manually releasing and allocating memory.

Do you know what RAII is? And have you ever used C++ or Rust before? The same argument can go to the author’s rant on the lack of GC in Rust.

has only rudimentary concurrency mechanisms

Let me reply with a tweet from Bryce Lelbach.

Almost everything in this article is patently wrong, like the claim that "[C++] only rudimentary concurrency mechanisms". C++ has a formally verified memory and execution model, which is the defacto industry standard, and a rich library of concurrency primitives.
— Bryce Adelstein Lelbach (@blelbach) December 8, 2020

In C++, all references are nullable.

In C++, no references are nullable 😉.

JAVA & C#

since the early versions of C# were a Microsoft implementation of Java

C# was an imitation of Java. But it was a new language and never intended as an implementation of Java.

In particular, C# claims to support functional programming. I must disagree… What functional features should a language have? At the very least, built-in support for immutable data structures, pattern matching, pipe operator for function composition, Algebraic Datatypes.

Those are all great features, but none of them are the essence of functional programming. The first functional language, Lisp, supports none of those features.

By the way, C# does support pattern matching. ¹ The author seems to acknowledge this fact earlier and forget later, again made me wonder whether some part of the post is “borrowed” from elsewhere.

rudimentary concurrency support

C# is the language that makes the async/await paradigm popular.

In C#, all references are nullable.

Except that there are nullable-references support and references can be made not-null by default.

Python

Language family: C

What does “The C family languages” even mean? Languages share a syntax resemble C? And how does Python suddenly become a C-family language?

Python is an interpreted language

“Interpreted language” is a common buzzword in this field without a clear definition. Instead of the language itself, a language implementation decides whether it is “interpreted” or “compiled.” Plus, there are a lot of middle-ground between an ahead-of-time compiler and a tree-walk interpreter, and most language implementations these days are in the middle ground.

Python is also pretty slow to start up

A Python VM usually boots up in less than 100ms.

Rust

Rust also suffers from a lot of unfair ranting for its “low productivity” in this article, and to be honest all the criticism for Rust in this article looks like from a quick Google search.

The runtime performance of Rust programs is a little faster than Go.

You can’t compare the runtime performance of programming languages without context like that. There are a lot of performance design tradeoff, and a language that runs faster in one circumstance is possible to run slower in another.

The first language on our list with a modern null alternative

C++ has std::optional² and Java has Optional³.

Developers have to worry about things like boxing and pinning, which typically are done automatically in a garbage-collected language.

Some garbage collectors move memories in a process called memory compaction, and that is why C#, for example, also support pinning.

Typescript

Even experimental features can be enabled in JavaScript with the use of Babel, which can’t be done for TypeScript.

Totally not true⁴.

While JavaScript developers can use libraries that help with immutability, TypeScript developers typically have to rely on the native array/object spread operators

Both immutable.js and Rambda, the Javascript libraries that the author mentioned, provide typescript type definitions, and they are not harder to use compared to using them in JS.

Functional languages

As a person who tries to promote functional languages, the author should know better about those languages. Unfortunately, the author seems to have more errors in those languages, probably because they change from “opinionated rant mode” into actually talking about language features in this section.

Haskell

There’s no type system more powerful than Haskell.

No type system can be considered the most “powerful.” By the way, what about dependent type languages ⁴?

OCaml

There’re three package managers — Opam, Dune, and Esy.

Dune is not a package manager, but instead a build system. It is often used in combination with Opam.

The go-to book for learning OCaml is Real World OCaml. The book hasn’t been updated since 2013, and many of the examples are outdated.

The 2nd edition of Real World OCaml is up-to-date and also available freely online.

Scala

Scala has first-class support for immutable data structures (using case classes).

The Scala standard library does provide fantastic support for immutable data structures. However, case classes have nothing to do with those data structures.

Elm

The only time when you will encounter runtime errors with Elm is when interacting with outside JavaScript code.

Unfortunately, the Elm compiler still can generate Javascript code that throws exceptions at runtime.

interop with JavaScript libraries next to impossible

There are custom elements⁵ and ports⁶.

This means that the developers have no access to the vast ecosystem of libraries and components made for React.

You can make a React component a custom element.

We don’t even know whether or not he’s still working full-time on Elm. The language might actually be dead by now.

Evan is still doing work on Elm and interacts with the community regularly.

Reason ML

Just like TypeScript, ReasonML has access to the entire JavaScript ecosystem.

Using Javascript libraries in Reason requires some boilerplates (external), just like in Elm.

React initially was written in OCaml

The first prototype of React was written in Standard ML, rather than OCaml.

Elixir

Language family: ML.

Ok, I can stand that you say Haskell or Elm is in the ML family (though I disagree), but what is a dynamic-typed language doing here?

Conclusion

The article has some good content on pure functions, algebraic data types, pattern matching, and error-handling in FP languages. If the author removes all the biased, incorrect, and misleading content, I would recommend it for people to read. However, the author chooses a different path. Unfortunately, the Internet always rewards clickbait and sensational articles these days instead of posts with meaningful content.

Also, what worries me is that these kinds of blog posts will push people away from functional languages. A minority of trolls make people lose faith in the whole community. For example, here is one comment on Medium to the article:

Ooh, you’re a functional programmer! That explains why I had that feeling you didn’t know what you were talking about.

I can stop reading now. I read enough flawed examples, dubious comparisons and more from articles written by your kind.”

Rest assured that most people in the functional programming community are friendly and don’t have that kind of bias against your favorite language.

Footnotes

Improve Rust Link Time with lld

Sun, 01 Nov 2020 00:00:00 GMT

Update 2025: Rust now uses lld as the default linker on x86-64 Linux in nightly. Some Rust’s wasm and aarch64 targets also already use lld by default.

For faster iterative development, alternatives like mold and wild are also worth considering.

Today I start to experiment with the WebGPU API, and I choose to use the wgpu-rs implementation in Rust. I am happy with the experience overall, but one difficulty I met is the long iterative compilation time:

Compiling
Source: xkcd

The compile-time of my webgpu project is ridiculously slow (about 10s for this single file), any #Rust expert know how to improve that?
— Lesley Lai (@LesleyLai6) November 2, 2020

For some applications, slow compile-time is OK. Coding some hard algorithms requires extensive thinking, and if they compile and pass unit tests, they are likely correct.

By contrast, for graphics and game programming, iteration time is paramount. A lot of the time, there are no right or wrong answer to a problem, instead, we need to do a lot of small tweakings.

Fortunately, a person (user Rukai) on the Graphics Programming Discord provides a solution.

What I need to do is to create a config file ~/.cargo/config as

[build]
rustflags = [
  "-C", "link-arg=-fuse-ld=lld",
]

This flag sets lld to the linker, which is way faster than Rust’s default linker. And I also need to install lld on my computer.

And this simple change magically makes my iterative compilation time under 3s. It is still not ideal from my perspective, but at least I can enjoy doing this project again.

Recursive Modules in OCaml

Thu, 15 Oct 2020 00:00:00 GMT

Recursive module is an interesting feature in OCaml. To use it, we need to use the form

module rec module-name : module-signature = module-expr

Explicit signature is required when using recursive modules, as the compiler can no longer deduce the module signature with recursion.

A typical recursive module looks like the following:

module rec M : sig
  (* explicit signature *)
end = struct
  (* Implementations *)
end

And we can even have mutually recursive modules, for example:

module rec A : sig ...end = struct ... end
and B : sig ... end = struct ... end

My primary use case of recursive modules is to combine with first-class modules. First-class modules are ordinary values that wrap a module. It is a powerful way to introduce dynamic polymorphism in OCaml.

Dynamic polymorphism is usually combined with recursive data types, but Ocaml modules are not recursive by default. Thus, recursive modules serve as valuable additions.

For example, I use first-class modules and recursive modules in my ocamlpt project. Ocamlpt is a path tracer, where its scene contains different kinds of shapes. The signature of a shape is the following:

module type Shape = sig
  type t
  val hit: Ray.t -> t -> Material.hit_record option
  val bounding_box: t -> Aabb.t
end

We want to make the shape polymorphic, so we need to use first-class modules. In the below code, I introduce a Shape_instance modules that wrap both the shape module and the value of that module, and I also add a build_shape function that builds first-class modules of the signature of Shape_instance. This way, we can store those first-class modules, and Whenever we want to use them, we can unwrap the first-class modules to get a concrete Shape_instance module.

module type Shape_instance = sig
  module S: Shape
  val this: S.t
end

let build_shape
    (type a)
    (module S : Shape with type t = a)
    (shape: a)
  =
  (module struct
    module S = S
    let this = shape
  end : Shape_instance
  )

The above code is good enough to deal with concrete shapes such as spheres or triangles. However, the shapes are organized in a tree structure called bounding volume hierarchy (BVH). And each BVH node can contain other shapes, including BVH nodes themselves.

We can implement the BVH node with recursive modules:

module rec Bvh_node : sig
  include Shape
  val created: (module Shape_instance) list -> t
end = struct

type t = {
  left: (module Shape_instance);
  right: (module Shape_instance);
  aabb: Aabb.t;
}

(* Other members of the Bvh_node module *)

(* Creating bvh code from a list of objects *)
let rec create (shapes: (module Shape_instance) list) =
  ...
  (* if shapes contain 3 elements *)
  let left = ...
  and right = ... in
  let aabb = Aabb.union left.aabb right.aabb in
  { left=(build_shape (module Bvh_node) left);
    right=(build_shape (module Bvh_node) right);
    aabb }

end

The above code works like magic, but the code would not compile without the rec keyword before Bvh_node, since the create function refers to the module Bvh_node itself.

All in all, recursive modules is a way to support cyclic dependencies among components that the purely hierarchical module systems cannot support. Such cyclic dependencies are usually undesirable and can be avoided by changing the software design. Nevertheless, sometimes there are legitimate reasons to have a module depend on itself, especially consider how versatile the OCaml module system is. In those cases, recursive modules can serve as a valuable asset.

Beware passing mutable lambda to STL algorithms

Wed, 30 Sep 2020 00:00:00 GMT

Recently, I have seen some people passing complex mutable lambdas to standard algorithms. Those usages usually come from one mindset: “Since we want to follow ‘no raw-loop,’ and the choice of STL algorithms is limited, what can we do other than using a mutable lambda to hold our complicated logic?” I think that both premises of this thought are wrong. First, “no raw-loop” should be treated as an ideal instead of dogma. Second, even though STL algorithms cannot cover every use case, we can always write algorithms to fit our needs.

I expressed this thoughts in the following tweet:

Random thought: if you want to pass a complicated mutable lambda to a C++ standard algorithm, you are using the wrong algorithm.
— Lesley Lai (@LesleyLai6) September 21, 2020

And this post tries to expend this thought a little bit.

Mutable Lambdas destroy the beauty of `<algorithms>`

Why we use <algorithm>? Is it because it is “elegant” or “modern?” Or is it because “Some experts said so?” Both are horrible reasons to prefer <algorithm> over loops. For me, <algorithm> provides the following benefits:

Less mutable states
Declarative
Express intent
Known correct implementation

Mutable lambda destroys all of them. First, STL algorithms encapsulate mutable states into small functions. Nevertheless, we only need mutable lambda when our algorithm fails to encapsulate all mutable logics. Second, since the mutable states and complex control flow are back, we can no longer call our implementation declarative. Third, since we need complicated logic inside a lambda to stretch the algorithm to perform our task, the algorithm does not express our intent. Fourth, since the algorithm does not express our intent, even though the algorithm itself is correct, there can still be bugs lure in our own hard-to-understand code.

A LeetCode example

Let’s look at the following C++ solution to the LeetCode Two Sum problem by Yacob Cohen-Arazi. The problem is worded as follows: “Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.” and LeetCode provides the type signature of the twoSum function that we cannot change.

std::vector<int> twoSum(std::vector<int>& nums, int target) {
  int idx1{}, idx2{};
  auto process_and_lookup(
      [m = std::unordered_map<int, int>(),
       i = 0, target, &idx1, &idx2]
      (const auto item) mutable {
        auto iter = m.find(target - item);
        if (iter == cend(m)) {
          m[item] = i++;
          return false;
        }
        idx1 = iter->second;
        idx2 = i;
        return true;
      });

  auto iter = std::find_if(
    cbegin(nums), cend(nums), process_and_lookup);
  assert(iter != cend(nums));
  return {idx1, idx2};
}

This version is long, messy, and hard to read. It also contains five mutable states m, idx1, idx2, i, and target, even though target is never modified. Here is the loop version I wrote that are doing essentially the same logic:

std::vector<int> twoSum(std::vector<int>& nums, int target) {
  std::unordered_map<int, int> nums_map;

  const int size = static_cast<int>(nums.size());
  for (int i = 0; i < size; ++i) {
    const auto item = nums[i];
    const auto iter = nums_map.find(target - item);
    if (iter != nums_map.end()) {
      return {iter->second, i};
    }
    nums_map.emplace(item, i);
  }
  throw std::runtime_error{"No solution exist"};
}

This loop version is shorter, easier to understand, and only contains two mutable states: the map nums_map and index i.

The <algorithm> version lands badly here because std::find_if does not match this problem’s intent. std::find_if finds a single element that matches a predicator, but our situation requires to find two elements that match a predicator together. As a result, it does not provide enough useful functionalities for this problem but instead serves as an obstacle. I consider this kind of <algorithm> usages instances of the abstraction inversion anti-pattern, where the abstraction is so unfit for the task that we start to re-implements the implementation details that our abstractions suppose to hideaway. This kind of usage makes the code hard to read, introduces potential non-trivial runtime cost, and increases the possibility of introducing bugs. The <algorithm> header tries to address all of the adversities, but by using mutable lambda, we somehow land us in a situation worse than the loop counterparts of our functions.

Another Example: Calculates inner product until it satisfies a predicate

Dima Savin gives me a tricky problem:

Ok, which algorithm should I use to calculate the inner product until it exceeds a value and get the index when it happened? Didn't find find just the right thing in a table by @code_report that doesn't require a mutable lambda.
— Dima Savin (@dima_savin) September 21, 2020

This problem is tricky to solve with STL algorithms since STL algorithms are designed to compose sequentially, and as we will see in the loop version, there is multiple interleaved logic during the iteration.

Thus, I will use the loop version as the starting point. Since Dima does not specify what happens if we didn’t find the index, I return the final result of i, which should be the index of the last element plus one:

template <std::input_iterator Itr, std::input_iterator Itr2, class T>
auto inner_product_till(
        Itr first1, Itr last1, Itr2 first2, const T upper_bound)
   -> std::size_t
{
  T acc{};
  std::size_t i = 0;
  for (; first1 != last1; ++first1, ++first2, ++i) {
    acc = std::move(acc) + *first1 * *first2;
    if (acc > upper_bound) { return i; }
  }
  return i;
}

This version is certainly not ideal. It contains four mutable states first1, first2, i, and acc. Nevertheless, the logic inside the loop is simple, and every decent C++ programmers should be able to grasp this code in a relatively short amount of time.

I am satisfied with this version. Even the person who proposed “no raw loop” ideology in the first place, Sean parent, will not consider this kind of simple loops that are nicely encapsulated in a function “raw loops.”

A raw loop is any loop inside a function where the function serves purpose larger than the algorithm implemented by the loop — Sean Parent, 2013 ¹

The std::find + mutable lambda version, however, is certainly inferior to the loop version. This version contains the same amount of mutable states, and is signaficantly harder to read even for people familiar with this kind of lambda-heavy style of programming:

template <std::input_iterator Itr, std::input_iterator Itr2, class T>
auto inner_product_till(
        Itr first1, Itr last1, Itr2 first2, const T upper_bound)
   -> std::size_t
{
  std::size_t i = 0;
  std::find_if(first1, last1,
              [acc = T{}, first2, upper_bound, &i]
                (const T& elem) mutable {
                  acc = std::move(acc) + elem * *first2;
                  if (acc > upper_bound) return true;
                  ++first2;
                  ++i;
                  return false;
                });
  return i;
}

If we step back a little bit and think about what logic we try to achieve here. We can find two interleaving steps. First, we need to perform an inner product to the elements we meet so far. Second, we find whether this calculated inner product is greater than the upper_bound. If we ignore the “interleaving” part, then we can use std::transform and std::partial_sum to perform the first step and std::find_if to perform the second step:

template <std::input_iterator Itr, std::input_iterator Itr2, class T>
auto inner_product_till(
        Itr first1, Itr last1, Itr2 first2, const T upper_bound)
    -> std::size_t
{
  std::vector<T> products;
  std::transform(first1, last1, first2, std::back_inserter(products),
                 std::multiplies<T>{});
  std::partial_sum(products.begin(), products.end(),
                   products.begin());
  const auto result = std::find_if(products.begin(), products.end(),
                      [&](T e) { return e > upper_bound; });
  return std::distance(products.begin(), result);
}

This version is the closest to my thought flow, however, it is also very inefficient since it allocates extra heap memory and eagerly computes results that we may not need. Lazy ranges view solves the performance problem, If ranges have numeric algorithms support, then we can potentially write the following code:

template <std::input_range Range, class T>
auto inner_product_till(Range r1, Range r2, const T upper_bound)
    -> std::size_t
{
  return std::ranges::distance(
    std::view::transform(r1, r2, std::multiplies<T>{})
    | std::view::partial_sum
    | std::view::take_while([&](T e) { return e > upper_bound; }));
  );
}

This version is splendid. It does not allocate and exit early, so in theory, it can be as efficient as the raw loop version or the mutable lambda version, and it is certainly much more readable and less error-prone to write than both of them. Unfortunately, none of the algorithms in the <numeric> header is included in the C++20 ranges. As a result, std::view::partial_sum is not a thing at the time of this writing. Nevertheless, the range-v3 library includes all those functionalities.

Don’t be afraid of writing your own algorithm

Another way to solve this problem is to write your own STL-style algorithm. For example, in the above example, we can write our own view::partial_sum view adapter.

Our algorithm often does not need to be very generic in practice, as you can always enhance it later when you need to reuse this piece of code. The starting point of an algorithm can merely be “extracting a loop into a function.”

Also, the interesting thing is that the above inner_product_till is an STL-compatible algorithm. And we can treat it as one of the lowest levels of abstraction. If it is well tested, fast, and well behaved, who cares about whether it uses loops or other algorithms under-the-hood? It is not as generic as std::inner_product, but we can always add initial value and the plus/multiply binary operations as parameters later if we need them.

What about using mutable lambdas in `std::generate`?

A lot of usages of std::generate use mutable lambdas as a “generator” function. For example, the following code generates the first 20 numbers of the recurrence relationship .

int seq[20];

std::generate(std::begin(seq), std::end(seq),
    [x = 0]() mutable {
        return std::exchange(x, x * 2 + 1);
    });

This kind of “generator” usage of std::generate and mutable lambdas is common, and I think, unlike previous examples, they are fine.

There is an advantage of this version compared to using a loop. Compared to the equivalent loop version, the scope of the mutable variable x is constrained to be in lambda’s scope. And we should strive to make the scope of variables (especially mutable) as small as possible. Nevertheless, we can surround the loop with explicit brace pair to get a similar effect:

int seq[20];

{
  int x = 1;
  for (auto& elem: seq) {
    elem = std::exchange(x, x * 2 + 1);
  }
}

Consider the alternatives over passing mutable lambdas to STL algorithms

To sum everything up, I believe passing mutable lambdas to STL algorithms other than std::generate or std::generate_n is an anti-pattern that we should try to avoid. There are several alternatives. Sometimes we can switch to a better algorithm. Sometimes using a plain-old loop is the better option. And sometimes, we can write our customized algorithms to achieve the task.

Footnotes

Sean Parent, 2013. C++ Seasoning. Retrieved September 23, 2020, from http://channel9.msdn.com/Events/GoingNative/2013/Cpp-Seasoning ↩

The implication of const or reference member variables in C++

Tue, 18 Aug 2020 00:00:00 GMT

In the conventional wisdom of the C++ community, non-static const or reference data variables are considered problematic. Surprisingly, I cannot find a single resource dedicated to this topic.

I decide to write this post because the same problem raises several time by different people on Twitter and the #include ＜C++＞ discord server. There are solid reasons on why you should avoid const or reference member variables in C++. Nevertheless, like many things in C++, “avoid” does not mean “never use.” And they can occasionally still find some uses.

Const members

If you are familiar with any programming languages, such as Rust, that treat const as default and mutable as second class citizens, you may have the temptation to mark everything const if you don’t need to modify them. This practice provides a lot of benifits even in C++, as countless Jason Turner and Kate Gregory talks show. Alas, in C++, every best practice has a twist, such as “const everything except member variables.”

const member variables disables assignment and move semantics for a class. For assignments, it makes sense, since how can you assign something to a constant? For move semantics, even though technically copy is a valid move implementation, the type system cannot guarantee that the after-move state remains the same.

“What is the big deal? I already said that I don’t want to mutate the fields ever.” you may ask.

Except that swap uses both assignment and move semantics. Without move operations, every move fallback to a copy. The lack of assignment is more severe, as it makes swap fail to compile:

struct BadImmutablePoint {
    const int x = 0;
    const int y = 0;
};

int main() {
  BadImmutablePoint p1;
  BadImmutablePoint p2 {42, 55};
  std::swap(p1, p2); // Error
}

That also means no to all STL facilities that use assignments internally. For example, std::sort:

std::vector<BadImmutablePoint> points;
// Sort by x-axis
std::ranges::sort(points, {}, &BadImmutablePoint::x); // Error

But I don’t want to mutate the member variable!

The best thing you can do in C++ is to make the member variable private and only expose the getter. Access control still doesn’t prevent the class internals from modifying the members, but at least now everything outside the class can’t.

class ImmutablePoint {
    int x_ = 0;
    int y_ = 0;

public:
    constexpr ImmutablePoint() = default;
    constexpr ImmutablePoint(int x, int y) : x_{x}, y_{y} {}
    [[nodiscard]] constexpr auto x() const -> int { return x_; }
    [[nodiscard]] constexpr auto y() const -> int { return y_; }
};

int main() {
    std::vector<ImmutablePoint> points;
    ...
    std::ranges::sort(points, {}, &ImmutablePoint::x); // Ok
}

It is quite a bit of boilerplate. And to be honest, I will stick with aggregate with none-constant fields in this particular case. When you create a point variable, you can still mark the whole point as const:

struct Point {
    int x = 0;
    int y = 0;
};

const Point immutable_point {42, 55};

If you want to get really fancy, you can even create a small template to automate the process of only exposing getters. Though I myself will certainly not go this far.

template <typename T>
class const_wrapper {
    T val_;
public:
    constexpr const_wrapper(const T& val) : val_{val} {}
    constexpr const_wrapper(T&& val) : val_{std::move(val)} {}

    [[nodiscard]] constexpr auto get() const -> const T& { return val_; }
    [[nodiscard]] constexpr operator T() const { return val_; }
};

Then you can use this template as following:

struct ImmutablePoint {
    const_wrapper<int> x = 0;
    const_wrapper<int> y = 0;
};

int main() {
    std::vector<ImmutablePoint> points;
    ...
    std::ranges::sort(points, {}, &ImmutablePoint::x); // Ok
}

Reference member variables

Unlike pointers or “references” in a lot of other programming languages such as Java and Python, C++ references cannot rebind. Hence, we have a situation very similar to const members. A good analogy of references is a const pointer that cannot be null. For example, the below struct subjects to the same problem of the struct with const fields.

struct BadImmutableTriangle {
    const ImmutablePoint& a;
    const ImmutablePoint& b;
    const ImmutablePoint& c;
};

Like the solutions for const data members, instead of storing a reference data member, we can store a pointer member and only expose a reference getter.

class ImmutableTriangle {
    const ImmutablePoint* a_;
    const ImmutablePoint* b_;
    const ImmutablePoint* c_;

public:
    // No default constructor
    constexpr ImmutableTriangle(
        const ImmutablePoint& a,
        const ImmutablePoint& b,
        const ImmutablePoint& c)
        : a_{&a}, b_{&b}, c_{&c} {}

    [[nodiscard]] constexpr auto a() const -> const ImmutablePoint& { return *a_; }
    [[nodiscard]] constexpr auto b() const -> const ImmutablePoint& { return *b_; }
    [[nodiscard]] constexpr auto c() const -> const ImmutablePoint& { return *c_; }
};

The C++ standard library ships a std::reference_wrapper helper template and it function a lot like our const_wrapper above.

struct ImmutableTriangle {
    std::reference_wrapper<const ImmutablePoint> a;
    std::reference_wrapper<const ImmutablePoint> b;
    std::reference_wrapper<const ImmutablePoint> c;
};

std::reference_wrapper is more useful than my const_wrapper. As it is essential when we try to store something in the container while still maintains reference semantics:

std::vector<ImmutablePoint&> triangles1; // Error
std::vector<std::reference_wrapper<ImmutablePoint>> triangles2; // Ok
std::vector<ImmutablePoint*> triangles3; // Ok， with caveat

The code std::ranges::sort(triangles2); sorts triangles2 according to value comparisons. And it will fail to compile if you haven’t define relevant comparison operators. This is the desirable behavior, as there are no clear default ordering for triangles. On the other hand, std::ranges::sort(triangles3) compiles, but it sorts by the addresses of pointers. And this kind of nondetermistic behavior is undesirable.

Where `const` or reference member variables can still be useful

In some cases, you already disabled the assignment and move operations, or you need to write your own anyway. One of the primary examples is inheritance hierarchies. And in those cases, it is fine to use const or reference member variables.

Another use case of const or reference members is in local function objects, where you don’t care about assignment behavior. For example, variables captured by reference in a lambda expression are desugared into reference member variables.

Conclusion

C++, at its core, is an imperative language built on C heritage, and const and references are afterthought of the language. Also, The core language mechanisms heavily rely on assignment. Like it or not, when writing C++ classes, restricting user’s freedom to mutate member variables is not well supported.

Zero is the Devil: Common ways to construct bogus proofs

Sun, 10 May 2020 00:00:00 GMT

It is easy to make mistakes when conducting mathematical proofs. Nevertheless, you can find some recurring error patterns in those proofs. And some of the most common reasons are related to the innocuous-looking number zero.

Division-by-zero fun

Let’s look at the following “proof” of :

What is wrong here? We cancel both side of the equation by , but our premise includes , so we have a division-by-zero problem.

Generally, performing cancellation without a zero-check is a terrible idea and should be avoided.

Sets with zero elements

Ok, here is another stupid “proof” of that “all objects are the same.” We will assume that objects are countable.

Proof:

Let be the set of all objects. And let the property mean that all subsets of of size at most contain the same same objects. Formally:

where is the power set of the set , which is defined by all subsets of , and means the cardinality (elements count) of .

We want to prove that . And we will prove that by mathematical induction on .

Base case ():

This is trivial as the singleton set of object can only contain the same object.

Inductive cases:

We treat as our inductive hypothesis, and we need to prove . Without the loss of generality, pick an arbitrary set such that . Pick two objects , and let’s show . Let and . Since , we know that and by the inductive hypothesis. Pick an arbitrary object . We get because of and . Similarly, . Thus, , which proves the inductive steps and the “theorem” .

Again the mistake here is related to zero. can well be zero, so we cannot just “pick” an element from it.

If you are from a more programming background, it is no coincidence that dividing by zero or getting an element from a collection of zero-elements will cause horrible run-time errors.

I hope you have fun reading this post, just as me having fun writing it.

The surprising codegen impact of noexcept

Mon, 02 Mar 2020 00:00:00 GMT

Would spamming the noexcept keyword make your code faster? Sometimes. But not always. Consider the following snippet of code:

int g();

int f() {
  return g();
}

I intentionally do not define g in this translation unit since otherwise, the compiler will be too smart and inline everything. Nevertheless, all the major C++ compilers can figure out that f only contains a tail-call to g and generate codes like this:

f():
        jmp     g()

Now lets consider the following code:

int g();

int f() noexcept {
  return g();
}

Since the compilers have no idea if g would throw or not, they are forced to generate codes that invoke std::terminate in case bad things happened. Here is the result codegen from various compilers:

msvc

$ip2state$int f(void) DB 02H
        DB      08H
        DB      00H
$cppxdata$int f(void) DB 060H
        DD      imagerel $ip2state$int f(void)

int f(void) PROC                                      ; f, COMDAT
$LN5:
        sub     rsp, 40                             ; 00000028H
        call    int g(void)                         ; g
        npad    1
        add     rsp, 40                             ; 00000028H
        ret     0
int f(void) ENDP                                      ; f

gcc

f():
        sub     rsp, 8
        call    g()
        add     rsp, 8
        ret

clang

f():
        push    rax
        call    g()
        pop     rcx
        ret
        mov     rdi, rax
        call    __clang_call_terminate
__clang_call_terminate:
        push    rax
        call    __cxa_begin_catch
        call    std::terminate()

How to deal with C functions?

Now we know that noexcept can cause overhead if we call a non-noexcept function inside, how do we deal with functions that will not throw but are not mark as noexcept? Fortunately, the venerable Hana Dusíková came up with a clever solution:

Did you ever get an suboptimal code, because you were calling external C function in your noexcept code?

Suffer no more: https://compiler-explorer.com/z/zyyAeW
— Hana Dusíková 🍊 (@hankadusikova) June 27, 2020

You can mark the noexcept_cast function force inline by compiler-specific extensions so it will not decrease performance in debug mode.

Conclusion

Don’t spam noexcept if you don’t have a project-wise “no exception” policy. And be especially careful with higher-order functions that may invoke user-defined functions. All in all, noexcept is a part of the type system and the contract of your API. Only add noexcept to function that you want to guarantee not to throw.

Concepts in Programming Languages, Part II: Statics

Mon, 02 Mar 2020 00:00:00 GMT

What are the statics of a programming language? Most programming languages exhibit a phase distinction between static and dynamic phase of processing. People sometime loosey say static of a language happened at “compile-time,” and dynamic of a language occurred at “run-time.” The static phase of a language contains lexing, parsing, and in the case of static-typed languages, type-checking, and name resolution. And the dynamic phase consists of the execution of a program. We will only focus on static-typed languages in this post since the statics of dynamically-typed languages are trivial.

In the static phase, we consider what the valid operations of a program are. We construct a set of rules on the typing judgments to state if an expression is well-formed for certain types.

Static of a small expression language

Let’s consider a pretty dull expression-oriented language below.

The above grammar defined two sorts, and . A type in this language can either be number or string. Now it’s time to define the inference rules for the derivation of each operation. First, the type of literals are quite obvious

The we can define typing for operations of the language:

If both the left-hand side and the right-hand side have the type , the expression have the type . Otherwise, is ill-formed.

We can use the similar way to define the rest of the operations:

With those basic rules, we can state that in our language, is well formed and is a type error.

Typing context

So far, our little language does not have variables. In real programming languages, the type system needs to consider the typing context. Let’s introduce variables and let binding into our language:

Now we can define variable in our languages such as . In a concrete syntax, the expression looks like

let x = 1;
x + 2 // evaluates to 3

Whether make sense depends on whether the variable x is defined in the surrounding context, but our inference rule for cannot catch that yet.

What you can do is to introduce another concept called typing context , which is a mapping from variables to types.

We inductively define as either an empty set or the extension of another typing context with one mapping from a variable to a type.

Then you need to change the judgment form of typing to , which means “under typing context , the type of expression is .”

For most of the rules, nothing exciting happens besides the additional typing context in all judgments.

For variable name resolution, we need to lookup in the typing context.

For let bindings, we can extend the typing context and check the inference rules recursively.

If you want to prevent name shadowing, you can change the rule a little bit.

Concepts in Programming Languages, Part I: Judgements and Inference Rules

Sun, 26 Jan 2020 00:00:00 GMT

From a layperson’s perspective, the field of programming language research is full of jargon, greek letters, and weird symbols. On the one hand, Those common parlances make the programming language papers concise. On the other hand, you need not only mathematical maturity but also domain knowledge to understand them.

Since I am taking a Fundamentals of Programming Languages course, I want to share the key concepts I learned in a series of blog posts. And I hope to write them in a “mortal-understandable” way to unravel the mysterious field of programming languages.

I want to thank Professor Chang for offering this fantastic course, and my classmates for creating a vibrant discussion environment. I also need to make a disclaimer that many ideas of those posts come from the classroom. I would cite writing texts when apply, but it is impossible to cite in class discussions. Of course, all errors are my own, and please contact me for anything wrong.

A lot of the mathematical concepts in the programming language field comes from the branch of propositional logic. Thus, this first post focuses on the formal language of Judgements, and Inference Rules.

Judgements

A judgment is a statement or an assertion on a given abstract syntax tree. Below are some standard notations we use for the judgments ¹:

Notice in the above examples such as , is an unknown variable. We call those judgement forms And we can plug in actual values into the variables of judgement forms to get a judgement:

As we can see, judgments can either be true or false. You can consider it is a function application that returns a bool.

Inference Rules

Inference rules are a logic form that takes premises and returns conclusions. They generally have the standard form of the following:

You can read them as “if all the premises are satisfied, then the conclusion.”

Let’s inductively define the natural numbers by the inference rules.

In this inference rule, we state that a natural number is either zero or a succession of another natural number. A rule without any premise, such as the first one, is called an axiom.

Because using inference rule to describe syntax is verbose, a common way to describe syntax is by grammar notation like the Backus normal form (BNF). A grammar of a programming language is a set of inductively defined terms. For example, for natural numbers, we can describe them as

However, inference rules can express much more than syntax. For example, let’s define the semantics of the operator of the natural number:

We can define more operations, such as and , by the inference rule. Let’s look at another example, a singly linked-list of natural numbers:

This grammar means that a is either or a -cell of natural number and another . A is an empty list, and a is a “node” of the singly linked-list that contains an individual element and points to a sub-list.

Now we can start to define operations on with inference rules. For example, we can define a head function that gets the first element of the list:

Partial Function, Total Function, and Error handling

Notice our version of head is a partial function, which means not all the list has a mapping to a natural number through head. In this particular case, we have not defined the meaning of head(Nil). We have several choices of dealing with such partial functions, one is to leave the operation as undefined. This approach is what the C programming language takes, and it is the best for optimization, though it impairs the type safety.

Another approach is to make such a function call “error” or “exception” such as

And a third approach is to transform this operation to a total function:

A lot of the modern programming language becomes eclectic on error-handling strategies. For example, the Rust programming language offers all three approaches in different contexts. For certain operations, it not only offers a default “safe” version either with the second approach (panic) or the third approach (Option and Result), but also an “unsafe” version with the first approach.

Derivation

You can easily create nonsense such as , so how to prove a judgment is correct? To prove a judgment, you write derivation (also called derivation tree or proof tree).

A derivation always starts from axioms and ends at the judgment we want to prove. For each step, we apply an inference rule to the previous judgment (s).

For example, to prove “1 + 1 = 2” with our definition of nat, we have

Reading from bottom to top, you can find that the derivation is analogous of the execution of a program:

Succ(Zero) + Succ(Zero)
= Zero + Succ(Succ(Zero))
= Succ(Succ(Zero))

We can trace the execution of the + operation by substitution easily because it is a pure function. In other words, + is deterministic and side-effect free, at least at the level that we concern.

Analogy to programming

All of the mathematical notations that we talked about have programming counterparts. Below is a table comparison between math notation and programming:

Mathematical Notation	Implementation
Judgement form	A function signature of a function that returns `bool`
Judgement	Function application
Inference Rules	Function body
Derivation	Evaluation/Execution

Let’s say that we have the judgement form , we can write it as a function signature

val head : (l: nat list, e: option(nat)) -> bool

The inference rule of head can be view as the function body.

let head (l : nat list, e: option(nat)) =
  match l with
  | [] -> false
  | hd::_ -> hd = e

And the judgement such as is analogous to function application such as

head Cons(Succ(Zero), Nil) Succ(Zero)  (*true*)

I use OCaml syntax as an example, but it applies to any programming languages. The advantage of an ML-family language such as OCaml in my use case is there excellent support for inductively defined types such as nat and list.

Notice that the literal translation from math generates very inefficient implementations. In an actual implementation, You would probably write the head function as:

let head (l : nat list) =
  match l with
  | [] -> None
  | hd::_ -> Some(hd)

Nevertheless, it is still useful conceptually to see the connection between the mathematical notation and the actual programming.

”Type error” in judgements

It is easy to make “type error” when writing judgments and inference rules. For example, the following inference rule is incorrect as + is not a natural number, so we cannot put it inside a Succ.

It is equally easy to make this kind of mistake when coding a tree-walking interpreter by mixing the abstract syntax and the values. If you are using a statically-typed language, the type-checker will catch those kinds of errors. On the contrary, when writing judgment and inference rules, you are on your own, so building a mental “type checker” helps tremendously in writing judgments correctly.

Summary

Judgments and inference rules are the fundamental building block of the formal definition of programming languages, and it is hard to find a programming language paper without them. Thus, it is crucial to understand how to read and write in such notations.

Footnotes

Robert Harper. Practical Foundations for Programming Languages. Cambridge University Press, Cambridge, England, Second edition, 2016. ↩

Const Correctness Issue of std::function

Mon, 30 Dec 2019 00:00:00 GMT

The const type qualifier is one of the jewels of the C++ language design. Surrounding by this feature, we devise the “const correctness” practice to prevent const objects from getting mutated. The const correctness rule is straight-forward to follow for implementation of the most classes, but it is harder to heed for classes with type erasure. Unfortunately, the standard library type std::function is implemented by type erasure; and due to short-sightedness, it becomes one of the ill-behaved citizens that doesn’t follow the const-correctness rule.

The Problem

std::function has one const member operator(), yet it can mutate the underlying function. For example,

const std::function<int()> f {[x=0]() mutable { return ++x; }};
f(); // returns 1
f(); // returns 2

The Document N4348¹ first formalized this concern. It states that

This violates not only basic tenets of const-correctness, but also the data race avoidance guarantees in [res.on.data.races]/p3, which states that “A C++ standard library function shall not directly or indirectly modify objects accessible by threads other than the current thread unless the objects are accessed directly or indirectly via the function’s non-const arguments, including this”.

The Fix

Implementations of a function-like class should have separate specializations for const and non-const.

template<class Sig> class function; // not defined

template<class R, class... Args>
  class function<R(Args...)>;

template<class R, class... Args>
  class function<R(Args...) const>;

operator() of the const specialization should be annotated as const, but the constructor of the const specialization would not accept mutable function objects.

function<int() const> f1 {[x=0]() { return x; }};
f1() // ok;

function<int() const> f2 {[x=0]() mutable { return ++x; }}; // Does not compile

On the other hand, operator() of the non-const specialization would not have const type signature, so you cannot invoke the const version of such functions at all:

function<int()> f1 {[x=0]() mutable { return ++x; }};
f1(); // ok

const function<int()> f2 {[x=0]() mutable { return ++x; }};
f2(); // Does not compile

The Future

I don’t expect std::function itself to have any change that breaks backward-compatibility. As of the time of this writing (December 2019), my bet is on the proposed std::unique_function ², which is a drop-in replacement of std::function that fixes the const-correctness bug among other features. Once we have an alternative in standard, std::function can be deprecated just like std::auto_ptr. In the meantime, we can always implement unique_function on our own, and I have a small library to implement that on Github.

Footnotes

Make Impossible State Unrepresentable, in C++

Sat, 26 Oct 2019 00:00:00 GMT

At CppCon 2019, I gave a lightning talk at called Make Impossible State Unrepresentable. Due to the nature of a 5 minutes lightning talk, it was handwavy, and I cut a lot of prepared contents to fit the time. This post is a deeper dive into the topic with more detailed explanations and examples.

The same practice in typed-functional programming communities inspires this topic. However, I do not consider this theme too “functional,” and it can certainly be applied to C++ or any other programming languages with a type system. The topic also has a strong relationship with “strong typing.”

The motivation

Consider the following code snippet that I copied from a tutorial website for the Vulkan Graphics API. Apparently, many people directly copy this tutorial to their codebase.

In the snippet, we have a struct of indices for different queues, and we first query the indices and use them to refer to those queues later.

struct QueueFamilyIndices {
    std::optional<uint32_t> graphics;
    std::optional<uint32_t> present;

    bool isComplete() const {
        return graphics.has_value()
        && present.has_value();
    }
};

QueueFamilyIndices findQueueFamilies(/*...*/) {
  // ...
  QueueFamilyIndices indices;
  for (const auto& queue: queues) {
    if (/* queue i support graphics */) {
        indices.graphics = i;
    }

    if (/* queue i support present */) {
        indices.present = i;
    }

    if (indices.isComplete()) {
        break;
    }
  }
  return indices;
}

In this particular case, the function findQueueFamilies is the only place where we can have uninitialized queue indices, so why no get rid of all the optionals in the struct:

struct QueueFamilyIndices {
    uint32_t graphics;
    uint32_t present;
};

std::optional<QueueFamilyIndices> findQueueFamilies(/*...*/) {
  // ...
  std::optional<uint32_t> graphicsFamily = std::nullopt;
  std::optional<uint32_t> presentFamily = std::nullopt;

  for (const auto& queue: queues) {
    if (/* queue i support graphics */) {
        graphicsFamily = i;
    }

    if (/* queue i support present */) {
        presentFamily = i;
    }

    if (graphicsFamily && presentFamily) {
        return QueueFamilyIndices{*graphicsFamily, *presentFamily};
    }
  }

  return std::nullopt;
}

The memory footprint of QueueFamilyIndices gets reduced from 16 bytes to 8 bytes. The reason is partly that we no longer store unnecessary information, and partly because of the inefficient alignments of multiple std::optional from the first struct.

struct A {
  optional<uint32_t> i;
  optional<uint32_t> j;
};

struct B {
  bool has_i;
  bool has_j;
  uint32_t i;
  uint32_t j;
};

In the above snippet, the sizeof(A) is 16 bytes while the sizeof(B) is only 12 bytes.

We also reduced the need for assertions or runtime checking. Notice the isComplete function goes away for the second case, as we don’t need to call this logic multiple times. In the first case, we would no be that confident, since we can have a bug that left QueueFamilyIndices uninitialized.

Algebraic Data Types

The above example demonstrates the usage of algebraic sum types (optional or variant), albeit in an inefficient way at first. Those types belong to the new addition of the “vocabulary types” in C++17, though they have a long history in other programming languages and third-party C++ libraries. The name “sum type” comes from the cardinality of the set of the possible state of those types. Similarly, the more familiar struct or tuple are called “product type” because their cardinality is the product of the cardinality of all of their fields. Sum types are sometimes also called “tagged union” or “variant type”.

Algebraic sum type has an advantage on building state machines. A textbook example of such use case is network connection:

struct Connection {
  struct Closed {};
  struct Connecting {
      IP ip;
  };
  struct Connected {
      IP ip;
      Id id;
  };

  std::variant<Closed, Connecting, Connected> state;
};

This implementation faithfully represents the data used by each state. For example, it doesn’t make sense to store an IP address for Connection is it is Closed.

Inheritance Hierarchy vs. Sum Type

Both sum types and inheritance are used for runtime polymorphism. In other words, only use them when you need runtime polymorphism. Sum types add one major constraint over inheritance. Inheritance is open to extension, while sum types are closed. The constraint is not necessarily a bad thing. For example, because as the compiler knows maximum size information statically, it can put the whole variant object on the stack.

In theory, dispatch over variant can be faster than the virtual dispatch, though none of the current implementations of std::visit are faster than virtual. However, in a potential future C++ version with language variant and pattern matching, there is evidence ¹ that variant would provide an advantage.

However, the “open to extension” property of inheritance does prove useful from time to time. For example, consider that you are working on a compiler, you may represent your expression in a traditional OO-way like this:

struct Expr { ... };

struct ConstExpr : Expr { ... };
struct LambdaExpr : Expr { ... };
struct ApplyExpr : Expr { ... };

Adding compilation errors is as simple as adding derived classes like SyntaxErrorExpr and TypeErrorExpr into the corresponding stages, and those errors are completely hidden between stages. By contrast, with sum type, one option is to create a mess like:

using Expr = std::variant<ConstExpr, LambdaExpr, ApplyExpr,
                          SyntaxErrorExpr, TypeErrorExpr>;

This approach forces us to handle TypeErrorExpr in the parser. Another option is to pay extra overhead and to wrap every Expr into an expected. Both alternatives are less than ideal, and the problem becomes even bigger if the abstract syntax tree becomes more complex and contains a hierarchy.

Another type of polymorphism is row polymorphism. Row polymorphism only considers features and structures of a type. Like inheritance, row polymorphism is also open to extension, so it shares many advantages as inheritance. Row polymorphism is arguably a better alternative to virtual inheritance ²³⁴⁵⁶. Though row polymorphism is exactly what C++ concept achieves, C++ lacks support build-in support of it for runtime polymorphism. Go and Typescript interfaces and Rust trait are examples of such language features. In C++, runtime row polymorphism can be implemented by doing type-erasure manually.

Data Modeling

All of the above discussions lead to data modeling — defining and analyzing data requirements and define data models accordingly. Both data-oriented design and functional programming people like to talk about Data modeling.

From the point of view of an object-oriented developer, data modeling is similar to class design. Classes often work as self-contained entities that know how to do operations on themselves. However, such an approach requires packing all “logical related” data into one structure, and it often does not make sense. For example, below is how pbrt-v3 implements triangles:

struct TriangleMesh
{
  std::vector<int> vertexIndices;
  std::unique_ptr<Point3f[]> p;
  // other data
};

class Triangle
{
public:
  // Triangle operations

private:
  std::shared_ptr<TriangleMesh> mesh; // back pointer
  const int *v; // A pointer to vertex indices
};

Each Triangle need to store a back pointer to operate on itself. Moreover, there is no guarantee that the pointer v is not dangled. In this particular example, programmers make sure that v always points to memory managed by TriangleMesh.

If we abandon the idea that triangles must know how to operates on themselves, then the triangles become just indices to the vertices:

struct Triangle {
  std::uint32_t first;
  std::uint32_t second;
  std::uint32_t third;
};

struct TriangleMesh
{
  // Triangle operations

  std::vector<Triangle> triangles;
  std::unique_ptr<Point3f[]> p;
  // other data
};

Since we no longer need to worry about the dangling of indices, we don’t need reference counting anymore.

Transform the API

Sometimes following the guideline of better data modeling means changing the APIs. Such a change would make the API easier to use and harder to misuse, so it is better to start early than later.

Below is another example from graphics programming where we have commands to submit to GPU. We don’t directly push the data to GPU, but instead, cache them in a CommandBuffer object that we can batch submit later.

struct CommandBuffer {
  CommandBuffer& push_draw_command(uint32_t count, uint32_t vertex_offset,
                                   uint32_t instance_count);
  CommandBuffer& push_draw_indirect_command(void* indirect);
  CommandBuffer& push_bind_graphics_pipeline_command(GraphicsPipelineHandle pipeline);

  // ...
};

This graphics API directly maps to lower-level APIs like Vulkan and DirectX12 nicely and is very flexible. There is one huge drawback, nevertheless. The graphics pipeline object encapsulates all the logic of drawing, like how to interpret data we sent to the GPU. However, in the current API, you can freely start to draw objects without bind to a graphics pipeline:

CommandBuffer buffer;
buffer.push_draw_command(count, 0, 1);
queue.submit(buffer);

One naive forward modification is putting the reference of the graphics pipeline inside each command. Nonetheless, we are paying an extra overhead here as the need to check if the graphics pipeline stays the same. If it is, we don’t need to rebind the pipeline again, since rebinding a graphics pipeline can be a costly operation in GPU. Another optimization for this model is to add sorting against the graphics pipeline on top of each command. Such optimization, however, also introduces additional overhead.

struct CommandBuffer {
  CommandBuffer& push_draw_command(GraphicsPipelineHandle pipeline, uint32_t count,
                                   uint32_t vertex_offset, uint32_t instance_count);
  CommandBuffer& push_draw_indirect_command(GraphicsPipelineHandle pipeline,
                                            void* indirect);

  // ...
};

A better fix is to introduce another structure, DrawingCommandbuffer, that contains a graphics pipeline and draw commands. In this model, there is no need for checking or sorting, and we can quickly build DrawingCommandbuffer in parallel.

struct DrawingCommandbuffer {
  DrawingCommandbuffer(GraphicsPipelineHandle pipeline);

  DrawingCommandbuffer& push_draw_command(uint32_t count, uint32_t vertex_offset,
                                   uint32_t instance_count);
  DrawingCommandbuffer& push_draw_indirect_command(void* indirect);
};

struct CommandBuffer {
  void push_drawing_commands(DrawingCommandBuffer buffer);
};

Note that we can implement DrawingCommandbuffer in terms of Secondary Command Buffers of Vulkan, but there are no restrictions on how it must be implemented. Thus, implementations of different lower-level graphics APIs can use completely different approaches.

Limitations

Not all invariant can be checked at compile-time, and that is why many programming languages support contract or at least runtime assertion. However, even counting all the “compile-time known state,” there are limitations of applying “make impossible state unrepresentable” in C++. Some of them are due to the design of the C++ type system, and others are due to the performance requirements for C++ applications faces.

The curious case of Move semantics

I love C++11 move semantics. However, despite move semantics solving a lot of problems, it opens a hole in the C++ type system. Consider a class that wraps resource with underlying C-style API. In the C++98 area, we achieved the perfect RAII since the resource’ lifetime is tied with the lifetime of the object.

class Window {
  // ...

private:
  // Would never be nullptr
  GLFWwindow* window;

  Window(const Window& other);
  Window& operator=(const Window& other);
}

We introduced move semantics to make it movable. However, to enable move semantics for our resource handle, we created a pointer-like object. The reason is that the after move states must be valid; to have a valid after-move state, we are forced to represent the empty state in our class. That is why we have unique_ptr but no unique_reference in the C++ standard library. And it is also partly why people repeatedly propose destructive move.

class Window {
  // ...

  Window(Window&& other) noexcept : window{other.window} {
    other.window = nullptr;
  }

private:
  GLFWwindow* window;
}

Conclusion

Utilizing the static type system well, we can eradicate the possibility of runtime invariant violations in a group of cases. This approach decreases the possibility of insane debugging sessions and the need for aggressive assertions. It also helps testing because we don’t have to test what a static type system guaranteed. Moreover, we can see a performance gain sometimes by thinking about how to model data more carefully.

Footnotes

We are defining assignment operators wrong.

Mon, 14 Oct 2019 00:00:00 GMT

Update: Apparently there is a WG21 paper on this subject that goes in much more detailed than my post. I am surprised that I missed his CppCon talk on this topic and come into the silimar conclusion.

One principle of C++ operator overloading is that the behavior of overloaded operators should be similar to the counterparts on fundamental types. For the most part, we are doing a decent job. However, the way we define assignment operators leaves some surprise.

Consider the following code snippet:

1 = 2; // error: lvalue required as left operand of assignment

It is complete nonsense in most of the programming languages. And indeed, no compilers are happy about it,

However, for a class type, it is perfectly fine to assign to a temporary:

struct S {};

int main() {
  S{} = S{};
}

The reason is that the type signature of the assignment operators, whether if they are compiler-generated or if we define manually, does not exclude r-value types:

struct S {
  // Perfectly happy with `*this` being both lvalue or rvalue
  auto operator=(const S& other) -> S&;
  auto operator=(S&& other) -> S&;
};

And an easy fix is only to define the lvalue reference overload of assignment:

struct S {
  auto operator=(const S& other) & -> S&;
  auto operator=(S& other) & -> S&;
};

int main() {
  S{} = S{};
}

In this case, all three major compilers created a somewhat mystical error message, just like what usually happens when overload resolution fails, but at least it will not compile.

Does this issue even matters?

To me, this concern is more of a theoretical nuisance than a serious problem. I can’t picture any seasoned programmers who inadvertently assigning to an rvalue. It has the potential to be a problem to absolute beginners if they haven’t touch any programming languages before. It can also confuse beginners when they write a single equal when they want double equals. If they follow the best practice of declaring as much as const as possible, then the left-hand side of an assignment will be either a const value or a temporary. And such error can be caught by making the assignments l-value reference qualified.

It is still a good idea to follow rule-of-zero and do not touch any assignment operators. However, when you do need to define assignments, consider making only the lvalue reference overload. If C++ does get something like the epoch, then we can potentially add reference qualifiers to assignment operators of standard library types, for example, std::string.

CppCon 2019 Trip Report

Sun, 22 Sep 2019 00:00:00 GMT

What a week we had! CppCon 2019 is by far the best CppCon that I’ve ever attended. There are contents that interest me on every time slot, and for a lot of time there are conflict so that it is hard to decide which talk to go to.

Pre and post-conference classes

Arthur O’Dwyer’s Standard Library From Scratch teaches us the implementations of type-erased containers (any and function), synchronization primitives, smart pointers, and a bunch of meta-programming utilities. This course makes me more confident about type erasure, small-object optimization, and meta-programming.
Gordon Brown and Micheal Wong’s Parallelism in Modern C++: From CPU to GPU talks about general parallel programming principles and SYCL programming. I didn’t have much experience in GPGPU and never touched SYCL before, but I find that many concepts maps nicely to the Vulkan Graphics API.

The keynotes

CppCon this year have one keynote for each day, and all the keynotes are high quality.

Bjarne Stroustrup’s C++20: C++ at 40 [video] talks about the current status of C++ from the perspective of its creator. Nothing substantially surprising is in this talk, but the combination of C++ features like modules and concept has already completely transformed this language into a new height. Bjarne also talked about his vision of future C++.
Andrei Alexandrescu’s Speed Is Found In The Minds of People [video] is both entertaining and inspiring. It makes me rethink about algorithms and optimization.
Ben Smith - Applied WebAssembly: Compiling and Running C++ in Your Web Browser [video]. Interning in a company where we have a web assembly product using the C++ codebase, I am delighted that people are spreading this practice.
Sean Parent’s Better Code: Relationships [video] continues his “Better Code” series. This time he was talking about theories of relationships between objects and how they guide us to architect software.
Herb Sutter’s De-fragmenting C++: Making Exceptions and RTTI More Affordable and Usable [video] naturally grab everyone’s attention. A large part of the communities is not satisfied, which the current status of exceptions and RTTI, so Herb’s series of proposals will help tremendously. Herb gives the same talk in my user group in March.

Personal high light

There are so many great talks in this year’s CppCon, so I can only mention some of them that I attended and impressed me the most.

Bryce Lelbach’s The C++20 Synchronization Library [video] is probably the best concurrency talk I heard in CppCon this year. It went through not only C++20 synchronization primitives but how to use them to build a task system. I plan to watch it several times until absorbing all its content.
Alisdair Meredith and Pablo Halpern’s Getting Allocators out of our way [slides] proposed an interesting language extension to simplify the writing of allocator-aware classes on top of the current pmr model. The basic idea is that allocators are no longer a regular parameter, but a special parameter that we can optionally provide with a different syntax. The extension works like Scala’s implicit parameter, and it can have potential use to other structures like executors.
Jason Turner’s C++ Code Smell [slides] finally convinced me that const function parameters have an advantage with a very simple example, which I was doubtful when he talked about it last year.
Mathieu Ropert’s This Videogame Programmer Used the STL and You Will Never Guess What Happened Next [slides] demystifies some common myth against C++ standard library, including the common concern of “debugging performance.” It also explains when should you (not) use STL.

Matt Godbolt’s “Path Tracing Three Ways” [slides] implements a same primitive path tracer in three C++ styles— object-oriented, functional, and data-oriented design. He analyze the performance and compares their strengths and weaknesses. One interesting detour is that a naively designed data-oriented code without dynamic polymorphism can be even slower than its OO counterpart because of branch misprediction (which DOD tries to avoid). The fix he applied not only improved the data-oriented version but also significantly increase the speed of the functional version. One thing I wonder is that in the particular case of path tracing, how much performance advantage of data-oriented design can be preserved when adding acceleration data-structures.

My lighting talk

I gave a lightning talk on Wednesday night called Make impossible state unrepresentable inspired by the typed functional languages communities. In the lighting talk, I mentioned how to design data and types in C++ to leverage the static type system so that invariants breaking becomes impossible in some instances.

This talk is my first presentation to give in front of the public instead of a university or meetup setting. I was nervous, but I managed to finish it. I also found that it is extremely hard to fit content into five minutes, as I cut more than half of the original slides I prepared. Thank CppCon for giving me this opportunity, and thanks Phil Nash for organizing the lighting talks well!

Conclusion

As a student, attending a conference at school time always gives me immense pressure in term of school works. However, CppCon was and is always worthwhile. It is a pleasure to be surrounded by so many extraordinary people in the C++ communities, and “C++ heroes” that I usually can only see online. Thank everyone I met for being awesome for the whole week. I can’t wait to attend the CppCon and meet you all next year!

ACM Siggraph 2019 Trip Report

Wed, 07 Aug 2019 00:00:00 GMT

This year, several of the coworkers and I at Trimble SketchUp attended ACM Special Interest Group in Graphics (Siggraph) conference. It is my first time attending such a big gathering. The week is exciting, exhaustion, and also extremely rewarding for me.

This year the conference location is Los Angeles, so we had the chance to have a tour to the pier, taste different seafood, and watch the sunset. We also had nerdy jokes about the pier floor is just a displacement map, and the sunset can be rendered by some shader hack.

Ray Tracing on Sunday

The spotlight of this year’s Siggraph is still ray tracing after Nvidia announce their Geforce RTX GPUs with ray-tracing capacity a year ago.

As a ray-tracing fanatic, I am glad to see the technology I like becomes more and more popular. It is said that “ray tracing is not slow; it is the computers.” Fortunately, we are just entering this revolution that, for the first time, computers are fast enough to do serious ray tracing works in real-time. I spent the whole Sunday on Ray-tracing related sessions. The session on the morning is Are We Done With Ray Tracing? Spoiler alert, as you may expect, the answer is no. The area is still a warm bed of new researches. Further, with the advent of real-time ray-tracing, new challenges arose like denoising on images generated by very-low sample size, effectively updating of acceleration structures.

Different speakers had different vision of how fast the ray-tracing adoption will be. Morgan McGuire of Nvidia thinks that ray-tracing pipeline will become mainstream in real-time graphics in 5 years. By contrast, Colin Barré-Brisebois for EA is much more conservative, considering rasterization/ray-tracing hybrid rendering-pipeline will be the future for a long time. I am more aligned with the latter opinion because ray-tracing are still much more expensive, and the hybrid approaches are already producing amazing results. To be honest, as long as we do not adopt a full-blown path-tracing approach (which still have prohibitive cost for current large real-time applications), I don’t think produced graphics quality of single real-tracing pipeline or rasterization will have a big difference. However, ray-tracing may decrease maintainance gain, especially for small teams and projects, since a completely ray-tracing pipeline will drastically decrease the complexity of current beastly graphics pipeline. By contrast, AAA shops’ graphics pipeline will be more complicated because they need to support both hybrid ray-tracing and fallbacks. I attended Introduction to Real-Time Ray Tracing afternoon, which was on the same topic but covered more basic and detailed material, from Peter Shirley’s ray tracing introduction to how to write a simple DirectX ray-tracing program.

Monday: Advances in Real-Time Rendering, and Animated Shorts

My colleges and I spent most of the Monday attending “Advances in Real-Time Rendering in Games” part 1 and 2. It is astonishing how many crazy new methods in real-time rendering get developed, from strand-based hair rendering to ocean wave simulation. There are just too many goodies for me to justify them all.

The Electronic Theater at night was a fun event. We saw a lot of great works of animation artists this year. However, All of us felt that this year’s demos have overly depressing and emotional themes in general. There were excessively too many aminations focuses on the loneliness in an industrial society or the evil side of human nature.

Tuesday: Vulkan, Ray Tracing Roundtable

On Tuesday we went to Best Practices for Using and Contributing to the Vulkan Validation Layers and Vulkan SDK Update and Community Feedback from LunarG on Vulkan SDK. I am still very new to Vulkan, but I am impressed about how much work LunarG folks put into the SDK to make using Vulkan a better experience.

I also went to the Ray Tracing Roundtable organized by Eric Haines. People interested in ray tracing gathered in small groups and talked about news and advancement of ray tracing. It was an astounding experience that people like me could chat with heroes in the field face to face.

Wednesday and Thursday

I have an ambition of making the CU Computer Graphics Group a Siggraph chapter, so I went to ACM SIGGRAPH Chapters Fast Forward and Startup Meeting Wednesday morning. I then went to An Introduction to Physics-Based Animation afternoon, which compressed semester-worth materials into three and a half hours. On Thursday morning I went to Differentiable Graphics With Tensorflow 2.0. The idea of Differentiable Rendering sounds exciting, and it is always good to see applications of machine learning in graphics beyond denoising. Nevertheless, I felt that it is hard for me to come up with a useful use case for it. Maybe I need to delve into this technique more in the future.

Exhibition

Various companies have exhibitions and live demos in Siggraph. As with everything else, a lot of excitement around the exhibition is related to real-time ray-tracing. There were a lot of companies that demonstrated their motion capture techniques and streamed the results into a game engine. One of the particularly striking shops implemented a VR avatar that will always have eye contact with you after you move.

Conclusion: An inspiring year to learn Graphics

The conference itself is just five days, but it leaves me with year-worth materials to learn. I took notes on several new technologists and libraries to play and more than ten papers that I want to read. Also, due to time conflict, I can’t attend all the sessions that I am interested in. There are still several intriguing talks and workshops I want to watch afterward, including A Fast Forward through Ray Tracing Gems, Optimizing and Deploying Ray-Traced Dynamic Global Illumination, Open Problems in Real-Time Rendering, Path Tracing in Production, Ray Tracing Gems 1.1, and My Favorite Samples.

Intuition Behind X86 "lea" Instruction

Tue, 11 Jun 2019 00:00:00 GMT

During the last meeting of the North Denver C++ Meetup, some people mentioned that lea is more confusing than other instructions. lea is an acronym for “load effective address.” The usual explanation is “to put a memory address from the source into the destination.” The syntax of lea in the Intel Syntax is the following:

lea destination, source

For example, if you have an array points of struct Point:

struct Point
{
    int x;
    int y;
    int z;
};

The compiler may generate the following line for int x = points[i].y;

mov  eax, [rbx+rcx*4 + 4]

In this case, the register rbx points to the array points, rcx is the index variable i, and eax is the register that holds x. Similarly, for int* x = &points[i].y;, compilers can generate

lea  eax, [rbx+rcx*4 + 4]

However, besides using it for address operations, compilers seem to prefer using lea to other arithmetic instructions as well for efficiency reason. For example, int y = x * 5; may generate

lea  eax, [rdi + 4*rdi]

instead of the more intuitive version of

imul  eax, [rdi], 5

lea is, in my point of view, a process of pointer arithmetic sandwiched with casts. For the previous example, the equivalent c code is

int y = (int)(&((int*)x)[x]);

The above code first treats x as an int pointer ((int*)x), and then get address the x-th element of that pointer. That part is essentially the address [rdi + 4*rdi]. Next, it assigns the lower 32 bits of the address as an integer value to the destination.

I hope this example gives you some intuitive understanding about lea. Of course, no sane C programmer will write such kind of code by hand. The above code is not even conforming C++ for a good reason (C++ disallow casting from pointer to smaller type int). However, from a machine’s perspective, such kind of “reinterpret_cast” is essentially a no-op, and machine languages leverage that all the time.

When does a C++ temporary object die?

Thu, 28 Mar 2019 00:00:00 GMT

A lot of operations of C++ require temporary values. Using them before their destruction is imperative. However, not all C++ programmers I met have a solid understanding of when a temporary expire. This situation often leads to over-conservative estimations, which will not cause any harm. Nevertheless, sometimes it will cause programmers to assume guarantees that the language does not provide, which leads to insidious bugs.

One of the common scenarios such problem manifest is when we manipulate a string with std::string, but feed the result string back to an API that takes const char*. Consider the following code snippet:

[[nodiscard]] auto greet(const std::string& name) -> std::string {
    return "Hello, " + name + '!';
}

int main() {
  const std::string name{"Lesley Lai"};
  std::puts(greet(name).c_str()); // highlight-line
}

The C++ Standard guarantees it to work. The Standard mandates that all temporary objects get destroyed as the last step of evaluating of the full-expression that contains the point where the temporaries were created¹. “full expression” means an expression that is not sub-expression of other expressions.

A noteworthy exception of the rule is references. References can extend the lifetime of temporaries, but they will be a topic of another post.

In “The Design and Evolution of C++,” Bjarne discussed the early design decision of the lifetime of temporaries ². The book refers to an earlier paper that identified several alternative destruction points. For example, in the original CFront implementation of C++, temporaries are destroyed at the end of the blocks. This approach caused problems when creating large temporaries, and some programmers explicitly avoided the issue by wrapping statements in curly braces.

Another approach is to kill temporaries after the first use. An over-paranoid C++ programmer may suspect that the above code leads to undefined behavior. Having this thought may imply a subconscious assumption of this approach. I perceive this strategy more intuitive than the current way because of its consistency. With the current strategy, changing the above code a little bit will introduce undefined behavior:

[[nodiscard]] auto greet(const std::string& name) -> std::string {
    return "Hello, " + name + '!';
}

int main() {
  std::string name{"Lesley Lai"};
  // highlight-start
  const char* greeting = greet(name).c_str();
  std::puts(greeting);
  // highlight-end
}

In the above code, the destructor of the temporary returned by greet gets called after evaluating the full-expression. Thus, the pointer greeting gets dangled. I got bite by expired temporary strings when dealing with OpenGL shaders before. Such code may even appear to work for some cases ³ because of Small String Optimization. Anyway, if an undefined behavior guarantee to break the program in a certain way, it is no longer undefined.

Why C++ choose the current way? First, C++ cannot afford a garbage collection runtime, so “after the last usage” is out of the picture. Also, the current approach is far less error-prone to newbies than “after first use” strategy, while still performant without weird workarounds that “at the end of the block” implies.

Footnotes

cppreference: lifetime ↩
D&E, 6.3.2 ↩
for instance, in your unit tests ↩

C++ Lambda Tutorial

Mon, 25 Mar 2019 00:00:00 GMT

C++ lambda expression is a construct added to C++ back in C++11, and it continues to evolve in each version of the C++ standard. A core part of the language nowadays, lambda expressions enable programmers to express anonymous functions and closures in C++. This post describes what a lambda expression is, provides some basic usages, and outlines their benefits.

Basic Usage

Passing functions as a parameter to customize the behavior of functions is a common task in programming. For example, since the conception of standard algorithms library, a lot of the algorithms in the <algorithm> can take an invokable entity as a callback. However, before C++11, the only kinds of invokable entities in C++ are function pointers and function objects. Both of them require quite a bit of boilerplate, and this cumbersomeness even impedes the adaption of the standard algorithm library in practice.

In the meantime, lots of programming languages support features of anonymous functions. Before C++11, such features are mimicked by metaprogramming. For example, the Boost C++ library provided its boost.lambda library. Those metaprogramming hacks are slow to compile and some of the has performance implications at runtime; moreover, they require more boilerplate then one want. Thus, in C++11, lambda expressions are added as a language extension. As an example, the ISO C++ Standard shows usage of a lambda expression as a comparator of the sort algorithm: ¹

#include <algorithm>
#include <cmath>

void abssort(float* x, unsigned n) {
    std::sort(x, x + n,
        [](double a, double b) {
            return (std::abs(a) < std::abs(b));
        });
}

Inside the function abssort, we passed an instance of a lambda expression into std::sort as a comparator. We can write a normal function to achieve the same purpose:

#include <algorithm>
#include <cmath>

bool abs_less(double a, double b) {
    return (std::abs(a) < std::abs(b));
}

void abssort(float* x, unsigned n) {
    std::sort(x, x + n, abs_less);
}

If you are familiar with lambda expressions in other languages, everything should make sense except the mysterious [] syntax. And that is our next topic.

Captures

The above example shows the basic usage of lambda expressions, but lambda expressions can do more. The main difference between a lambda expression and a regular function is that it can “capture” state, and then we can use the captured value inside the lambda body. For example, the below function copies elements, which are above the threshold, from the old vector to the new vector.

// Get a new vector<int> with element above a certain number in the old vector
std::vector<int> filter_above(const std::vector<int>& v, int threshold) {
    std::vector<int> result;
    std::copy_if(
      std::begin(v), std::end(v),
      std::back_insert_iterator(result),
      [threshold](int x){return x > threshold;});
    return result;
}

// filter_above(std::vector<int>{0, 1, 2, 4, 8, 16, 32}, 5) == std::vector<int>{8, 16, 32}

The above code captures threshold by value. The [] construct is called a capture clause. There are two kinds of captures, capture by value or capture by reference ([&]). For example, [x, &y] - capture x by value and y by a reference. You can also have a default capture clause: [=] captures everything in the current environment by value and [&] captures everything by reference.

We call a function that stores an environment a closure; almost all modern programming languages support closures. However, in all languages that I know except C++, the capture lists are implicit. In those languages, a closure captures all the bindings from the current environment.

We can mimic the behaviors in those languages by capturing everything by reference ([&]); it only captures variables in the environment that the lambda uses. However, default capture can be dangerous in C++; if the lambda lives longer than the captured object, then dandling problems occur. For example, we can pass a callback to asynchronous functions and capture resources by reference.

auto greeter() {
    std::string name{"Lesley"};

    return std::async([&](){
        std::cout << "Hello " << name << '\n';
    });
}

The above code is undefined behavior since name may be destroyed when we execute the asynchronous operation. The rule of thumb is only to use default capture by reference when the lambda is short-lived. For example, when passing a lambda to STL algorithms.

The implicit capture strategy works in garbage-collected languages. Rust gets away with implicit capture because of its borrow checker. On the contrary, by requiring the programmer to be explicit about ownership, the C++ approach provides more flexibility than the counterparts in other programming languages.

Lambda expression under the hood

We discussed quite a lot of usage of lambda so far. However, curious readers may start to wonder, what exactly is a C++ lambda expression? Is it a primitive language construct like closures in functional languages? Before I talk about the internal of lambda, I will first talk about a construct date back to the C++98 era, function objects.

Some C++ programmers call the function objects “functors.” It is a misnomer that we should avoid. In category theory, a functor is a map between categories²” and satisfy specific “functor laws.”

Functional programming languages utilized this concept for their language constructs, though they too overloaded this terminology. In Standard ML and OCaml, a functor is a higher-order module. You can think of it as a meta-function that maps a module to another module. A more prevalent usage comes from Haskell and various inspired languages and libraries, where functor is a type class that defines mapping operation. The Haskell definition of a functor is also useful in C++. For example, the standard range adaptors can be considered functors that map ranges. Also, if the types std::optional andexpected support a “map” operations, then they become functors. Various libraries already implemented that, and some standard proposals are working in this direction ³.

Function Object

Function objects are normal objects that are able to be invoked. They are implemented by overloading a class’s operator() operator. Below is our abs_less example as a function object:

#include <algorithm>
#include <cmath>
class abs_less {
  bool operator()(double a, double b) {
    return (std::abs(a) < std::abs(b));
  }
};

void abssort(float* x, unsigned n) {
    std::sort(x, x + n, abs_less{});
}

Function objects are more flexible than regular functions because they can store data like ordinary objects. Let us implement the previous filter_above example with function object:

template <typename T>
class GreaterThan {
public:
  explicit GreaterThan(T threshold): threshold_{threshold} {
  }

  bool operator()(const T& other) noexcept {
    return other > threshold_;
  }

private:
  T threshold_;
};

std::vector<int> filter_above(const std::vector<int>& v, int threshold) {
    std::vector<int> result;
    std::copy_if(std::begin(v), std::end(v), std::back_insert_iterator(result), GreaterThan{threshold});
    return result;
}

Going back to lambda expressions

Lambda expressions in C++ are syntactic sugars of those classes with operator() defined. At runtime, those lambda expressions get evaluated into function objects. Through the amazing C++ Insights website, we can see a desugared version of our abssort example:

#include <algorithm>
#include <cmath>

void abssort(float * x, unsigned int n)
{

  class __lambda_6_9
  {
    public: inline /*constexpr */ bool operator()(float a, float b) const
    {
      return (std::abs(a) < std::abs(b));
    }

    ...
  };

  std::sort(x, x + n, __lambda_6_9{});
}

As you can see, a lambda expression creates a default constructed object of a local class. Thus, C++ lambda expressions can do a lot of stuff anonymous functions in other languages may not allow to do. For example, you can inherit from lambda and have mutable states from lambda. Though I haven’t found too much use for either of them.

The compilers generate the types of lambdas expressions; however, there is no way to use such types by their name through any standard means in a program. Nonetheless, type inferences and template works normally for those types. Also, we can use those types explicitly by decltype. Below is an example from the cppreference:

auto f = [](int a, int b) -> int
    {
        return a * b;
    };

decltype(f) g = f;

Such anonymous types are called “Voldemort’s types” in the world of C++ and the D programming language because they cannot be directly named, but codes can still use this type.

Capture with an initializer

Now you understand a lambda expression is a syntactic sugar over classes; you may expect lambda expressions to store arbitrary values, not just to capture the values from their local scope. Fortunately, in C++14, lambda expressions can introduce new variables in its body by the mean of capturing with an initializer⁴.

[x = 1]{ return x; /* 1 */ }

Move capture

Rust closures can take ownership of the values in the environment. C++ lambda expressions do not have special support for such move capture, but the generalized capture in the C++14 covers such use case:

// a unique_ptr is move-only
auto u = std::make_unique<some_type>(
  some, parameters
);
// move the unique_ptr into the lambda
go.run( [u=std::move(u)] {
  do_something_with(u);
});

Immediately Invoked Lambda Expression

You can invoke a lambda expressions at the same place where we construct them.

[]() { std::puts("Hello world!"); }(); // Same as what is inside the curly braces

In the world of Javascript, immediately invoked function expressions are all over the place since JavaScript programmers sometimes use them to introduce scopes. C++ does not need this kind of trickery. As a result, C++ programmers are more reluctant to use immediately invoked lambda. For example, in her talk during CppCon 2018, Kate Gregory concerns about the readability of the immediately invoked lambda expressions for people not familiar with this idiom.

Nevertheless, if you follow the best practice of declaring as more const values as possible, immediately invoked lambda expression does provide an advantage. Some objects require complex construction beyond the constructor’s capability. Mutations will only happen during the construction of objects. Once the construction is completed, the objects will never be modified again. If such construction is reusable, then writing builder classes or factory functions is a sensible choice. However, if such construction only happens once in the codebase, a lot of the people will drop the const qualifier instead. For example, consider that if you want to read several lines from stdin into a vector:

std::vector<std::string> lines;
for (std::string line;
     std::getline(std::cin, line);) {
    lines.push_back(line);
}

It seems no way to make lines constant since we need to modify it in the loop. Immediately invoked lambda expression solves this dilemma. With it, you can have both const and no boilerplates:

const auto lines = []{
    std::vector<std::string> lines;
    for (std::string line;
         std::getline(std::cin, line);) {
        lines.push_back(line);
    }
    return lines;
}();

Footnotes

Book Review: "Functional Programming in C++"

Fri, 22 Mar 2019 00:00:00 GMT

Functional Programming in C++ by Ivan Čukić is a new book about applying functional programming principles in C++. This book is for people who already have a decent understanding of C++. It is written in an idiomatic style that a C++ programmer should feel welcome.

If you just start to learn C++, this book may not be the best starting point. I will recommend A Tour of C++ instead. On the other hand, the book does not require any functional programming knowledge. The book spends its first six chapters to build basic functional programming concepts like pure functions, higher order functions, partial applications.

As a programmer already familiar with FP, the book does not provide too much major revelation to me. However, I still gain some small insight from each chapter. Though the implementation from this book may not be sophisticated and efficient, they demonstrate concepts pretty well because of their simplicity.

Chapter 6 discusses lazy evaluations and memoization. I feel like the book’s implementation for memoization is too inefficient to be useful, though I cannot come up with a better solution myself. I fear that a generic yet efficient solution is hard to find, and memoization should more be implemented in a case by case basis. Nonetheless, I particularly like the later part of lazy string concatenation by using expression templates.

Chapter 7 introduces ranges, which are merged into C++20 already. The introduction is not in depth, but it is necessary since later chapter uses ranges extensively. Chapter 8 discussed persistence data structures. The immer C++ library is an robust implementation of those structures. The library’s CppCon talk and ICFP paper are also fantastic resources to learn more.

Chapter 10 is about functors and monads. This chapter connects constructs like ranges, std::future, std::optional, and expected into more general concepts. Unlike a lot of “monad tutorial” online, the book takes a more practical approach. A normal imperative programmer should easily understand the material if they followed all the previous chapters. I am; however, not impressed by his usage of the range-based Pythagorean triple example, especially with the readability and performance concern such code raises.

Chapter 11 talks about template meta-programming. It considers type traits as “meta-functions” operates on the type-level. The class template trick to he mentioned to debug metaprogramming is helpful, and I hope that I know it earlier. One of Ivan’s blog posts provides more techniques for debugging template code.

Chapter 12 details on concurrent systems and provides a functional reactive solution. It puts all the ideas in the book into a practical, real-world scenario.

Overall, I will recommend all C++ programmers who are curious about terms like “Currying,” “Monad,” and “Lazy Evaluation” to read this book. Functional programming becomes popular nowadays. Thus, you will find more C++ codebases written in various degree of functional styles. Reading this book can help you understand, write, and appreciate such codebases.

Tail Recursion Explanation

Tue, 22 Jan 2019 00:00:00 GMT

Tail-recursion is an important concept to understand before we can analyse the behavior of a functional program. I will try to illustrate what tail recursion is with an Elm-like pseudocode. Though you don’t need to know any Elm to understand this post.

From recursion to tail-recursion

Consider the following function:

factorial: Int -> Int
factorial n =
    if n == 0
    then 1
    else n * factorial(n - 1)

We can expand factorial(4) as

  factorial(4)
= if (4 == 0) 1 else 4 * factorial(4 - 1)
= 4 * factorial(4 - 1)
= 4 * factorial(3)
= 4 * (if (3 == 0) 1 else 3 * factorial(3 - 1))
= 4 * 3 * factorial(2)
= ...
= 4 * 3 * 2 * 1 * 1
= 24

Because we multiply numbers to the inner-function call result, we need a place to store those numbers 4, 3, 2, 1. Those numbers are stored in the stack frames. Since every function has its own frame, we need to create n + 1 stack frames for factorial(n).

Tail recursion is a space optimization for the recursive calls. Unlike most optimizations, it changes the asymptotic behavior of the memory usage from to . The idea is that if a recursive call itself is the last action in another function call, the function’s stack frame can be reused. Function calls in the tail position of another function call are called tail call.

Accumulators - Technique for implement tail recursive functions

A nice technique to transform naive recursive functions to tail recursive counterparts is using accumulators. For example, here is a tail recursive version of factorial:

factorial: Int -> Int
factorial n =
    let helper acc n =
        if n == 0 then acc else helper (acc * n) (n - 1)
    in
    helper 1 n

Using accumulators implies an iterative process that we use all the times with loops. Indeed, tail recursions will always transform into the same kind of low-level code as the loops by a compiler.

Continuation-passing style

Accumulators are not always working. There is another technique called continuation-passing style (abbreviate as CPS) to transform more complex recursive functions. Here is our factorial() function in continuation-passing style:

factorial_k: Int -> (Int -> a) -> a
factorial_k n k =
    if n <= 0 then
        k(1)
    else
        factorial_k (n - 1) (\v -> k(v * n))

factorial: Int -> Int
factorial n =
    factorial_k n (\x -> x)

As you see, there is a lot of boilerplate with no apparent benefit. Writing code in CPS manually is tedious and error-prone, so it is probably not worthwhile to code every recursive function in CPS style. On the other hand, there are tools to translate normal functions into CPS.

Note that the Elm compiler cannot compile code like this at all and would generate infinite recursion at the time of writing, but you can try this function in some other languages.

Afterthought

Since tail recursion is an optimization, not all implementations of all programming language will implement them. For example, there is no mandatory tail-call elimination in the C++ Standard at the time of writing, though all the mainstream compilers (MSVC, Clang, and GCC) will do it anyway. The story is different in functional programming languages. Those languages usually will mandate tail-call elimination if you write a tail-recursive function. The reason is that those languages usually discourage loop or have no loop at all, so tail-call elimination is necessary to achieve a decent performance in a lot of cases. To be a good citizen in those languages, you should try to write recursive functions tail-recursive (at least on the easy cases where you can transform them with accumulators.)

Book Review: "Professional CMake: A Practical Guide"

Tue, 15 Jan 2019 00:00:00 GMT

CMake is the de facto industry standard for the build system generator of the C and C++ this days. Like C++, people seem to love and hate it at the same time. However, it is definitely a better choice compare to writting Makefiles manually.

There are a bunch of Cmake resources online, in the forms of youtube videos, conference talks, and blog posts, but they are usually either for beginners, solve a specific problem, or focus on “best practices.” I would not say such resources are bad, but they are inadequate. For example, even though books like Effective Modern C++ are useful, but we need to first read books like The C++ Programming Language to have the whole picture of the C++ language. And counterparts of this book in the CMake world are hard to find.

As a result, CMake is always a dark side to my codebase. I use CMake for years with a very shallow understanding of how it functions. For most of the time, my level of familiarity with CMake is enough. I would copy and paste code snippets I find online. However, whenever I want to do any “non-trivial” tasks with CMake, I will meet trouble. One of the reasons is that a lot of tutorial writers, like me, have a minimal understanding of CMake so that they will post none-robust CMake scripts. For instance, a lot of the times we need to copy resources files from the source directory to the binary directory, and for years I used a way that would only copy files when a file with the same name does not exist in the build directory. Nonetheless, in Graphics programming, I modify shaders all the time, and every time I need to delete the files in binary directory manually. A more sinister drawback of this workflow is that I can modify the shaders and forget to remove the old ones.

Recently, I find someone recommend “Professional CMake: A Practical Guide,” a CMake handbook written by a CMake co-maintainer Craig Scott. The book is a structured introduction to CMake. It helps me to form a basic understanding of how CMake works. I learned concepts like differences between configure time and generate time and generator expressions. All of those are rarely mentioned in online tutorials. The book also mentions a lot of “best practices” and the common pitfalls of using CMake in each chapter (and the better alternatives).

All in all, I recommend this book for anyone kept using CMake in the dark. Build system codes are still part of the production system, and they deserve the same attention as the regular codes. Maybe you should treat them even more carefully than the regular codes since in a lot of times build system errors are even harder to debug than the most insidious template metaprogramming bugs (Afterall, CMake scripts are “meta-meta programming” in a very dynamic language where no type system will save you.)

Resource management and RAII in C++

Wed, 26 Oct 2016 00:00:00 GMT

Recently, I have encountered a legacy code base at work. There are several tremendous class written like this:

class ExtnlOutData
{
public:
    int phase;
    int* phaseIdx;
    char** phaseNames;
    ...

    ExtnlDLLData() : phaseIdx(NULL), phaseNames(NULL) {}

    ~ExtnlDLLData()
    {
        if (phaseIdx) {
            delete[] phaseIdx;
            phaseIdx = NULL;
        }

        if (phaseNames) {
            for (int i = 0; i != phase; ++i) {
                if (phaseNames[i]) delete[] phaseNames[i];
            delete[] phaseNames;
            phaseNames = NULL;
        }
    }
}

The real class is much bigger. We can criticize this snippet in multiple ways. For example, the copy-operations will do shallow copy, which is counter-intuitive. And programmers of the dynamic libraries conform this interface need to allocate memory themselves, which is monotonous and error-prone. If we allocate more space to phaseIdx than sizeof(int) * phase, memory leak happens; if we allocate less space, the program will crash mysteriously.

I want to focus on the “DLL” part today. This class is designed as an interface for customized plug-ins of our software. We use them like this:

void calculate ()
{
    ExtnlOutData data;
    extnlDllCalculate(&data);

    // Do something about data
}

The problem is that now all parts of our software need to be compiled by the same compiler which builds legacy shared libraries (In our case, it is Visual Studio 2008, which is quite ancient). The reason is that we destroy memory outside the dll while allocate memory inside the dynamic libraries. Since different compilers may call different memory management functions, the program will crash at the destructor of data. This situation is like what happens when we combine malloc() and delete, but it is a lot more insidious.

Qt library: example

It is surprised to me that some otherwise well-designed code bases suffer similar problem. For instance, the Qt Library’s parent-child relationship is a similar resource management strategy. If you have used QT, you must have written code like this:

// Not real Qt code
void foo(QString name, QFont font)
{
    QTabWidget parent;
    auto child = new QWidget;
    parent.addTab(child);
    child.setName(name);
    child.setFont(font);
} // The distructor of parent will destory child

As a consequence, Qt, unlike most libraries, cannot be linked by different compilers than what itself compiled. For example, QT 5.7.0 for windows 64 binaries have three versions (VS 2015, VS 2013, MinGW) to satisfy different compiler users. We must use corresponding compilers to develop Qt application.

Exception safety problem

If you are programmers develop software solely for POSIX platforms, you may think it is not your business. But I have another point relate to you, too. The point is, those ad hoc resource management strategies are innately exception-unsafe. Consider what will happen if setName or setFont can throw exceptions. An innocuous order change by clients will introduce leak:

child.setName(name);
child.setFont(font);
// if the above lines throw, the child will never be freed
parent.addTab(child);

No wonder old style libraries like QT forbid exceptions for “historical reasons”. But the library authors still cannot prohibit clients do something like this:

child.setName(name);
child.setFont(font);
if (!child.valid()) throw Exception{"Invalid tab"}; // May cause leak
parent.addTab(child);

RAII to rescue

In the title, I discourage you from inventing your own resource management routine. The reason is c++ already have a standard resource management idiom RAII. It can easily eradicate problems about leak and unmatched system functions memtioned above. We can redesign the first example like below:

struct PhaseData
{
    int ID;
    std::string name;
}

class ExternalOutData
{
public:
    ...

private:
    std::vector<PhaseData> data;
    ...
}

As for the GUI example, if you decide to write a new GUI library now, you can design your interface like this:

void foo(MyString name, MyFont font)
{
    MyTabWidget parent;
    auto child = std::make_unique(MyWidget);
    child.setName(name);
    child.setFont(font);
    parent.addTab(std::move(child));
} // The distructor of parent will destory child

This version is a bit more verbose, but it has the similar usage of Qt, without Qt’s problems.

Integrate a unit test framework in cmake

Fri, 13 May 2016 00:00:00 GMT

Automatic tests are ubiquitous in software industry these days. Especially to large-scale software, it is necessary to have a set of test to ensure the specification is fulfilled and to prevent regression bugs. In this post, I will not bore you with why we do test. Instead, if you are using the CMake build system, I will show you how easy it is to integrate test into the system.

In this tutorial, my directory structure includes two parts: the sources (in src subfolder) and tests (in test subfolder).

The test framework I chose is Catch2. However, the process of using different frameworks like CppUnit, Boost Test Library, doctest, or googletest should be very similar.

Setup

Firstly, I added all the source code except main.cpp into a library called common and linked it by both the production program and the test.

./CMakeLists.txt

cmake_minimum_required (VERSION 2.8)
project (MyAwesomeProject)

...

add_subdirectory (src)

...

add_executable(MyAwesomeProject src/main.cpp)
target_link_libraries (MyAwesomeProject common)

add_subdirectory (test)

src/CMakeLists.txt

add_library (common a.hpp a.cpp b.hpp)

Configure test framework

We can create a test/CMakeLists.txt that deals with testing stuff. You can then put the unit test library into your repository. Since Catch is a header-only library, we can use CMake’s interface library to handle it. For libraries like googletest, just link it as a normal library.

# Add catch as an interface library
set(CATCH_INCLUDE_DIR <WHERE YOUR Catch.hpp is>)
add_library(Catch INTERFACE)
target_include_directories(Catch INTERFACE ${CATCH_INCLUDE_DIR})

# Add test executable
add_executable (tests testmain.cpp testA.cpp testB.cpp)
target_link_libraries(tests Catch CommonSourceCode)

An alternative: CMake external project

An (unrecommended) alternative is to fetch the test framework from GitHub automatically and configured it as a CMake external project. This way you do not need to worry about updating the test framework to its latest version. Do aware this way you cannot compile the code without Internet connection since whenever CMake runs it will try to fetch your unit test framework online.

include(ExternalProject)
find_package(Git REQUIRED)

ExternalProject_Add(
    catch
    PREFIX ${CMAKE_BINARY_DIR}/test/catch
    GIT_REPOSITORY https://github.com/philsquared/Catch.git
    TIMEOUT 10
    UPDATE_COMMAND ${GIT_EXECUTABLE} pull
    CONFIGURE_COMMAND ""
    BUILD_COMMAND ""
    INSTALL_COMMAND ""
    LOG_DOWNLOAD ON
   )

# Expose required variable (CATCH_INCLUDE_DIR) to parent scope
ExternalProject_Get_Property(catch source_dir)
set(CATCH_INCLUDE_DIR ${source_dir}/include CACHE INTERNAL "Path to include folder for Catch")

# Add catch as an interface library
add_library(Catch INTERFACE)
target_include_directories(Catch INTERFACE ${CATCH_INCLUDE_DIR})

# Add test executable
add_executable (tests testmain.cpp testA.cpp testB.cpp)
target_link_libraries(tests Catch CommonSourceCode)

`ctest` support

Now we can run the test program manually by executing the test executable. We can even configure our IDE to run the test excutable whenever we compile.

Still, we can do better. CTest is the test driver program that CMake provides. To enable ctest, we need CMake to realize our tests executable is for tests.

add_test(NAME tests COMMAND tests)
enable_testing()

To enable CTest, add the following line into the top level CMakeLists file after we define the project.

include(CTest)

Package managers

If your project use package managers like Conan or hunter, integrating unit test frameworks should be brainless. However, the idea of making a test executable alongside the main one still apply.

Conclusion

CMake is a widely accepted cross-platform build tool across the industry. Adding unit test and other supporting tools like CI and static analysers to it is incredibly easy.

If you are still using IDE specific configurations or good old Makefiles for C or C++ projects, I will suggest you spend several hours learning how to use CMake. It will be a production boost.

Lesley Lai's Blog

A Love Letter to Flashcards

Resources

Fifty Shades of OOP

Classes

Method Syntax

Information Hiding

Encapsulation

Interfaces

Late Binding

Dynamic Dispatch

Inheritance

Subtyping Polymorphism

Message Passing

Open Recursion

OOP Best Practices

In the End

Self hosting comments with Comentario

Self-Hosting Setup

Custom Domain and DNS

Reverse Proxy

Client-Side and CSS

Final Notes

Resources

Site Update (April 2025)

Representing an Abstract Syntax Tree in C++: Variants

What Do I Mean by Variant?

std::variant

Discriminated Union

Enum Tag + Inheritance

A Virtual Function That Returns Enum Tag

Inheritance with the Visitor Pattern Approach

”Uber node” as an alternative to variant?

Conclusion

Online Courses that I Recommend

Meta-Learning

Math

Calculus

Linear algebra

Differential Equations

Discrete Math

Signal Processing

Logic

Computer Science and Programming

Intro

Computer Graphics and GPU Programming

Programming Languages and Compilers

System Programming

Misc

Psychology

Physics

Tips on finding good courses

Highly Regarded Courses that I don’t recommend

Small Naming Tip: Use "from" Instead of "to" in Function and Variable Names

What happened to Lesley in the last couple of years

2021 Summer Fiasco

After I went back to China

First Half of 2023

Restart Application Process

US Visa Application

2023/12/24 Update: University’s Follow-Up

2024/1/3 Update: Second Visa application

Footnotes

Use ManuallyDrop in Rust to control drop order of structure fields

The problem

A Vulkan example

Using Option to circumvent the drop order

Introducing ManuallyDrop

Drawback of ManuallyDrop

Conclusion

Footnotes

CMAKE_SOURCE_DIR is probably not what you want

VK_KHR_dynamic_rendering tutorial

Initialization

Check extension availability

Enable feature and load the extension

Use dynamic rendering in command buffer

Pipeline creation

Image layout transition

Final word

`std::variant`

Using `Option` to circumvent the drop order

Introducing `ManuallyDrop`

Drawback of `ManuallyDrop`

Enter `std::align`

The motivation for `std::function`

Mutable Lambdas destroy the beauty of `<algorithms>`

What about using mutable lambdas in `std::generate`?

Where `const` or reference member variables can still be useful