Today we will look at reproducing functions. Starting with no arguments, void functions, all the way up to functions returning multiple values.

Nullary Void Functions

The definition of function¹ we will be using in this article is:

A named group of instructions that is reusable, can take inputs and can return outputs

From what we have seen in the previous article, jumps seem like a good approximation of this concept: they provide a mechanism to execute code from elsewhere, and they have a human-readable name. What could one desire more?

In high-level languages, functions do their job and hand back control to the caller once done, typically with the return keyword. Jumps, conversely, are one-way control transfer: once you jump to a location there is no way back unless the callee knows where to jump to.

The premise that we need to control callee and caller hinders reusability, one property we expect from functions. Imagine authoring a library; functions would have to know details about calling code’s structure to jump back, making it impossible to write modular or reusable code.

How do we make this execution model caller-independent?

Call and return

At any moment, we know the address of the current instruction because it’s stored in rip, the instruction pointer. The caller can save this address before jumping to another location, and the callee can later jump back to the next instruction using that saved address. Problem solved, right?

Not quite. Doing all this manually would be tedious and prone to mistakes. Luckily, assembly provides two instructions, call (call) and ret (return), to do the math for us. Let’s look at them.

The first, call looks like a jump:

call label

It jumps to the specified label, but before doing so, it saves the current address (the return location) to a special memory region called the stack.

Note

We will look into the details of the stack in the next article. For now, all you need to know is that it’s a memory location where you can store values and retrieve them later.

Much like in high-level languages, at the end of a function we return to hand the control back to the caller. In assembly, we do that using the ret (return) instruction

label:
 ; code of the function
 ret

Just like a Scooby Doo mask off moment, what we see is once again a jump: ret fetches the value stored on the stack by call and jumps back there, giving back control without having to know anything about the caller. Victory!

Let’s look at an example.

We’ll create a little dungeon crawler game where our explorer navigates a maze to find a treasure. We will learn a few new instructions and extensively use functions to reduce boilerplate. Incidentally, we will realize we already know how to implement loops in assembly, our second high-level programming concept for this article.

Arity and Return Values

Alright, that was a lot to take in! But the good news is we’ve already covered most of the heavy lifting for today. Great job!

As you know, there is very little one can do with functions without passing parameters or returning values. Let’s go ahead and fix that.

In the examples above, we got comfortable with passing data between functions using registers.

For example, before calling print, we set the values of rsi and rdx so that the function had the right data in the correct registers. That’s how parameters are typically² passed to functions in assembly.

Returning values works the same, but in reverse: when a function needs to return a result, it places the value in a designated register, allowing the caller to retrieve it from there.

This system feels a bit brittle, doesn’t it? How can we make sure that functions don’t overwrite registers we’re relying on? How do we decide which registers to use for what? And how do we preserve values across function calls?

Calling Conventions

Since the language can’t inherently enforce rules, assembly relies on calling conventions: guidelines for passing parameters, returning results, and safely using registers to ensure data integrity.

These conventions are part of the Application Binary Interface (ABI), specific to each operating system³. Our ABI of reference will be x86-64 System V ABI, commonly used in most Unix-like systems.

To prevent unintended data overwriting, the ABI introduces two register categories: callee-saved and caller-saved.

• callee-saved means the callee is responsible for preserving the value in the register. Practically, it means the callee must either not use the register, or save its original value before use and restore it before returning control to the caller.

• caller-saved means the caller is responsible for preserving the value in the register. In other words, the caller needs to store the register in the stack before invoking a function, if it cares about it.

Here’s the condensed version of the calling convention we will use in this course.

Sticking with the game theme, we will code a die roller. We won’t introduce new instructions, but we will see calling conventions and we will quickly touch on addressing: a new way of referencing memory that we will explore more in depth later on.

Conclusion

We explored how functions work using call and ret, and learned about calling conventions to safely pass parameters, return values, and manage registers without breaking things.

Next up, we’ll dive into the stack; a new tool for handling data beyond registers and fundamental to implement our next high-level construct: scope.

We will spend this lesson learning more instructions and use this knowledge to translate the first high-level construct into assembly: conditionals.

Control Transfer Instructions

Remember those old movies where computers were fed with long tapes of instructions? Surprisingly, today’s lightning-fast CPUs still work similarly, but executing instructions coming from a sequence of bytes in memory. We call this sequence the instruction stream, and the unique position of each instruction an address. As we saw in the previous article, the address of the instruction currently being executed is stored in the rip register, which is why we call it the instruction pointer.

Imagining the instruction stream as an array whose indices are the addresses¹, the execution of a program in pseudo-code would read something like this:

while not exited
  // Fetch the instruction at `registers.rip`
  instruction = instruction_stream[registers.rip]
  // Execute the instruction and return the
  // address of the next instruction.
  next_pointer = instruction.execute()
  // Assign the new address to `rip` to fetch
  // a new instruction on the next iteration.
  registers.rip = next_pointer
  // Handle side effects (we won't look into this)

Most of the time, the execution is linear: instructions are executed one after the other, in the order they are coded. Some instructions, however, can break this convention and are called Control Transfer Instructions (CTIs).

CTIs come in three flavors: conditional, unconditional, and software interrupts. We’ll focus on the first two, as they are the foundation of control flow in assembly, allowing the execution of non-consecutive instructions. Software interrupts, while interesting, are closely intertwined with operating systems and beyond the scope of this series².

The first CTI we will explore is jmp (jump).

Unconditional jumps

Jumps allow executing code at an arbitrary position in the instruction stream. All they need to do is update the rip and, on the next cycle, the CPU will pick up the instruction at the new address.

Syntactically, a jump looks like this

jmp label

where the operand represents the destination instruction.

Almost always, the destination is a label, and in plain English, the instruction above reads: “Continue the execution from the instruction whose label is label.”

The assembler, the software that turns assembly into machine code, translates the labels into a numeric address of the instruction stream and, on execution, it will be assigned to rip as described above.

In fact, numeric addresses and relative offsets to rip are all valid destinations, but they are usually more in vogue among machines than humans. For example, compilers with optimization flags or disassemblers prefer using numeric addressing rather than labels.

The attentive readers will have noticed that the jump we just described does not depend on any condition: if the program reaches that line, it’ll jump. This makes this instruction unconditional.

Let’s see an example in action.

We will use the same hello world example from the first lesson. We will make it more human-readable by introducing jumps to break the code into smaller chunks. En passant, we will introduce numeric constants to remove magic numbers from our code.

Conditional Jumps

As you might have guessed, we will implement conditional control flow using conditional CTIs and in particular conditional jumps. Don’t worry – we’ve already laid the groundwork with jumps, and conditional jumps are just an extension of the same concept.

Coming from high-level languages, you might be used to versatile conditional statements like if, unless, or when. Assembly takes a different approach. Instead of a few all-purpose conditionals, it provides a large number of specialized instructions for specific checks.

Fortunately, these instructions follow logical naming conventions that make them easier to remember. Let’s check an example out.

jne label

Here, label refers to an instruction in our code, just like we saw with unconditional jumps. In plain English, this would read “Jump to label, if Not Equal.”

The following table provides mappings to navigate the most common conditional jumps³:

Here’s a few more examples:

• je label: “jump if equal”
• jnz label: “jump if not zero”
• jg label: “jump if greater than”

These instructions do exactly what their names suggest: if the condition is met, the program jumps to the destination label. If not, it simply continues to the next line. Just like with unconditional jumps, the destinations can also be specified numerically.

Now, you might be wondering: “Equal to what?” “Greater than what?” “Zero compared to what?”

Let us answer these questions diving into the mechanics behind comparisons in assembly, introducing a special register that plays a crucial role in this process: the eflags register.

Flags

The eflags is a 32-bit register⁴ that stores various flags. Unlike general-purpose registers, eflags is read bit by bit, with each position representing a specific flag. You can think of these flags as a set of boolean values built right into the CPU. When a bit is 1, the corresponding flag is true, and when it’s 0, the flag is false.

Flags serve multiple purposes⁵, but for our discussion, they’re used to provide context after an operation. For instance, if an addition results in zero, the overflow flag (OF) can tell us whether this is due to an actual zero result or an overflow. They are relevant to us, since flags are how assembly stores the results of comparisons.

In this section we will only look at the following flags:

• the zero flag (ZF), set to 1 when an operation results in zero;
• the sign flag (SF), set to 1 when the result of an operation is negative.

The cmp (compare) instruction is one common way of performing comparisons:

cmp rax, rbx

This instruction subtracts the second operand from the first without storing the result. Instead, it sets flags based on the comparison. For example:

• If the operands are equal, the zero flag (ZF) is set to 1;
• If the first operand is greater than the second, the sign flag (SF) is set to 0.

With this understanding, the meaning of conditional jumps should become clear:

• “jump if equal” (je) translates to “jump if ZF=1”
• “jump if not zero” (jnz) translates to “jump if ZF=0” (equivalent to jne)
• “jump if greater than” (jg) means “jump if SF=0 or ZF=0”⁶

At last, conditionals

We are now, finally, ready to write conditionals in assembly. Joy!

Consider this simple pseudo-code:

if rax == rbx 
  success()
else
  error()

In assembly, we can express this logic as follows:

; Compare values in rax and rbx
cmp rax rbx
; If they are the equal, jump to `success`
je success
; Else, jump to `error`
jmp error

This assembly code first compares the values in the rax and rbx registers using the cmp instruction. Then, it uses conditional and unconditional jumps (je and jmp) to control the program flow based on the comparison result.

Let’s look at another example. Enough hello world. This time around we build a serious software that performs an addition and checks if the result is what we expect. Very serious.

Conclusion

We made it, friends! We’ve explored the fundamental building blocks of control flow in assembly language.

We’ve learned about Control Transfer Instructions (CTIs), focusing on unconditional and conditional jumps. We’ve seen how the instruction pointer (rip) guides program execution and how jumps manipulate this flow. We’ve delved into the eflags register and its crucial role in comparisons, understanding how flags like the zero flag (ZF) and sign flag (SF) inform conditional operations. Finally, combining the cmp instruction with jumps, we’ve constructed the assembly equivalent of high-level language conditionals.

While jumps enable basic control flow, they can make code hard to follow. In our next article, we’ll introduce the equivalent of functions: a way to execute code from elsewhere while maintaining a linear flow. You’ll see how this approach mirrors procedural code in high-level languages, making assembly more intuitive and organized.

Let’s take the following snippet:

section .data
  msg db "Hello, World!"

section .text
  global _start

_start:
  mov rax, 1
  mov rdi, 1
  mov rsi, msg
  mov rdx, 13
  syscall

  mov rax, 60
  mov rdi, 0
  syscall

Thankfully the second line gives away what this does.

None of the bread and butter of programming as we know it is here: conditionals and loops are nowhere to be seen, there is no way to create functions… heck, variables don’t even have names!

Where does one even start?

This little introduction is meant to introduce you, somebody with programming experience, to the world of assembly. We’ll discuss the basics of the language and map them to high-level programming constructs.

By the end of this guide, you will be able to navigate assembly code, know where to look for information, and even write some simple programs all by yourself.

Let’s get started!

Hello world

Unsurprisingly, our first program will be a “Hello World”.

Before jumping into the code though, we need to briefly introduce the language we’ll be using. At the end of this section, we will be able to write and run our first assembly program.

x86-64 assembly

First things first, assembly is not a language.

Assembly refers to a family of programming languages featuring instructions that closely map to the machine code that the CPU will execute. In fact, one of the raisons d’etre of assembly languages is to provide a human-readable version of machine code in situations like reverse engineering, hardware programming, or developing games for consoles.

In this guide, we will use x86-64 assembly which can be assembled and executed on most personal computers. This choice should ease running and tinkering with the snippets along the way.

For historical reasons, there are two “flavors” of the x64-64 assembly syntax: one called Intel and the other is called AT&T¹.

In this guide we will stick to the Intel dialect because it’s used by the Intel Software Developer Manuals (SDM), the source of truth on what the CPU really does when fed an instruction.

Assembly is all about working close to the hardware. Optimizimg for portability of the code examples across operative systems and architactures would obfuscate the content of this introduction.

The snippets we will be written for Linux, and they should run fine on Window’s WSL as well. The general concepts and practices are nonetheless valid regardless of your OS of choice.

Anatomy of an instruction

Instructions are the way we tell the CPU what to do. They look something like this:

mov rax, rbx

They represent the smallest unit of assembly language and are mostly composed of two parts:

• mnemonic: a shortened word or sentence that specifies the operation to be performed
• operands: a list of 0-3 items representing what’s affected by the operation

In our example, the mnemonic is mov, which stands for move, and the operands are rax and rbx. This instruction in plain English would read: move the content of rbx to rax.

Note

rax and rbx are registers and we will introduce them in the next paragraph. In the meantime, you can imagine them as variables holding a value.

Some instructions will have more then mnemonic and operands. Additional parts such as prefixes and size directives will only be needed later, and we’ll talk through them at the right moment.

Fear not, there is no need to memorize all the possible instructions now. Whenever we’ll come across new operations, we will discuss them, and with repetition you will remember in no time.

The Intel Software Developer Manuals (SDM) will be our instruction reference in the next chapters. Keep it handy!

Storing data: Registers

You can think of registers as storage space baked right into the CPU itself. They are small and incredibly fast to access.

The most common registers are the so-called general purpose registers. In x86-64 they are sixteen in total, and they are 64 bits wide.

One can access the whole register or a subset by using different names. For example, using rax (as in the code above) would address all the 64 bits in the rax register. With al, you can access the lower byte of the same register.

^{¹: 2 bytes are sometimes called words (hence the w suffix)
²: 4 bytes are sometimes called double-words or dwords (hence the d suffix)}

General purpose means that they can store anything in principle. In practice, we’ll see that some registers have special meanings, some instructions only use certain registers, and some conventions dictate who is expected to write where.

The only non-general-purpose register we will look at today is rip the instruction pointer register. It holds the address of the next instruction to execute, and therefore, modifying rip allows programs to jump to arbitrary instructions in the code.

Our first assembly file

Assembly files typically have an .s or .asm extension and they are split in sections. We will mostly be concerned with two sections:

• data: where we define constants and initialized variables;
• text: where we will type our code, this is the only mandatory section of the file.

section .data
  ; data here

section .text
  ; code here

Note

The semicolon ; is the comment character: whatever comes after it will not be executed.

Assembly programs run as you would expect. They start with the first instruction and sequentially execute one instruction after the other, from top to bottom. To create control flow, such as conditionals and loops, we make our programs ‘jump’ to specific instructions. We will look at jumps in detail in the next sections.

Just as you’d use a main function in many high-level languages, assembly requires us to specify an entry point for our program. We do this using the global declaration, which points to a label.

Labels are the assembly’s way of giving human-readable names to specific instructions. They serve two purposes: making our code more understandable and allowing us to reference these instructions elsewhere in our program. You can declare a label by writing it followed by a colon, like this: label:. When you want to reference a label (for example, in a jump instruction), use it without the colon: label.

Typically, global references a _start label declared immediately after it. That is where our program will start executing.

section .data
  ; data here

section .text
  global _start
_start:
  ; instructions here

At last, “Hello World”

Finally, we have all the tools to build software in assembly. Very Nice!

Our program will use two system calls: sys_write to print characters in a terminal and exit to terminate the process with a given status code.

Using syscalls goes like this:

• select the syscall to invoke by moving its identifier in rax
• pass arguments to the syscall by populating appropriate registers
• use the syscall instruction to fire the call

The only other instruction we will use is mov which we have seen in the instruction paragraph. It works pretty much like an assignment (the = operator) in many high-level languages: it moves the content of the second operand into the first operand.

Let’s look at the code to see how this plays together.

Coding along

Throughout this series, we’ll use an embedded editor to tinker with the code and run the examples as we go. The same content can be found in the sibling repository shikaan/x86-64-asm-intro if you want to run locally.

All the snippets are commented to explain what’s going on step by step. Make sure you read the comments carefully!

Conclusion

We have a “hello world”!

In this first article, we learned some basic assembly concepts, we cut our teeth on its syntax, and we even wrote some working software. Moreover, we explored how to communicate with the operative system and are ready to produce more interesting programs in the next article.

A bit of history

As a lot of the scientists of his time, he was a full-stack mathematician: his work has spanned Mathematics, Thermodynamics, Chemistry down to Engineering.

He also contributed to the “Description de l’Égypte”, although I am not sure whether Egyptology falls under the mathematical spectrum of full-stackness…

Along with his scientific career he was also a key member of the French Revolution and a loyal man in the service of Napoleon Bonaparte. Precisely at that time, he was called to solve a very practical problem which was affecting armed forces: how do we cool down guns and keep them usable during a very busy battle?

This lead to Fourier’s Theorem (and its byproducts Fourier Transforms) which are exactly the way computers and hi-tech gizmos deal with music and images.

Yeah, warm guns really relate to bathroom selfies…

Fourier basic idea was simple yet brilliant: heat waves — no matter how complicated they are — can be decomposed as sum of elementary waves.

Albeit this was a clever intuition, Fourier did not prove it in modern rigorous terms¹. However, his was not a lucky shot.

The decomposition of periodic functions in smaller elementary functions dates back to 3rd century BC when Ptolemaic astronomy tried to explain the motion of the planets. Also, the idea that studying heat waves could be related to periodic functions was not entirely new: Euler, d’Alambert and Daniel Bernoulli put together some solutions for the heat problem which happened to work only when the heat source behaved like an elementary wave.

Anyway, in one hundred years time the whole matter will be completely settled by Dirichlet and Riemann who will put the pieces together and give Harmonic Analysis a proper mathematical foundation.

As a matter of fact, such mathematical foundation is the very reason why we can use Fourier’s results outside of that domain: heat waves are just… waves, so as long as a given signal can be turned into waves, we can apply Fourier’s results to study them.

Now your ridiculously boring hours in physics classes make sense: both light which ultimately forms images and sounds are waves. Hence, they can be analyzed using Fourier’s Theorem.

Fourier Analysis for the rest of us

First things first: from a mathematical point of view, signals can be thought as functions. So in the following lines — as a common practice in Harmonic Analysis in general — we’ll be referring interchangeably to “functions” and “signals”.

The whole idea behind Fourier’s work was to rewrite “any given function”² as sum of elementary periodic chunks. As you remember from high school, the most elementary periodic things you can think of are sine or cosine and these small chunks are usually named oscillations.

Therefore, in Fourier terms all signals can be written like

where a coefficients can be thought as the average of the function we want to represent on a given interval. Such interval is called period and happens to be the period of the oscillations.

The key idea behind decomposition in oscillations is the following: the more you want to be precise the further you have to go in summing oscillations. Thence, the way to increase precision is to sum infinite chunks. Infinite sums in mathematics are called series and this is the shape of the Fourier Series for a given function:

One detail we omitted was that the above works for periodic signals. What happens when the signal is not already periodic? Luckily, the above still holds true to a certain extent and the generalization falls under the name of Fourier Transform. We’re not going to dig deeper on this.

A quick example

A simple way to picture this is thinking about what happens with music. Let’s say, for the sake of the argument, that each note emitted by a piano can be represented as a sinusoidal wave³. When you play a chord — namely more notes and once — you are producing a wave which is formed by summing all those waves.

What you get then is a complex signal which is ultimately given by the sum of elementary signals. The peak of the chord wave (the yellow one) happens when all the three node waves are at their peak, whereas none of the bottoms of the chord wave are as low in comparison: this is due to the fact that there is no moment when the three of them are at their bottom concurrently.

Applications in everyday life

Now, what you might be wondering how summing infinite things can lead to a non-infinite, hence meaningful, result. This problem is rather general in Mathematics, it is called convergence and unfortunately cannot be treated within this article because of its complexity.

However, one very evident thing can be observed here: to make this sum to not go to infinity (i.e. diverge), we need chunks which get smaller and smaller. This in turn implies that some items in the sum are holding the greatest part of the information needed to represent the original signal.

This last observation is what makes Spotify, Shazam, Instagram and even your iPhone’s guitar tuner app or noise canceling headphones possible.

In fact, when you are playing your music via Spotify you are not listening to the song exactly as it has been recorded. In order to provide a continuous data flow and keep the track going without needing to download it in advance, Spotify applies a compression algorithm which is meant to reduce file size enough to be streamed in real time.

What this algorithm does is:

• spot oscillations related to frequencies at end of or beyond the human audible spectrum and shave them off;

• remove the oscillations which do not hold a lot of information, namely the “rest” of the series.

The same principle applies to Shazam, SoundHound or even Siri and Google Assistant: when you provide a sound input, these software need to clean it, for example, removing frequencies which go beyond the average human voice spectrum and taking away minor oscillations. The actual search then happens comparing the coefficients of same oscillations between your input and a dataset.

Noise cancelling headphones work the same way: they have a microphone which records the ambient sound and calculates oscillations. Then they flip the oscillations so that the sum with the sound around you yields a silent wave. Eventually they inject this flipped wave in your mix so that frequencies outside of your music are not audible.

For images the things get a bit trickier because in that case we have to speak about two-dimensional Fourier Transform as the image signal spans across two dimensions. The underlying idea though stays the same: when we share a picture on Instagram, an algorithm chunks the image and applies the same kind of approximation we have seen above on every single pixel. This time around the computation happens on things like color spectrum and brightness and elements which live at the border of our perception are tossed away.

Conclusion

Every time you will see your younger sister’s bathroom selfies on Instagram or you listen to a Ed Sheeran song on Spotify, now you know who to blame. Do you think that in hindsight Fourier would have spread this knowledge?

Until next time!

Serving the correct application version

Serving the correct version of a web app started to become something you should be concerned about only “recently”.

Back in the days, we had server-side technologies like Java, JSP and PHP which used to serve thin client applications with small or no logic at all. Over time clients got thicker and we started splitting responsibilities between frontend and backend to the point where frontend and backend are usually two completely different applications¹ which are just meant to communicate, rather than being “the same thing”.

When the application is run by the server, serving the correct version isn’t a concern, because the browser is usually just asking “that page” and the ball it’s in the server’s court with regards with deciding which version of that page to serve².

When the application lives on the client side, unfortunately, the page requested by the browser is usually an index.html with a <script> which includes the client application via an src attribute.

So if the index.html is something like

<!DOCTYPE html>
<html>
  <head>
    <title>Wonderful WebApp</title>
  </head>
  <body>
      <main id="app"></main>

      <script src="app.js"></script>
  </body>
</html>

we could theoretically just bundle a different app.js every time keeping the index.html the same.

Unfortunately, that is not true any more. Browsers nowadays understand whether something changes³, so rather than asking again app.js, they will just assume it never changed and serve the old one unless we communicate them to not do so.

One way of doing this is appending the version of the application as a query string parameter in the src.

<!DOCTYPE html>
<html>
  <head>
    <title>Wonderful WebApp</title>
  </head>
  <body>
      <main id="app"></main>

      <script src="app.js?v=1.2.3"></script>
  </body>
</html>

Thus every time we bump a new version of the bundle, the browser is forced to perform a new request because the URL and the index.html changed.

Another similar (and by far more common nowadays) approach is naming the bundle with a hash which is different on every deploy. The hash can be based on the actual version, on the code, on the latest revision number or even the timestamp of the moment when the build happened.

<!DOCTYPE html>
<html>
  <head>
    <title>Wonderful WebApp</title>
  </head>
  <body>
      <main id="app"></main>

      <script src="app.gt8heef.js"></script>
  </body>
</html>

This technique is rather popular and most of the time is “for free” in CLIs for popular frameworks (like Create React App, Angular CLI, Vue CLI, Ember CLI).

You can implement it yourself using a build tool which rewrites the index.html including the version number/hash or, eventually, using manifest.json to get more fine-grained control. Some references to help you with implementation:

• Webpack - Caching my preferred way;
• Medium - Solving Browser Cache Hell With Gulp-Rev a gentle introduction to manifest.json;
• DZone - Use Gulp to bundle, minify and cache-bust old, but still relevant;
• Jessie Wong - Cache busting with Makefile a bit hardcore to me, but still an option.

Optimize content delivery with Service Workers

Among the things going hand in hand with manifest.json (especially with regards to Progressive Web Apps), we have Service Workers.

Without going too much in details about the awesome things you can do with service workers⁴, you can imagine them as a JavaScript thread running in parallel in the browser whose life cycle is not bound to the client application’s one.

The reason why we are so interested in them here is that in Service Worker API we have access to the Cache Interface.

There are some caching recipes you can follow, but the most common are:

• on install
• on user interaction
• on network response

The naming convention is borrowed from one of the greatest resource on the matter you can find online, namely Google’s Offline Cookbook.

If you followed what happened in previous episodes, you will certainly notice that the role played by Service Workers in those recipes is what in general we have called Resource Manager. Hence in the following paragraphs, I am about to show how those patterns map to what we said in previous articles.

Well, to be fair there’s another very good resource about this topic which is Mozilla’s Service Workers Cookbook - Caching Strategies, but I find Google’s perspective easier to follow. I strongly encourage you to read both anyway to have a wider spectrum overview.

On Install

In this pattern we do a cache write on the install hook of the Service Worker. It looks particularly useful when you want to store the application shell to be able to provide an offline experience.

In the Google’s cookbook, this comes in two different fashions called “as a dependency” and “not as a dependency”, which are basically “Write Through” and “Write Behind” of this article.

On User Interaction

From a caching strategy perspective, this pattern is not that different from On Install.

Suppose you want to implement a “Read Later” button on a blog. What you need to do is fetch the article and store it. Deciding if you want to save is synchronously (as in “Write Through”) or asynchronously (as in “Write Behind”) depends on your use case, but both the approach are feasible.

On Network Response

Of the three examples we are providing, this is by far the most common since you can apply this strategy every time you need to fetch data over network.

The implementation proposed in the offline cookbook is “Read Through” - no more, no less!

W3C standards: HTTP Headers

In the wonderful world of web development, finding a new fancy way of being screwed is never a problem. This is precisely why you may want to understand how the browser communicates with the server with regards to cached content.

Disclaimer

Even though I will always refer to the browser in the following paragraph, this also applies to server to server communication, so backenders could find this interesting as well.

Again, I am treating only the most interesting cases, but here you can find a list of resources covering more cases:

• MDN - HTTP Caching
• DigitalOcean - Web Caching Basics
• KeyCDN - HTTP Cache Headers Explained
• W3C - Cache-Control Specification
• W3C - ETag Specification
• Google - HTTP Caching

ETag

Even though the name is not exactly explicit, the ETag HTTP Header is one of the headers we can use to have control over cached content. ETag stands for “Entity Tag” and it is a way of tagging with a hash a specific version of a content we are exchanging.

In this case, an example will be better than one thousand words.

Suppose you as a client (both another server or browser) are requesting GET /dogs. The counterpart will respond with a 200 and the following response headers:

200 OK
Content-length: 512
Cache-Control: max-age=60
ETag: a23g1t4

As we’ll see in the following sections, max-age=60 tells us that the content will become stale in 60 seconds.

Suppose that after one minute, we request again the same resource but this time we attach the following request headers:

GET /dogs
If-None-Match: a23g1t4 

which basically means “give me either valid cached content or stale content as long as its version is a23g1t4”.

At this point the server will try to serve cached content, then falls back on stale content with that version and, if not even that is found, then it performs the actual request. In case the cached content is found the response will be:

304 Not Modified
Content-length: 512
Cache-Control: max-age=60
ETag: a23g1t4

Cache-Control

The Cache-Control HTTP header is used to define a cache policy, both from a client side (for example, “don’t give me cached content”) and from a server side (for example, “this content will expire in two minutes”).

Cache-Control has tons of directives which can be combined in a lot of fancy ways which is impossible to cover in a couple of paragraphs. Maybe it makes sense to write a separate article on that (and if you’re interested, please let me know!). We’ll be covering here only the most common directives.

no-cache & no-store

These two bad boys are probably the most mixed up.

The directive no-store - used both as a directive in request headers and response headers - simply means that any caching mechanism should be skipped. So the client should not cache the response it gets (when used in the request) and the server should not cache the response to speed up following requests (when used in the response).

When used as response headers, no-cache means that the content served won’t automatically be valid for subsequent requests. This basically means that the content can be cached or not, but, if it is, it has to be validated (for example using ETag) before being served.

When used as request header, no-cache means that we don’t care about what’s cached and we want a fresh request. However, this does not define whether the server can cache the response to speed up following requests (as opposed as no-store) and usually server will cache that response.

public & private

These look pretty obvious, but they actually hide a small quirk.

public is most of the time useless and, in fact, you rarely find it. It just means “this content can be safely cached”, but usually you have other directives telling you that (for example max-age, as we’re about to see).

private instead is a bit more tricky. It doesn’t mean that you cannot cache the response at all, but it rather says “you can cache that only if you own the content”.

What does being the owner of the information mean?

Suppose you have a micro-service built application with an API gateway in front of it. Every single service and the API gateway can have a cache, but only the micro-services themselves own the information. Usually, the content marked as private is just for one specific user, so only that user and the originator of that information can cache it.

Hence, in the example above, a browser could actually cache that information (as the user owns it) and the micro-service originating the information can, but the API gateway can’t and any eventually CDN in between can’t as well.

max-age

When used in requests, max-age=n means that the client is willing to accept content which is not older than n seconds.

When used in responses, max-age=m means that the information delivered will be considered stale in m seconds.

Final Words

This is the end of this Christmas streak, but maybe not the end of this caching series. Who knows? There are a lot more things we can cover…

As always, if you have any feedback (e.g., why did you stop with memes? why are you so obsessed with caching? how could you complete a whole episode without mentioning food?) feel free to reach out.

Until next time!

Please Note

If you’re looking for an introduction about caching in general and reading techniques, you can go here

What?! Writing techniques?!

I totally see your surprise here. In the reading techniques we already mentioned how and when to write to Cache Layer, so why in the hell do we have a set of different strategies here?

We are calling reading techniques those which are actually concerned with reading actions. For example, get a list of transaction. So, even though we already performed some writing, we were actually performing writing only to serve the purpose of reading actions.

So, writing techniques are basically strategies used during write actions to populate or update Cache. The biggest part of the benefits you get out of them is, again, when you are going to read data afterwards. Examples of writing actions are: create a new transaction, edit user info and so forth.

As mentioned in the other article, we are going to speak about these patterns:

• Write Through
• Write Behind
• Write Around

As last time, these are the participants:

• Client: who needs data;
• Cache: where you store data;
• Resource Manager: delivers resources to the Client;
• Data Accessor: fetches data from outside the application.

Write Through (aka Write Inline)

Exactly as for Read Through (or Cache Inline), we have the Resource Manager sitting in line between Client and Data Accessor.

This diagram illustrates the lifecycle of a writing action using Write Through

These are the steps:

• Client starts a write action calling the Resource Manager;
• Resource Manager writes on Cache;
• Resource Manager writes calling Data Accessor;
• Response is served to the Client.

Rationale

At first glance it doesn’t look like the smartest move: we are in fact slowing down the request adding an extra step. What are we gaining from this strategy, then?

As we have said multiple times, one of the biggest problems with cached data is that they get stale. Well, this pattern solves exactly this problem.

In the other article we have seen that one way to deal with stale entries is using TTLs and that still holds true, but in that case expiration was the best way to solve the issue since we were not producing the data we were fetching. Now we are in control of data we want to read, then updating the Cache every time we write data will ensure that cached entries never gets stale.

Of course there is no light without shadows and besides the write latency¹, this technique can turn detrimental when the Client doesn’t need to read data that often. In this case in fact, you end up wasting the resources needed to keep alive and synchronizing the Cache without gaining the reading benefits.

Write Behind (aka Write Back)

This other technique still has the Resource Manager inline, but writing through the Data Accessor happens asynchronously.

These are the steps involved in action life cycle:

• Client starts a write action calling the Resource Manager;
• Resource Manager writes on Cache;
• Response is served to the Client;
• Eventually Resource Manager writes calling Data Accessor.

Rationale

The best way to understand why and how this caching technique can be useful is to give an example.

Suppose we are now developing TrulyAwesomeBankAPI and we want to implement the Payment transaction creation using Cache. Payments need to happen as quick as possible, but Truly Awesome Bank backing our API is still on an old infrastructure which is not able to handle peaks very well.

We decide to use Write Behind. This means that every time we perform a Payment we save that transaction in Cache and return the response to the Client. Then we have another worker routine (running in background, in another process, based on a CRON expression or whatever…) which takes care of synchronizing our cached version of the ledger with the real ledger belonging to Truly Awesome Bank. This way we can provide responses quickly, regardless of how many requests Truly Awesome Bank is able to support at a given time.

We are then gaining on performance and stability, since we don’t need to wait for external data sources. This makes the architecture on the whole more fault tolerant towards external services and thus opens new resilience possibilities: we could, for example, implement simple retry strategy or even a circuit breaker without affecting the client at all…

The price we are paying though is consistency: before worker completes the synchronization process real data (as in data living in Truly Awesome Bank) and data we serve (as in data living in the Cache) are different and the thing can get a lot more complicated if we start thinking about how to deal with error cases².

Write Around

Well, just for sake of completeness we ought to mention Write Around, but to me it doesn’t look like a real pattern. In fact, in the following diagram you won’t find any trace of the word “cache”.

Basically, Write Around is “call directly Data Accessor and cache data only at read time” which to me means “apply any reading strategy without a writing one”.

Rationale

The reason why you would use this non-pattern is just because none of the writing techniques above are good for you: maybe you need to have super consistent data or maybe you don’t need to read data that often.

In those cases not applying a writing technique (or using Write Around, if you wish) works just fine.

Did you write some code?

You can find a more detailed version of these examples here

Yes, I did. Python this time around.

The example I am providing here is simulating a slow writing external service using timers. In particular, we are about to simulate more or less what happens in TrulyAmazingBankAPI: we create a transaction we want to save.

Launch the app and in some seconds you are able to see exactly the trace of what happens during the Write Through and the Write Behind cases.

Let’s examine the output case by case.

Write Though

>>> Save transaction
[14:59:17.971960] CacheManager.set
[14:59:17.971977] TrulyAwesomeBankAPIClient.save_transaction
>>> Get transaction
[14:59:19.974781] CacheManager.get

Here the first thing we do is saving the entry in the Cache, then we save it in the AwesomeBank and when after a couple of seconds we want to get the transaction we have just saved, we are using the Cache to retrieve it.

Write Behind

>>> Save transaction
[14:59:24.976378] CacheManager.set
>>> Get transaction
[14:59:21.978355] CacheManager.get

--------------------------------------------
|    AWESOME BANK DATABASE (before sync)   |
--------------------------------------------
{}

[14:59:26.974325] TrulyAwesomeBankAPIClient.save_transaction

--------------------------------------------
|    AWESOME BANK DATABASE (after sync)    |
--------------------------------------------
{
   UUID('0f41f108-0859-11e9-a138-b46bfc6c5cb9'): {
      'id': UUID('0f41f108-0859-11e9-a138-b46bfc6c5cb9'), 
      'transaction': {
         'type': 'PAYMENT', 
         'amount': 100, 
         'currency': 'EUR'
      }
   }
}

If we call request the couple of actions “set transaction” and “get transaction”, we can see from the output that during the whole life of the request the only involved participant is CacheManager.

The sole moment when we are calling the TrulyAwesomeBankAPIClient is 5 seconds after the end of the request, when we are completing the synchronization.

Please note that also the synchronization is a process purposely dumb and slow because of timers here. In real world synchronization process can be (and usually is) way more complicated than that and, in fact, it should be a major concern when data consistency is a game changer.

After synchronization, as you can see database is up to date with what we have in Cache. From this point on this entry is up to date and it will always be, until other writing actions happen.

Final words

Well, this closes active caching part.

First thing, thanks for feedback on previous article! Apparently naming wasn’t so clear, so I updated it a bit here. I took the opportunity to revisit diagrams as well so that they won’t make you eyes bleed. Not that much at least.

Until next time!

Introduction

It took me just three episodes to become inconsistent in my writing schedule. It has to be a record of some sort. To keep me motivated though I decided to spend the season back in Italy, so that I desperately needed to practice some English.

Well it’s not entirely true: I am passing the season here because of food. As usual, this leads me to this article’s topic: caching.

Readers right now are probably divided into two groups: the one knowing the famous joke about caching and the others. For both of you here’s a curated list of tremendously sad variations of it.

Needless to say, I find all of them hilarious.

Either way, this piece is going to be part of a Christmas series about caching techniques. I am about to cover active caching (as in, what I can do to cache without suffer too much) and passive caching (as in, how to stick with browser cache and similarities).

This article is the first in the Active Caching part.

What is this about?

Do you still wonder what has food to do with caching? You’d better do, else I need to seriously improve my cliffhangers skills.

Example: Christmas Dinner

Let’s start with a simple out-of-IT problem. It’s Christmas eve and you’re planning to arrange a mouthwatering dinner for you friends and family. For the sake of the argument we’re going to use one traditional Italian Christmas recipe: “il capitone”¹.

Let’s start cooking. First thing in the list of the ingredients is the eel. You call your favourite fish shop, you get your fish delivered. Second item, extra-virgin olive oil. You call your favourite farm, order a bottle of oil and you get that delivered. Third, lemon…

You can see by yourself how inconvenient this is, don’t you? What you start doing then is buying in advance and storing stuff in a more convenient place, closer to where you actually use it, to make the access to these ingredients more efficient. Let’s call this place cupboard.

Once you realize you can store things at home, you might be tempted to call the delivery person just once to collect all the ingredients not only for Christmas but also for New Year’s Eve’s dinner. So when you are at the fish shop, you buy the eel and the king prawns which you are actually planning to prepare a week later.

After a couple of days, the funky smell killing any living being in the area makes you realize that probably prawns are now expired and you should have prepared them fresh.

Well, caching has exactly the same kind of problems and perks: we usually cache items to save some computations, time or to avoid calling uselessly an external data source, but we should be extremely careful about expiration of entries because they can eventually get to an inconsistent (and very smelly) state down the line.

Caching patterns

As usual, let me introduce some jargon² which will help us in communication before diving into the patterns (maybe strategies is a better suited word here).

These are the participants:

• Client:
  • needs data (either fresh or from the cache);
• Data Access Component:
  • is called to get non-cached entries (e.g., HTTP Client, ORM…);
• Cache Layer:
  • stores cached entries (e.g., Memory, Local Storage…);
• Resource Manager: communicates with the Cache Layer.

In our previous example, these roles are mapped this way:

• Client is you;
• Data Access Component is the delivery person;
• Cache Layer your cupboard;
• Resource Manager someone so kind to administer resources in your cupboard.

Caching involves both reading (using the ingredients) and writing (storing the ingredients), so categorization follows accordingly. In this article we’ll speak about reading techniques.

Reading strategies:

• Cache Inline
• Cache Aside

Writing strategies:

• Write Through
• Write Behind
• Write Around

Warning

Unfortunately naming convention for these patterns is not that consolidated, so you can find them under different names.

To get an understanding of how does work and why we should use them, we will analyse the following scenarios for all the aforementioned patterns:

• cached entry is present and valid (Cache Hit);
• cached entry is missing or invalid (Cache Miss).

Disclaimer

As usual, we are tackling these strategies in isolation for sake of simplicity. In real world, those techniques are combined to get the best out of them.

Cache Inline (aka Read Through)

The reason for this name is that in this pattern the Client is never responsible of calling the Data Access Component directly, but instead it delegates the responsibility of knowing whether a cached entry is enough or a fresh entry is required to the Resource Manager.

Resource Manager then sits in line between Client and Data Access Component.

Cache Miss

Following the numbers on the arrows, you should easily get a grasp of what’s going on here:

1) Client asks Resource Manager for data; 2) Resource Manager gets no cached entries from cache, so it calls Data Access Component; 3) Resource Manager gets data, stores it and then returns it to Client.

Cache Hit

As you can see, using cache here is reducing the number of steps, hence the strategy is actually working!

Rationale

From a caching standpoint, this approach makes sure that we are caching only data we actually use. This is usually called lazy caching. This approach also promotes splitting responsibilities across different components, how can it have drawbacks?!

Well, unfortunately this is the case :(

The first issue is of course that, when you are in a Cache Miss scenario, the request has to do a longer trip before getting to the Client, making the first request actually slower than if we didn’t have cache at all.

One way of dealing with this is doing a cache primer: when the system starts we pre-populate the Cache Layer so we’ll always be in a Cache Hit case. Obviously this will make our caching mechanism not-so-lazy. As always, what’s best depends on the actual scenario.

The second drawback is that, since data is cached only once (on Cache Miss) data can become quickly stale.

Again, this is not the end of the world: as for food, you can set expiration for entries. It is usually called TTL (namely Time To Live). When entries are expired, Resource Manager can call again the Data Access Component and refresh the cache³.

Cache Aside

As opposed to Cache Inline, Cache Aside will make the Client responsible of communicating with Cache Layer to understand if a Cache Entry is needed or not.

The pseudo code for this behaviour can be as easy as:

class Client {
    CacheLayerManager cacheLayerManager;
    DataAccessComponent dataAccessComponent;

    getResource() : Resource {
        const resource = this.cacheLayerManager.getResource()

        return !resource
            ? this.dataAccessComponent.getResource()
            : resource
    }
}

Cache Miss

You can follow what’s going on here by looking at the pseudo code above. As you can see, responsibility of calling Data Access Component is now in the Client and the Cache is actually… aside.

Cache Hit

Again the trip here is shorter, so the pattern is actually working.

Rationale

This technique, as Cache Aside, is a lazy caching technique, unless we want to do a cache primer. Also, exactly as with Cache Aside, there is the problem of stale data, but again that problem can be tackled with TTL.

So, why should anyone go for Cache Aside over Cache Inline?

Since the Client now is responsible of communicating directly with the Cache Layer, when the Resource Manager fails, we pay a penalty only on the first request - when we go through the Cache Miss path -, making our system on the whole more robust.

Also, having removed the dependency between what we cache and what we get from Data Access Component, we could potentially have two different kind of model: a Model, which is representing what we get from Data Access Componentm and CachedModel representing what we cache.

This will indeed widen the spectrum of what you can achieve with cache: you can, for example, hydrate or transform cached data to gain on performance on multiple operation with just one cached entry.

Let’s give an example of this.

Suppose you are serving a list of bank transactions you get from this AwesomeBankAPI. Your application is supposed to expose two different endpoints: getAllTransactions and getPayments. Of course AwesomeBankAPI does not expose any filtering function. What you could do is storing the the list of all the transactions on the first call to any of those endpoints.

From this point on, if the call is towards getAllTransactions, you return the list as is. If the call is towards getPayments you will take the whole list from cache (rather than calling AwesomeBankAPI again) and you just need to do the filtering on your end.

Code or it never happened

You can find a more detailed version of these examples here

The example I am showing here is written in Node. It’s a simple application meant to communicate with XKCD to fetch latest comics.

CacheLayer in this example is represented by a simple Map. I am using a CacheManager to deal with it, so that if you want to experiment with a real caching engine (like redis, or memcached) you can do that without much effort.

The DataAccessComponent is represented by a simple XKCDClient which exposes (in a Vanilla JavaScript fashion…) only a getLastComics method.

The other component is indeed ResourceManager which is being used only in the inline-caching example.

Since all these components are eventually the same, I just created two different clients sharing and using them in different ways, based on the strategy we want to follow.

The Cache Inline example is about requesting twice the same resource (namely, last three XKCD comics), but the second time the request is way faster. This is because we are not doing any cache-primer, so the first time we are actually calling XKCD API, the second time we are retrieving information from the cache.

The Cache Aside example instead, shows how powerful can be caching when we want to request resources which can calculated from what we already have. In this specific example, we are fetching last five comics from XKCD and then we are fetching only last two. The second call of course is not calling the API.

The main difference here is then that we are using the cache to get a resource we didn’t have before, rather than using CacheLayer to get something we already fetched.

Again, those two strategies can (and usually do) live together. If you want to play a bit with these examples, you might try to make the ResourceManager from the first example a bit smarter so that it can either use the entries as they are (hence, what’s already in the repo) or it can try to extract the required info from CacheLayer and decide whether calling the API or not.

Final words

This closes the first episode of this Christmas special (yes, as TV shows).

As you might have noticed I am trying to keep this shorter and easier than usual, so you can easily follow without your laptop when you are hallucinating because of Christmas-sized food portions.

As always, if you have any feedback (the thing is too simplified, you miss my memes, I suck at naming things), please drop a comment and make this better together :D

Until next time!

As some of you may remember, in the pilot episode I said I was about to explain Command with three examples: a UI kit, a CQRS application and an undo/redo implementation in Electron. In the Command episode though I didn’t provide the latter and the reason is extremely simple: I am a jerk.

Furthermore, it made much more sense to me using that example to explain another Behavioral Pattern¹ belonging to the classic patterns in the Gang of Four: Memento.

Memento

Example: Calculator

Suppose you are working on a calculator. You provide an expression and it will do the maths for you. For simplicity’s sake, we just take in account one of its methods: power.

The logic behind this calculator is in a class called Calculator which should look something like:

class Calculator {
    // State
    private string display;
    // and a whole lot of unrelated other fields

    // Resolves expressions like x^y
    private power(string expression): number;

    // Writes on display
    setState(string display): void;

    // Parse what's on the display, calculates and overrides the display
    calculate(): number;
}

One fine day, we decide it’s time to implement an undo mechanism for this application. One first idea of implementing this mechanism could be simply apply the inverse function of what you just did.

Unfortunately this just does not work for the power function.

For example: undoing y = power(x, 2) is going to be applying sqrt(y, 2), but both power(2, 2) and power(-2, 2) yield the same result, so you won’t be able to get unambiguously to the x just by having the y.

At this point saving the previous state in a snapshot when you calculate and, upon undo, using such snapshot to reset the state of the calculator looks simpler and more effective.

Memento offers one neat way to deal with this problem.

What is this about?

Intent

Without violating encapsulation, capture and externalize an object’s internal state so that the object can be restored to this state later.

Yes, you have just won this “Guess the quote” round: it comes from the Gang of Four.

The idea here is pretty straightforward: we want to have a systematic way to store a snapshot of the internal state a given object, without exposing such state, in order to be able restore later on.

If you are wondering why you shouldn’t expose the state, maybe you are still not fearing coupling as you should. This is definitely bad. However, you are still in time to get this fixed by reading this article. I will wait for you here.

…

Done? We can get started with Memento in practice.

Pattern in practice

First things first: why this pattern is called Memento? Memento is a Latin word which can be safely translated into reminder². This is the object in which we store the part of the state of the Calculator we are interested in.

Calculator, which is where the state originates from, is called Originator and the third character of this story is going to be the one which takes care of making the whole thing work, which is called the CareTaker.

So, to wrap it up, these are the participants in Memento with their responsibilities:

• Originator:
  • creates a Memento to store the internal state;
  • uses Mementos to restore its state;
• Memento:
  • stores an immutable snapshot of the internal state of Originator;
  • can be accessed only by the Originator;
• Caretaker:
  • stores Mementos;
  • never operates on or read Mementos;

In practice these will become something like:

// Originator
class Calculator {
    private string display;

    private power(string expression): number;
    
    setState(string display): void;
    calculate(): number;
    save(): Snapshot;
    restore(Snapshot snapshot): void; 
}

// Memento
class Snapshot {
    private string state;

    getState(): state;
}

// CareTaker
class Application {
    Calculator calculator;
    Array<Snapshot> undoSnapshots;
    Array<Snapshot> redoSnapshots;

    calculate(): void {
        const snapshot = this.calculator.save()
        this.undoSnapshots.push(snapshot)
        this.redoSnapshots = []
        this.calculator.calculate()
    }

    undo(): void {
        const snapshot = this.undoSnapshots.pop()
        this.redoSnapshots.push(snapshot)
        this.calculator.restore(snapshot)
    }

    redo(): void {
        const snapshot = this.redoSnapshots.pop()
        this.undoSnapshots.push(snapshot)
        this.calculator.restore(snapshot)
    }
}

Nice! How can I use this s**t tomorrow?

With Memento we are kind of lucky: you don’t need to find super complex use cases to go for it. The undo/redo scenario is by far the most common place where this pattern shines, but it can easily be reused every time you need to revert an object to a previous stage.

You need another example, don’t you?

Suppose you have a profile age for a web application. The user clicks on “edit profile” but, after doing some things, they “cancel” the operation. Unless you wan to do the AJAX call to re-get user information every time this happens, a good idea can be storing a Memento containing a snapshot of the user profile to be restored upon cancellation.

Is Memento the only way to achieve this? No. Another fairly common pattern to go for in these cases is Prototype, which might be the subject of next episode. Or not, who knows? Either way, all you need to know now about Prototype is that it provides another way to create a copy of the state of an object, but in a different manner.

Bottom line, taking snapshots makes your life easier when you have to time-travel the history of your objects.

Your next question could be, is this just convenient or it is necessary? We have seen in the Calculator example that sometimes inverting last action could not be enough to get to the previous state. This is unfortunately true not only with non-invertible maths functions, but it applies every time any of your methods has side effects. In these cases usually taking snapshots is the only way to revert to a previous state safely.

Well, where’s the catch then?

This pattern has a couple of gotchas you should be very aware of.

The first and most obvious one is that, if the object you want to restore is big, having a history of snapshots can become cumbersome. One way to work this around is storing just a diff of the changes, but this works only in scenarios in which you know exactly the order of snapshots to apply (for example in undo/redo).

The other, sneakier, is that snapshots, if not created correctly, can easily create and accumulate errors upon traversing the history. Let’s give an example of this case.

Let’s suppose you have the dumbest game ever: every time you click a button you earn 10 points, if score gets to 100 you earn a badge. We want to implement an undo mechanism here, so we store snapshots on every click of the score variable.

We click up to 100, we earn a badge, we undo, we re-click and we earn a second badge.

Why did that happen? Because we forgot to keep track of the badges in the snapshot, thus on undo we just reverted the score, without cleaning the badge list.

A little less conversation, a little more action, please

You can find a more detailed version of these examples here

Finally code time!

As I promised in the introduction, I am about to show how the same undo problem can be solved both via Command and via Memento.

Disclaimer

I decided to not use Electron for this example for the simple reason that it makes the whole thing more complicated for people not familiar with it and it’s not bringing any value to Electron experts. If you’re really upset about this, drop a comment and I will add also that example.

The example is a very simple React application which is supposed to be a game: sort the tiles to win.

It basically sets a listener on keyDown and based on that it either calls a method (Memento) or issues a command (Command).

In the Memento example we have the Game component which is dealing with all the game logic: moving tiles, selecting tiles, calculate if the user is winning… This makes it the perfect Originator, because it’s also where we store the state we might want to revert via undo. Being the Originator also means that it’s responsible of creating and restoring the Snapshots.

Snapshot is of course Memento and it’s “private” to the Game ES6-module, to prevent the KeyboardEventHandler (aka the CareTaker) to know it.

In the Command example, we have an additional component: CommandManager acting as Invoker. Roles of Game and KeyboardEventHandler are unchanged, but given the different implementation, they are doing things differently. Game now is the Receiver of the command, whereas KeyboardEventHandler is the Client, the sole owner of Command.

As you might already have noticed, we can use interchangeably Command and Memento here because the action we are encapsulating (moveSelectedTile) is a pure action, with no side effects, so we actually don’t necessarily need a Snapshot to reconstruct the state: applying inverse functions is enough.

Does this mean that Memento and Command cannot live together? By no means. As a matter of fact, you can encapsulate in a Command the takeSnaphot method to decouple the CareTaker and the Originator. Or also, you can encapsulate moveSelectedTile - as we already did - and in the Command, besides executing the method, you also take a snapshot. This last one is the most common way to make Command and Mememto live together.

You can start from the repo and experiment with it as an exercise. If you’re evil and want to spoil everyone else’s party, you can submit a PR.

Final words

Well, things start to become a bit more exciting as we start adding knowledge and mixing cards on the table. This will definitely improve over time, so hang on for it :D

If you have any sort of feedback (“Don’t tell me how to code. You’re not my real mom!”), opinion (“You code like shit, but your memes are awesome”), comment (“Yeah, okay, Behavioral Patterns are cool, what’s next?”), please drop a message or a comment and let’s make this series better together.

Until next time!

As spoiled in the introduction, the first article will be about the Command Pattern. This pattern is one of the classic patterns you can find in the Gang of Four and it belongs to the set of patterns called Behavioral Patterns.

Behavioral Patterns

As the name suggest, behavioral patterns are concerned about behavior of objects.

Unlike other kind of patterns, behavioral patterns are not only patterns of objects and classes, but also pattern of communication between them. Their main purpose is to outline and distribute responsibilities across components in the application using abstractions meant to simplify complex control flow.

This last sentence was complicated enough to deserve a real life example.

Let’s say you are in a restaurant and you want to eat a juicy T-Bone steak (I guess now it’s obvious I have something for food). One way of getting that is to stand-up, going into the kitchen, and asking the chef to prepare a steak for you. At that point you realize that the kitchen is full of people with the same bright idea which are ultimately creating chaos and confusion in kitchen staff. Only one thing can be worse: your former girlfriend/boyfriend, yes the one with a thing for poisons, is the chef.

As a matter of fact, a customer is only interested in getting food. Direct communication with the chef is not serving this purpose and it’s actually only bringing problems. At the same time, this direct communication does not scale when you have multiple requests and it wouldn’t even when you have multiple listeners for those requests. This is a perfect example of the kind of problems that coupling can bring in software development.

The good news though is that even before software development was invented, human beings found a way to solve this obnoxious issue: placing orders.

Let’s suppose, for the sake of the argument, to have a mailbox attached to the kitchen door. Whenever you want to have your food, you just write everything you need on a piece of paper and you mail your order.

This simple trick magically solved our issues. We are not forced to know who is cooking our food. We don’t even know whether anyone is actually cooking our food or if they buy-resell, for example. This means a huge gain in flexibility (and maybe a bit of loss of trust in restaurants which work this way). Furthermore, this improved the whole process in the kitchen, as they can prioritize, prepare concurrently, throw in the bin, log or do whatever they want with the orders.

Everyone (panda included) lived happily ever after¹!

Oh, by the way, this was the Command Pattern.

Command Pattern

What is this about?

Lets start with a quote from the one and only GoF.

Intent

Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undoable operations.

In substance, Command is all about encapsulating a routine in an object. In the example above, we encapsulated the request for food in an object, which was the piece of paper used to place the order. The encapsulating object is what we call Command, hence the name of the pattern².

Effects

Applying command has mainly two effects: reducing coupling between the invoker and the executor of the command, make a routine a first class object.

The ex scenario in the example above should be enough to convince you that coupling can be dangerous even outside Computer Science.

If you’re not in the mood for thinking about your paranoid acquaintances you can also consider that the procedure you had to fulfill to get your meal is essentially unchanged if your meal needs to be cooked by two teams one specialized in steaks and one in sides.

At the same time, the kitchen staff does not care if the order comes from the waiter, from a phone call, an order or whatever. As long as they receive a command they can execute, they are fine.

This is just a part of the gain we have in transforming routines in objects. The best part is… wait for it… they are objects! That means you can manipulate routines as objects, as in you can store them to have a transaction history, you can delay the execution, you can ignore them if s**t comes out of the pipe, you can extend those to add debugging inspections, you name it!

Awesome! Will I ever need this in my lifetime?

No.

There are some situations in which Command is not only extremely handy, but almost needed.

Callbacks

Every time the executor of a command and the issuer not only they don’t know each other, but they cannot know each other in advance.

Let’s say you are developing a fancy UI kit. You are of course developing something that needs to be reused, so if you build a Button component, you want it to be able to execute any action, you don’t want to hard-code one.

“Hey, bro! We have callbacks for that!” Yes, I know, but not everyone in the world is so lucky to work with JavaScript on a daily basis (sorry, biased comment). When you want to (or have to) be strictly Object Oriented, this is the way to implement callbacks.

Transactions and logs

Having all the commands as first class objects allows you to store them and hence to create an history of transactions.

This comes extremely handy in systems in which you need a transaction history, like banking, for example. Furthermore, you get another pleasant side effect: you can reconstruct the state of the system at any point in time just traveling back the transaction history, making your life extremely easier if something goes off.

You can of course do the other way around: instead of storing the commands after executing them as a reference for what already happened, you can make the list of commands a queue of task to be executed, as within the restaurant example.

If you need more “workforce”, you just need to add some more consumers for that queue, making your application on the whole more scalable.

Undo/Redo

Making the execution of an action an object, allows you to create an object with two methods: execute and undo. The first is meant to do something, whilst the latter is supposed to undo what you have just done.

Add up what’s above about transactions and you can easily build and undo/redo history.

One last effort before code…

Before diving into code examples we need to build a bit of jargon, so we can understand each other. I will be using the exact same language as used in GoF, so that if you want to follow from there it will be easier.

The participants in this pattern are:

• Receiver:
  • knows how to execute the command;
• Command:
  • declares the interface for executing an operation;
• Concrete Command:
  • defines the binding between the Receiver and the action to execute;
  • invokes methods on the Receiver to fulfill the request;
• Client
  • creates the Concrete Command and sets its Receiver;
• Invoker
  • issues the request to execute the command;

In the example restaurant example we would have:

• Cook as Receiver
• Order as Concrete Command
• Restaurant as Client
• Customer as Invoker

Some pseudocode to look a bit more serious:

interface Command {
    function execute()
}

// Concrete Command
class Order implements Command {
    Cook cook;
    Meal meal;

    execute() {
        cook.prepare(meal);
    }
}

// Receiver
interface Cook {
    function prepare(Meal meal)
}

// Invoker
class Customer {
    Order order;
    Meal meal;

    mailOrder(Order order) {
        order.execute()
    }
}

// Client
class Restaurant {
    Cook cook;
    Customer customer;

    main() {
        order = new Order(cook, customer.meal)
        customer.mailOrder(order)
    }
}

Code examples

You can find a more detailed version of these examples here

Frontend: UI kits

Following the first example above, here you are a simple example of how you can use the Command Pattern on the frontend. I have chosen to not use any framework, as the idea is general enough to be applied also to vanilla JavaScript.

In this example we will just create and render a Button component (Invoker) which will execute an OpenAlertCommand (Concrete Command). The Window (Receiver) is actually responsible for doing the job, whilst Application (Client) is wrapping everything up.

gist:shikaan/77367e98e41351549bec891fbf626b43

You may argue that doing the same thing without the pattern would have taken less then 10 LOC. You are actually right, but, for the reasons we discussed earlier, this scales better and will be more flexible when you will get new requirements.

In the repo we are actually proving how more flexible this is, adding to this example a couple of other things: we reuse the same button with the same command with two different receivers, we use the same button to trigger two different commands at the same time.

Backend: CQRS in Python

A good introductory article on the matter is here.

The following example will contain a super simple CQRS application written in Python. It’s supposed to be a banking app in which you can only deposit and get the list of all the deposits. Everything is stored in memory and will vanish as soon as the process ends.

The architecture of the app, even though it’s super basic, contains everything you need to call it a CQRS app.

Strap yourselves because here we have two concurrent implementation of the Command Pattern: one for writing (Command) and one for reading (Queries). Both share the same Client though.

1) The Application (Client) creates the Deposit command and calls the handle_deposit method on the Command Handler (Command Invoker) 2) The WriteStore (Command Receiver) saves data 3) Right after the Command Handler fires an event to notify the ReadStore (Query Receiver) which updates 4) The Application (Client) then creates the GetLastDeposit query and calls the handle method on the QueryHandler (Query Invoker) 5) The ReadStore (Query Receiver) will then save the value into the query 6) The result stored in the query returns to the user

The code for this is of course available in the repo. Python is not my main language, so if you see something off, feel free to submit a pull request or open an issue there.

Final words

Well, this has been massive. Hopefully you got to read at least half of what I have written :D As always, if you have any feedback about how to make this series better, please let me know.

Until next time!

Design Patterns are quite an hot topic in software development. For many people they are considered to be the way to identify a well prepared developer. Luckily, I am not one of them, although I think that they definitely contribute to make developers better allowing them to tackle everyday’s challenges in a quicker and, often times, cleaner way.

This is exactly the reason why I want to write articles about Design Patterns based on what I learned mainly from the Gang of Four.

The difference between this and the overflowing amount of other articles doing the same, is that I will be trying to stick with full stack web development with extremely practical examples. Most of them are going to be in JavaScript or Python, as other languages have plenty of resources about this topic.

Something along the lines of: How to use Command Pattern in a React component, in a CQRS Node application and to implement an Undo/Redo history in an Electron application.

However, this first article is going to be the Pilot Episode of the series. So still no patterns in here :(

Let’s get started!

If you want to know more about design patterns in general I can recommend this website which is my go-to place when I need to dust off those concepts.

What is a design pattern?

As much as everyone of you claims to be the best cook in the world because of their special, unique, one-of-a-kind touch (well, maybe this affects Italy more than other places…), we can all agree that having a grandma-crafted recipe book can take a good cook out of almost everyone.

The reason is pretty straightforward: all those recipes have been created by someone who - eventually making a huge amount of mistakes along the way - fixed, corrected and amended those procedures over time. Using those well packaged bits of knowledge makes you avoid lots of common pitfalls and wrong decisions. This is extremely useful in circumstances when the choice you make looks unharmful, but in reality it is not. Something like of serving a poorly prepared dish to your grumpy uncle for the Thanksgiving Dinner…

At the same time recipes can be used as a template to build upon rather than as a set of rules carved in stone. There are plenty of extremely good chefs which revisit their family cookbook to make a business out of it or, in general, to serve their purposes which might be different from their grandma’s ones.

In software development the whole thing works pretty much the same way. The main difference though is that software development projects usually last more than a bunch of minutes and you cannot get away with brushing your teeth at the end. The main ideas are the same, though: having a very strong starting point to solve common problems which you might want to customize when you get to an expertise level which allows you to do so.

Criticism

As for all the things which are too good to be true, this has to be either not so good or not so true.

The good news is that this is true. The bad news is, though, that your decision-making process cannot completely be replaced by The Wisdom of the Ancients.

This is by far the most common argument raised against the pattern approach in software development: solutions provided via patterns tend to be not as efficient as they could be for very specific problems.

To me this is kind of a weak point as you should always improve on or at least adapt one of those solutions to your needs. Being backed by something which passed the test of time will give you the advantage of knowing in advance most of the weaknesses of you choice, so you have a better understanding of how to address issues coming down the line.

The other common argument against design patterns is that some of the classic ones (aka in the Gang of Four) exists only because of the state of software development in those days, which was a bit more “primitive” compared to what we have today.

Well, I cannot disagree with this, but (as Francis up here says) “Knowledge is power” and I’d rather have a tool I don’t use than lacking a tool I need.

This, however, leads to the last criticism I want to address here. One of the risks of introducing patterns is that you might end up using them even in situations which do not require them at all.

I guess this is something we cannot help and it’s a fairly common problem with anything which is learned in schemes (e.g., when you start learning scales in music). Unfortunately, experience is the best teacher in this case, but being aware of the risks will definitely help you throughout the way.

Classification

As you might have understood by now, the Gang of Four was really the s***t when it came out (which is, by the way, 1995).

So nowadays, we’re still somewhat classifying design patterns based on their classification.

The following list will become a list of links as long as I write articles on the subject

Creational Patterns

• Abstract Factory
• Builder
• Factory
• Prototype
• Singleton

Structural Patterns

• Adapter
• Bridge
• Composite
• Decorator
• Facade
• Flyweight
• Proxy

Behavioral Patterns

• Chain of responsibility
• Command
• Interpreter
• Iterator
• Mediator
• Memento
• Observer
• State
• Strategy
• Template method
• Visitor

Final words

This was a brief and hopefully not-so-boring general introduction to Design Patterns. Next articles will be more practical, less wordy and maybe with the same amount of memes. Let me know if you are interested in the topic, as I really need motivation to continue writing :D