Max Desiatov

Introduction to structured concurrency in Swift: continuations, tasks, and cancellation

Thu, 14 Jan 2021 12:40:32 GMT

This article is a part of my series about concurrency and asynchronous programming in Swift. The articles are independent, but after reading this one you might want to check out the rest of the series:

How do closures and callbacks work? It’s turtles all the way down
Event loops, building smooth UIs, and handling high server load
Introduction to structured concurrency in Swift: continuations, tasks, and cancellation

IMPORTANT: This article is about an experimental feature, which is not available in a stable version of Swift as of January 2021. APIs and behaviors described in this article may change without notice as new development snapshots become available, but I will try to keep sample code updated as we get closer to general availability of structured concurrency in Swift.

There are many discussions of the imminent introduction of async/await to Swift. The authors of Swift concurrency proposals have done monumental work in preparing all of the related features. And there are many of them. Just have a look at the actual “dependency tree” of the proposals:

Around the time async/await proposal was accepted, I saw people asking almost the same set of questions: how to convert legacy APIs to async? How an entrypoint to async code would look like? While examples of usage of async/await in UIKit apps were shared around, there were no good examples that utilized the structured concurrency proposal. I wanted to have a look at some minimal isolated code snippets that could help me answer these questions.

Setting up a SwiftPM project

Turns out, it’s relatively easy to set up a CLI project with SwiftPM that uses async/await. Please feel free to clone the final result from GitHub to follow along. The README.md file in the repository also contains important installation steps, as the standard toolchain supplied in the latest stable Xcode currently won’t work. You’ll have to install a development toolchain as described in the document to run this example code on your own machine. In the rest of the article I’m going to review this example project piece by piece.

Compiler flags

Notice how the target needs to be declared in Package.swift:

.target(
    name: "ConcurrencyExample",
    dependencies: [],
    swiftSettings: [
        .unsafeFlags(["-Xfrontend", "-enable-experimental-concurrency"]),
    ]
)

Until Swift concurrency features become stable and enabled by default you have to pass these flags when building. They are declared in the package manifest here so that you don’t have to pass them each time manually when building the project.

Imports

When using structured concurrency to expose legacy callback-based APIs as async functions, you currently have to import the _Concurrency module supplied with the latest Swift dev snapshots. The name of it starts with an underscore to highlight that the module is experimental and its API may change.

Reviewing the code

Continuations

While most of Apple’s APIs will be converted to async/await automatically, your own callback-based code can be converted using a few helper functions, such as withUnsafeContinuation and withUnsafeThrowingContinuation. They take a closure with a single continuation argument, and you’re supposed to call your callback-based code from this closure, capture the continuation, and call resume on it when you’re finished. Here’s how the declarations look for the non-throwing variant for more context:

struct UnsafeContinuation<T> {
  func resume(returning: T)
}

func withUnsafeContinuation<T>(
    operation: (UnsafeContinuation<T>) -> ()
) async -> T

One of the most simple but practical enough example of a non-throwing async call is sleep:

import _Concurrency
import Dispatch

func sleep(seconds: Int) async {
    await withUnsafeContinuation { c in
        DispatchQueue.global()
            .asyncAfter(deadline: .now() + .seconds(seconds)) {
                c.resume(returning: ())
            }
    }
}

And here’s a throwing variant:

struct UnsafeThrowingContinuation<T, E: Error> {
  func resume(returning: T)
  func resume(throwing: E)
}

func withUnsafeThrowingContinuation<T>(
    operation: (UnsafeThrowingContinuation<T, Error>) -> ()
) async throws -> T

Based on that we can convert URLSession.dataTask to a throwing async function:

import Foundation

struct UnknownError: Error {}

func download(_ url: String) async throws -> Data {
    print("fetching \(url)")
    return try await withUnsafeThrowingContinuation { c in
        let task = URLSession.shared.dataTask(with: URL(string: url)!) { data, _, error in
            switch (data, error) {
            case let (_, error?):
                return c.resume(throwing: error)
            case let (data?, _):
                return c.resume(returning: data)
            case (nil, nil):
                c.resume(throwing: UnknownError())
            }
        }
        task.resume()
    }
}

Here the continuation c argument of the closure passed to withUnsafeThrowingContinuation becomes your “callback”. You have to call resume on it exactly once with either a success value or an Error value. Multiple calls to resume on the same continuation are invalid, since async functions can’t throw or return more than once. If you don’t ever call resume on the continuation you’ll get a function that never returns or throws, which is just as wrong as throwing or returning more than once.

The entry point

As you probably noticed, in previous examples we got async functions, but how do you actually call them from non-async code? Currently, the runAsyncAndBlock function is an entry point you would use to interact with an async function from your blocking synchronous code:

runAsyncAndBlock {
    print("task started")
    let data = try! await download("https://httpbin.org/uuid")
    print(String(data: data, encoding: .utf8)!)
}
print("end of main")

Note that in the current toolchain (DEVELOPMENT-SNAPSHOT-2021-01-12-a at the moment of writing) runAsyncAndBlock does not take throwing closures as arguments, thus try! or do/catch blocks are required to call a throwing async function such as download.

The print statements here are added so that you can observe the execution sequence and to make sure that your async code is actually called.

Remember that you should not use runAsyncAndBlock in your GUI code running on the main thread, as it will block the event loop from processing any input from your user. This will result in your app being frozen until the async closure body has finished. In a CLI app that doesn’t expect any input this is fine though. In GUI apps you’d either have to call runAsyncAndBlock on a background thread that can be blocked, or use async handlers or actors to host your async code. Given that proposals for async handlers and actors aren’t available yet, we’re leaving those advanced topics out, and focus on a simple command-line app here.

Launching concurrent tasks with “async let”

Let’s say you need to fetch UUIDs for multiple entities, but you can only get a single one through an asynchronous call. In some naive implementation you would await for async calls repeatedly one by one until you fetch all of the data. This is highly inefficient if these calls are independent and can all run simultaneously without disrupting each other.

You can launch multiple async tasks concurrently with async let declarations. Then if you need to wait for all of them to complete, just use a single await marker on both of the values that were declared with async let:

func childTasks() async throws -> String {
    print("\(#function) started")

    async let uuid1 = download("https://httpbin.org/uuid")
    async let uuid2 = download("https://httpbin.org/uuid")

    return try await """
    ids fetched concurrently:
    uuid1: \(String(data: uuid1, encoding: .utf8)!)
    uuid2: \(String(data: uuid2, encoding: .utf8)!)
    """
}

Here two separate uuid1 and uuid2 tasks are launched concurrently, and they don’t block each other. The try await markers before print mean that print won’t evaluate before both of the tasks have completed. Compare this with the old Dispatch approach, where instead of async let you’d have to set up a DispatchGroup instance, which is much more cumbersome to work with.

Cancellation

Tasks launched with async let are called “child tasks”, and this is important when you think about cancellation. async let forms an implicit task hierarchy which reflects call stacks of async functions. In the code above await childTasks() launches one parent task, which then spawns two more child tasks for download calls. When a parent task is cancelled, its child tasks are cancelled too.

The most critical thing to highlight is that cancellation with Swift’s structured concurrency is cooperative, i.e. tasks need to “cooperate” in an explicit way to get cancelled as early as possible. This is done with checkCancellation() and isCancelled() static functions declared on the Task type from the _Concurrency module:

extension Task {
  /// Returns `true` if the task is cancelled, and should stop executing.
  ///
  /// This function returns instantly and will never suspend.
  static func isCancelled() async -> Bool

  /// The default cancellation thrown when a task is cancelled.
  ///
  /// This error is also thrown automatically by `Task.checkCancellation()`,
  /// if the current task has been cancelled.
  struct CancellationError: Error {
    // no extra information, cancellation is intended to be light-weight
    init() {}
  }

  /// Check if the task is cancelled and throw
  /// a `CancellationError` if it was.
  ///
  /// This function returns instantly and will never suspend.
  static func checkCancellation() async throws
}

Why do you need to call these functions instead of the concurrency runtime just cancelling tasks automatically? The runtime doesn’t know what your task is doing, it may need to save and close a file handle, save the state of an expensive computation, or do whatever cleanup is needed. Cancelling tasks preemptively would lead to much more complexity, while forcing tasks to account for possible cancellation at any arbitrary line of code.

A try await Task.checkCancellation() call executed within a task will throw Task.CancellationError if this task was previously cancelled, meaning that everything that follows it in the same function scope won’t be executed. If you actually have to do any meaningful cleanup, add a defer block or use a non-throwing isCancelled() boolean check to manage this in even more explicit way.

Task handles

How would you actually cancel a task? Remember we mentioned that async let creates an implicit hierarchy of child tasks. There’s a way to manage it explicitly with detached tasks to which you get a handle value as soon as you launch them. Such task has no implicit scope and is not included in any task hierarchy, so you have to manage it yourself. How does the Task.Handle type look like that we’re operating on here?

extension Task {
  struct Handle<Success, Failure: Error>: Equatable, Hashable {
    /// Retrieve the result produced the task, if is the normal return value, or
    /// throws the error that completed the task with a thrown error.
    func get() async throws -> Success
  }
}

extension Task.Handle where Failure == Never {
  /// Retrieve the result produced by a task that is known to never throw.
  func get() async -> Success
}

Importantly, task handles allow you to cancel a corresponding task:

extension Task.Handle {
  /// Cancel the task referenced by this handle.
  func cancel()
  
  /// Determine whether the task was cancelled.
  var isCancelled: Bool { get }
}

And to launch one and get a handle you should use Task.runDetached:

extension Task {
  /// Create a new, detached task that produces a value of type `T`.
  @discardableResult
  static func runDetached<T>(
    priority: Priority = .default,
    operation: @escaping () async -> T
  ) -> Handle<T>

  /// Create a new, detached task that produces a value of type `T`
  /// or throws an error.
  @discardableResult
  static func runDetached<T>(
    priority: Priority = .default,
    operation: @escaping () async throws -> T
  ) -> Handle<T, Error>
}

Note that you can even give a priority to such task, but I consider that a more advanced topic to deserve its own separate article.

Cancellation is cooperative

Let’s see how it works in practice and add a cancellation check to childTasks:

func childTasks() async throws -> String {
    print("\(#function) started")

    async let uuid1 = download("https://httpbin.org/uuid")
    async let uuid2 = download("https://httpbin.org/uuid")
    try await Task.checkCancellation()
    print("\(#function) is not cancelled yet")

    return try await """
    ids fetched concurrently:
    uuid1: \(String(data: uuid1, encoding: .utf8)!)
    uuid2: \(String(data: uuid2, encoding: .utf8)!)
    """
}

The function looks almost the same as previously with just two lines added in the middle: try await Task.checkCancellation() and a print immediately after that. To make things more interesting let’s launch a task that sleeps for one second, then starts childTasks(), and finally prints the result when that’s available:

// run this as a detached task and get a handle for it
let handle = Task.runDetached {
    await sleep(seconds: 1)
    try await print(childTasks())
}

To see the effect of cancellation, in our example the detached task is cancelled immediately after it’s launched, errors from that are caught and printed:

// cancel the task immediately through the handle
handle.cancel()

do {
    try await handle.get()
} catch {
    if error is Task.CancellationError {
        print("task cancelled")
    } else {
        print(error)
    }
}

Let’s build and run the final example with cancellation and observe its output in the terminal:

childTasks() started
fetching https://httpbin.org/uuid
fetching https://httpbin.org/uuid
task cancelled
end of main

Hm, why does it print childTasks() started if we cancelled the task immediately? Remember that tasks that you launch have to explicitly check for cancellation and react appropriately. The sleep function does not check for anything, and the first cancellation check on the execution path happens right after implicit uuid1 and uuid2 tasks are launched. But the result of these two downloads is never printed, because the whole parent task doesn’t finish thanks to the cancellation check in the middle.

Summary

In this example we learned how to set up a SwiftPM CLI project with the new experimental concurrency features enabled. We had a look at the new _Concurrency module and new types introduced in it: continuations and task handles. We learned how to call async functions from non-async code, how to launch new concurrent tasks with async let and detached tasks with Task.runDetached. We also had a look at cooperative cancellation and how to add support for it in your async code.

Concurrency in Swift is a big topic, and there’s a lot more we omitted here that deserves its own separate articles. I hope you liked this one, feel free to shoot a message on Twitter or Mastodon with your feedback!

The state of Swift for WebAssembly in 2020 (and earlier)

Wed, 16 Sep 2020 12:40:32 GMT

It probably all started with an innocently-looking issue in the emscripten repository back in 2014:

For context, back in 2014 the Emscripten project was built as a backend for LLVM-based compilers. While initially it produced JavaScript and later its low-level subset asm.js, Emscripten now mainly targets WebAssembly.

As I wrote in my previous article, the availability of a virtual machine in all relatively recent major browsers makes a lot of code much more portable. It easily follows that Swift targeting WebAssembly would essentially make Swift available in some form on all platforms that have browsers with WebAssembly support.

I started thinking seriously about it in 2018, but I remember having some passing interest in Emscripten and potential Swift support probably much earlier. By 2018 Swift was available on Linux for two years already, people were actively trying to make it work well on Android, and WebAssembly support in upstream LLVM became more or less stable, especially with WebAssembly support in the Rust compiler maturing to some point of usability. In September I started playing with forks and patches that were shared in the original Emscripten thread, and posted a quick update:

The positive reaction surprised me to say the least, I knew the thread was long-running, but I didn’t expect people to actually pay attention to it, and I still thought that WebAssembly was perceived as a fringe technology at the time.

Unfortunately, both LLVM and the Swift toolchain are not documented really well. Additionally, as I learned from my own mistakes, to comfortably work with the codebase you have to be proficient not just in C++ and compiler internals, but also in CMake, Python and Shell to be able to wrangle the huge build system of the toolchain. Powerful hardware is also required, as clean builds can take hours, and incremental builds are not very reliable. I didn’t know what I was doing, and even now I’m just winging it. 🙈 I was just trying to resolve conflicts in patches from other people (mainly Patrick Cheng) and to make at least some code to build without errors. A book that I read many years ago and blog posts by Brian Gesiak and Matt Diephouse gave me some understanding of what things looked like, and confidence that people outside Apple can do some work on it too.

This book, a couple of blog posts from other people, my rusty (no pun intended!) knowledge of C++, Python and Shell scripting, and my MacBook Pro 2018 (I still hate that keyboard) were probably the only weapons I had when I started fighting the dragon.

I was trying to keep up with upstream Swift and LLVM changes, working on it on and off, with some things building, but nothing still worked end-to-end. By February 2019 I was blocked by Swift’s reliance on the pthreads API and atomics, none of which were available in the initial version of WebAssembly (and still aren’t enabled in all browsers by default). I was only able to work on it nights and weekends, while still doing software consulting work during weekdays, which was my main source of income at the time. I still didn’t have enough knowledge of the toolchain to make all necessary changes, and just resolving the conflicts and waiting for multi-hour builds to complete consumed all the efforts I could spend on it.

The most significant move forward happened when Zhuowei Zhang made it all work with the freshly available WASI API and fixed most blocking runtime, metadata and linking issues. By April-May 2019 the SwiftWasm organization was set up with first toolchain builds uploaded and working with basic example code. He also deployed the SwiftWasm website that hosts a simple demo, allowing you to download the compiled WebAssembly binary.

The fact that Chris Lattner himself is interested in WebAssembly support is incredibly motivating!

Unfortunately, neither Zhuowei, nor I could put much time into making this work for something more complex than a simple example. Specifically, on a lower level the Swift compiler makes a distinction between “thin” and “thick” closures. Thin closures are trivial, they don’t capture any surrounding vairables in its context (you can read more details about closure environment in one of my previous articles). Also, Swift error handling is implemented on a lower level as an additional pointer argument passed to throwing functions, but thin closures can’t be throwing as they don’t take that argument. Thick closures expect both context and error pointer arguments to be passed to them. These closure types might seem to be incompatible, but on a high level Swift allows you to pass non-throwing closures where throwing ones are expected:

// Expects a non-throwing closure
func f(_ a: (Int) -> Void) {
  // Passes a non-throwing closure where a throwing one is expected.  
  g(a)
}

// Expects a throwing closure
func g(_ b: (Int) throws -> Void) {
    try! b(1)
}

f { _ in }

This works on a lower level, because none of the existing hardware architectures care if you cast a function with a specific number of arguments to a function with less arguments and ignore the rest of them. You can compile the corresponding C code to x86 or ARM64 and it will work just fine:

#include <stdio.h>

void closure(int argument, void *context, void *error) {
  printf("Argument is %d\n", argument);
}

int main(void) {
  void (*dropArguments)(int) = &closure;
  dropArguments(42);
}

Swift relies on the same trick where thin closures are cast as thick, and this was never a problem that the Swift compiler previously encountered. WebAssembly is much stricter though when casting function pointers. This C code will just crash when compiled to WebAssembly, and quite possibly you won’t be able to launch it at all. Wasm hosts are required to run validation on supplied binaries before execution. One of the validation checks includes verification that caller and callee function signatures match exactly to each other in the number of arguments.

This caused crashes in almost all non-trivial Swift code, as a lot of the standard library functions (map being the most widely used example) can take a throwing closure as an argument, but also accept a non-throwing one. Fortunately, we’ve reached yet another significant milestone when Yuta Saito submitted a PR that worked around this problem in October 2019. The whole issue of Swift relying on the function arguments mismatch trick still bites us here and there, but at least we’re now aware of it, and all known instances of it are fixed in our fork.

What’s going on with SwiftWasm in 2020?

By end of January 2020 Yuta set up automated upstream tracking with the wonderful pull GitHub app that automatically submits PRs with changes from Apple’s repository to our fork. Thanks to this we no longer needed to do it manually to keep up with upstream.

In February-March I no longer had any full-time consulting engagements and decided that it was a good opportunity to focus on open-source work full-time instead. The COVID thing has just started, but it was also clear that it wouldn’t be easy to find consulting clients anyway in this economic environment. In the meantime I wanted to polish some of the other open-source libraries I maintain, and to focus on SwiftWasm as the next big thing in Swift for me personally. I’ve been doing it since then, funding the efforts with my own savings and partially with the help from amazing GitHub sponsors.

There’s a big dilemma here in my SwiftWasm development strategy. I can spend my time either on submitting the changes from our SwiftWasm fork to the upstream Swift repository, or on developing user libraries, improving documentation and writing example code. Kickstarting the ecosystem allows people to build apps and lowers the barrier for contributions from the community, even without WebAssembly becoming a platform officially supported in upstream distributions of Swift.

Submitting PRs upstream on the other hand is very time consuming. Not only the changes need to be polished to a high standard, but also, due to the reasons I’ve mentioned above, working on the toolchain requires a ton of effort. On top of that, due to the limited amount of people available to review PRs to the official Swift repository, sometimes you need to wait weeks for a review. Then if any changes were requested, you apply the changes and wait for weeks again for a re-review. Obviously, we can’t submit one giant PR for everything. So with about 150 files changed in our fork just in the main swift toolchain repository this will be multiplied by dozens if not a hundred PRs. There’s also a comparable amount of changes to the Foundation library.

At the same time, making all the changes available upstream would be a great boost to the overall visibility of the project. But it doesn’t necessarily mean that the WebAssembly SDK will be distributed with Xcode or with any other official Swift distribution. Most probably, Swift developers targeting Wasm would need to download the toolchain and SDK separately just as they do now. This download and installation process is already automated with a developer tool we had to build for SwiftWasm anyway, so I don’t think that official support would have a big impact on the actual developer experience. Given that I’m not employed by any company funding this work, and that my savings and sponsorship revenue are limited, I decided I’d rather spend the next months building libraries and writing documentation for our users rather than drown in the upstreaming process, even though some PRs have already been submitted and a subset of those have been merged. This doesn’t mean that upstreaming work will never be completed. It just won’t happen as soon as some would expect, at least without more people joining the project and helping us out with this.

In April I was sure that we were still pretty far from SwiftWasm becoming usable in complex projects, but Yuta managed to make JavaScript bindings work, which were demoed through the wonderful Game of Life demo built with Swift and running in the browser. This was the first example known to me of SwiftWasm interacting with browser DOM. I consider this to be the most significant milestone this year. I also didn’t expect that SwiftPM would work so well for this project, but it did, and with comparably minor changes.

Inspired by this, I decided to revive my old framework called Tokamak. It was initially conceived in 2018 as a port of React to Swift and iOS, but that aspect of it obviously became irrelevant after the release of SwiftUI. When SwiftUI was released, it really surprised me how similar SwiftUI was to React after all, and it’s somewhat ironic, given how much aversion I saw to React from an average Swift developer before SwiftUI have been introduced. SwiftUI, while built with the same fundamental principles as React (and many other similar frameworks), is augmented with language features that make it a lot more elegant with property wrappers and function builders.

I’m going to publish a detailed overview of Tokamak in the future, but for the purpose of this article, I’ll just mention that in July of 2020 the first release of Tokamak compatible with WebAssembly and SwiftUI was tagged with incredible amount of help from Carson Katri, Jed Fox, Helge Heß, my sponsors, and many other people who reported bugs and provided early feedback. There’s still enough of the SwiftUI API left to implement, but I’m convinced that the general approach is viable, and more releases are coming soon.

Future goals for SwiftWasm

Despite the fact that 2020 has been a horrible year so far from many perspectives, I’m deeply grateful that I have an opportunity to work on a project such as this. We’re just getting started, and there’s much more to do for the ecosystem to grow sustainably. I’ve prepared a list of some of the issues that I’d like to see resolved sooner rather than later.

Short term

Integrate binary size improvements developed by Yuta into the 5.3 branch of our SwiftWasm fork.
Enable SourceKit-LSP support in our SwiftWasm distributions.
You currently can get access to the standard C library by using an import Glibc statement in your code. As the API of the WASI C library is substantially different from the actual Glibc module, it should be exposed under a different name. SwiftWasm users will have to use import WASI instead of import Glibc in later SwiftWasm snapshots, but this will make the API differences explicit.
Release SwiftWasm 5.3.0 after the official Swift 5.3.0 is available for other platforms.

Medium term

Continue our upstreaming work to LLVM, Swift toolchain and SDK repositories.
Set up a community CI node integrated with the official CI Jenkins server.
As Swift support for Windows hosts is going to be available in Swift 5.3, we need to make sure that cross-compiling from Windows to WebAssembly works well. We also need to provide Windows builds of the SwiftWasm toolchain and SDK. It’s not clear to me if Windows support for 5.3 also implies SwiftPM support, as right now it’s only included in builds off the master branch. If it doesn’t land in 5.3, SwiftWasm snapshots for Windows probably will only be available off master and in some future SwiftWasm version.
Similarly, we need to make sure that ARM64 builds of SwiftWasm are available for macOS Big Sur, but as far as I know, none of SwiftWasm maintainers have access to the Apple Silicon DTK, and I personally don’t have any budget for new Apple Silicon production hardware to be released later this year. Sponsoring SwiftWasm maintainers so that we have access to hardware for testing would be greatly appreciated. 🙏
Research more opportunities for performance improvements and binary size reductions. We already have a few in mind:
1. JavaScript strings use UTF-16, while Swift strings use UTF-8 encoding under the hood since Swift 5. This means that every call into JavaScript, especially for modifying DOM, incurs a re-encoding overhead. As Swift String API does not expose the underlying encoding directly, maybe we could go back to UTF-16 in builds that target WebAssembly.
2. One of the biggest dependencies in Swift binaries is the ICU library, which is used for locale-aware string conversions. One way or another, the browser already has access to this code and exposes it to JavaScript. I wonder if we could make Swift strings delegate this corresponding ICU-specific code to the JavaScript API, meaning we’d no longer need to bundle ICU in every binary produced by SwiftWasm.
3. While WebAssembly is a “bare metal” platform with no basic facilities for memory allocation and other basic APIs one would expect, WASI is a compatibility layer that gives you that. It is a big dependency too, so we should explore if it could be stripped down just to memory allocators and whatever other basic code is required to make things work. I’m sure it can be stripped down substantially as the full AssemblyScript runtime is only 2KB, while the WASI JavaScript polyfill required for things to work in browsers, even without counting WASI itself, is more than 200KB.
WebAssembly and web APIs is a collection of different features and not all of them are always implemented by all browsers. We should figure out a way to communicate it in our Swift code, and I don’t think that making the Swift toolchain aware of every feature is a reasonable way forward. That is, I’d prefer (versions are arbitrary) @available(Chrome 242, Firefox 303, Safari 24) attributes on functions to @available(WebAssembly([.mvp, .multiThreading])). The problem with the latter approach is that the number of features will grow very fast, and one would want to encode not only WebAssembly features, but DOM APIs too. For example, if your code uses the Web Animations API and the Intersection Observer API, would you want to specify both of those in the @available attribute? Making the Swift compiler aware of each feature is an unreasonable expectation, while the number of WebAssembly hosts is limited and can be reasonably updated with time if new significantly popular hosts appear.
Speaking of web APIs, JavaScriptKit gives us mostly untyped API bindings, which is not ideal. There are some basic classes in JavaScript, such as Date, Error, Promise, and a few more, but the browser DOM API is much more complex and is huge, and new features are constantly added. It is untenable to create and maintain bindings for DOM manually with such a small team as ours. Luckily, DOM APIs are usually available in the IDL format, and a proof of concept exists that can parse it and generate bindings automatically. We still need high-quality bindings for the basic JavaScript classes to exist for it all to work well, so this is still in progress.

Long term

As I mentioned different WebAssembly features in the previous point, we should be aware of what’s on the horizon to be able to support it. While multi-threading support would be great, the WebAssembly reference types proposal is even more exciting to me. Not only we would no longer need to maintain a lot of interop code that bridges Swift and JavaScript, this could potentially allow Swift developers to import WebAssembly modules with a simple import statement and get most of the type information exposed properly out of the box.
Integrating Swift for TensorFlow with SwiftWasm would be a nice expansion of limits of what’s possible with Swift, as running TensorFlow models in the browser has a lot of practical use cases.

Come join us!

As you can see, there are many interesting and research-focused goals to accomplish. As the ecosystem is in its early stage, it’s easy to make a substantial contribution to its foundations. Please review and file new issues, submit your PRs, and improve the documentation. Build your own projects and let me know of your experience, either on Twitter or via email!

How WebAssembly changes software distribution

Wed, 09 Sep 2020 12:40:32 GMT

If you had any experience with Windows and Internet Explorer in the 90s, quite probably you remember ActiveX controls. Most frequently this involved bulky popups on pages with these controls having to display something more complex than a few blocks of text.

Or, remember Java applets? They became available in 1995, and later they weren’t limited to just Windows and Internet Explorer. I remember I had to use Java applets on macOS as recently as 2013, which chronologically is closer to the present time than the 90s are. (Feeling so old anyway! 👴)

Seems like ActiveX and Java applets were necessities mostly in the enterprise world, but Macromedia Flash (later known as Adobe Flash) was certainly much more widely known to consumers. It was a requirement in the early days of streaming video (even YouTube required Flash to work back then!), but also a major driver in browser gaming in late 2000s and early 2010s. We certainly could blame Flash for making our browser windows look like this:

While ActiveX has seemingly failed to reach a significant adoption, Microsoft made yet another attempt with Silverlight:

In the meantime, Google was working on its own thing for Chrome:

It would be fair to say that these attempts failed to establish wide adoption, especially after both consumers and businesses started shifting to mobile. Here’s how all these forays ended according to Wikipedia:

Microsoft dropped ActiveX support from the Windows Store edition of Internet Explorer 10 in Windows 8. In 2015 Microsoft released Microsoft Edge, the replacement for Internet Explorer with no support for ActiveX, this marked the end of the technology in Microsoft’s web browser development.

“ActiveX” article on Wikipedia.

Beginning in 2013, major web browsers began to phase out support for the underlying technology applets used to run, with applets becoming completely unable to be run by 2015–2017. Java applets were deprecated since Java 9 in 2017 and removed from Java SE 11 (18.9), released in September 2018.

“Java applet” article on Wikipedia.

In July 2017, Adobe announced that it would declare Flash to be end-of-life at the end of 2020, and will cease support, distribution, and security updates for Flash Player.

“Adobe Flash” article on Wikipedia.

There is no Silverlight plugin available for Microsoft Edge. It has not been supported by Google Chrome since September 2015 or by Firefox since March 2017.

“Microsoft Silverlight” article on Wikipedia.

On October 12, 2016, a comment on the Chromium issue tracker indicated that Google’s Pepper and Native Client teams had been destaffed.

“Google Native Client” article on Wikipedia.

But JavaScript solved all these problems, didn’t it?

Most of these browser add-ons were introduced before modern JavaScript and HTML5 became available, so one could argue you no longer need browser add-ons at all. Well, some purists even say browsers should have never supported JavaScript or any scripting whatsoever in the first place. Nevertheless, there are enough use cases for browser scripting and browser apps in general that are hard to avoid. When looking at the history of browser plugins in general, it’s hard not to notice a few themes:

Distributing productivity apps via browsers is convenient in a lot of cases.
Browser gaming made a lot of sense, especially for casual games.
In both of these scenarios browsers had to display something more complex than text and a few static images.

The modern casual tower defense game genre arguably was reborn due to the popularity of Adobe Flash and browser gaming, with Flash Element TD being a classic example.

Even though native apps were (and in many situations still are) objectively better for users, early browser apps were attempting to build their own ad-hoc app stores before the App Store existed. You didn’t have to buy a CD with an application and install it and manage it on your disk. You didn’t have to install updates manually and migrate your data. There was no need to uninstall apps, you just close a corresponding browser tab and forget about it.

And when browser scripting capabilities became advanced enough, some people started seeing the allure of making a browser version of their app the only version they provided. Browsers are cross-platform, aren’t they? Just wrap your JavaScript app code in a browser-like container (say Electron) and distribute that instead of your native app.

But eventually not only the JavaScript APIs became more complex, the language itself could no longer accommodate what developers wanted. Not everyone liked JavaScript syntax (remember CoffeeScript?) or semantics (I couldn’t help but notice that TypeScript has grown in popularity in recent years). But it’s hard to transpile an arbitrary programming language to JavaScript, the latter was not built with that goal in mind.

Corollary, the JavaScript interpreter itself has both memory and performance overhead. Having a garbage collector built in makes it even harder to transpile languages with different memory models to JavaScript. The allure of having only one language to write all your apps for all platforms is still there, but why do you have to be confined to JavaScript itself, even as a target language?

How WebAssembly actually started

With the death of browser plugins, at least we can praise the interoperability efforts of browser vendors. Some lowest common denominator of JavaScript is supported in all browsers, and there is a clear incentive for the vendors to keep up. With the demand to go beyond JavaScript, there were initial attempts to support low level programming with asm.js in 2013:

Much of this performance gain over normal JavaScript [with asm.js was] due to 100% type consistency and virtually no garbage collection (memory is manually managed in a large typed array).

“asm.js” article on Wikipedia.

Syntactically this still looked pretty much like JavaScript, but when you have a lot of low level code, the resulting file can get big pretty quickly, and the size of your code is pretty important when your users download it frequently. As you weren’t supposed to write asm.js code manually most of the time, and it was designed primarily as compilation target, it made sense to invent a binary format for it. That’s basically how WebAssembly started:

WebAssembly was first announced in 2015, and the first demonstration was executing Unity’s Angry Bots in Firefox, Google Chrome, and Microsoft Edge. The precursor technologies were asm.js from Mozilla and Google Native Client, and the initial implementation was based on the feature set of asm.js.

“WebAssembly” article on Wikipedia.

Angry Bots is still available to play on the Unity website.

What WebAssembly got right

Now you’re no longer restricted to JavaScript as a target language for browser apps. As soon as LLVM got WebAssembly backend more or less ready, it allowed compilers built on top of LLVM (for C, C++, Rust, Swift and many more) to adopt it without rewriting everything from scratch. This unlocked the browser environment to a huge amount of pre-existing software that can also run close to native speed if optimized well.

Not only can you run fun little projects such as Sandspiel and orb.farm in your browser tab, but complex games such as Doom 3 (at least its demo version) are available too. Both Unity and Unreal Engine announced their support for WebAssembly, and while we may not see AAA games running in browsers on their initial release date, this still gives enough confidence in the maturity of the platform.

According to its creator, orb.farm is “a virtual ecosystem where different species of creature can live, grow and die as part of a self-contained food chain”.

It’s obviously not limited to games, as we can see Apple folks compiling their C++ and Objective-C code from iWork to Wasm¹, or 1Password using it in their browser extension getting substantial performance improvements as a result:

With our move to WebAssembly, page filling and analysis now runs at least twice as fast as before, and those websites with a large number of fields are up to 13x faster in Chrome and up to 39x faster in Firefox! It’s blazing fast. 🔥

“1Password X: May 2019 update” article on the 1Password blog.

Wasm is a general purpose virtual machine

Not only you get performance improvements with WebAssembly compared to JavaScript, as it was designed to run arbitrary code in your browser, it’s one of the most widely available secure sandbox environments. And as a general purpose virtual machine, Wasm is not limited only to browsers. Cloudflare uses it for edge computing on their CDN:

We’re excited by the possibilities that WebAssembly opens up. Perhaps, by integrating with Cloudflare Spectrum, we could allow existing C/C++ server code to handle arbitrary TCP and UDP protocols on the edge, like a sort of massively-distributed inetd. Perhaps game servers could reduce latency by running on Cloudflare, as close to the player as possible. Maybe, with the help of some GPUs and OpenGL bindings, you could do 3D rendering and real-time streaming directly from the edge.

“WebAssembly on Cloudflare Workers” on the Cloudflare blog.

With people realizing the wide applicability of the Wasm tech stack, it was no surprise when WASI (stands for WebAssembly System Interface) appeared. Where WebAssembly itself is a “bare metal” platform, it does not supply any primitives such as memory allocation or filesystem access, which WASI does provide. As Solomon Hykes, creator of Docker, puts it:

If WASM+WASI existed in 2008, we wouldn’t have needed to created Docker. That’s how important it is. Webassembly on the server is the future of computing. A standardized system interface was the missing link. Let’s hope WASI is up to the task!

@solomonstre on 27 March 2019.

Many of you may know that shipping compilers or virtual machines through the iOS App Store is prohibited. With Wasm you get the ultimate JIT compiler and virtual machine installed on any relatively recent iOS device. Unsurprisingly enough, people have been able to ship a C++ compiler and a command line shell in an app approved for App Store, so let’s hope this remains a legit way to distribute developer tools on iOS. 🤞

a-Shell and Textastic are available on the iOS App Store.

And what completely blew my mind recently is a JIT compiler for x86 binary code running in browsers (not all browsers yet, it requires some features that are currently only supported in Chrome):

As part of CheerpX, we have implemented a fast x86 interpreter and JIT compiler that can generate WebAssembly modules on the fly to efficiently execute arbitrary x86 applications and libraries, fully client-side.

“Extreme WebAssembly 1: pushing browsers to their absolute limits” on Leaning Technologies’ Blog.

WebAssembly as a platform

As a secure and fast sandbox, Wasm also seems to be a good fit for application plugins. One could imagine editors such as VSCode or Atom allowing extensions to be written not only in JavaScript, but in any language that can target WebAssembly. This would make their extensions ecosystem richer and unlock performance improvements that this platform provides. Miguel de Icaza, the creator of Mono and Xamarin agrees, and goes further with this idea:

[…] IDEs/Editors/Tools could leverage WebAssembly to host their favorite language for scripting during the development stage, but for the final build of a product (like Unity, Godot, Rhino3D, Unreal Engine and really any other application that offers scripting capabilities) they could bundle the native code without having to take a WebAssembly dependency.

“Scripting Applications with WebAssembly” on Miguel de Icaza’s Blog.

WebAssembly is arguably a more direct path towards achieving the idealistic goal of “write once, run anywhere” than Java/JVM ever was. This is thanks to the open nature of the whole stack, potential developer mind share (spanning big and diverse set of languages and ecosystems), and direct involvement of browser vendors such as Apple, Google, Mozilla and Microsoft. This is the opposite to the fractured ecosystem we saw in the 90s and 00s, where every vendor had their own special plugin and forced you to use a specific programming language as a gatekeeping measure.

What WebAssembly still needs

As with any tech stack in its early years, not everything is hunky-dory in the WebAssembly land. It would be unfair if I didn’t mention that debugging with print statements is still a thing when targeting Wasm, or that multi-threading support is not available in all browsers and formally haven’t reached the implementation stage yet. The lack of stable ABI for dynamic linking is not critical and static linking makes some things somewhat easier, but it can still bite at times.

The fact that the vast majority of consumer computing devices (92% as of September 2020 according to caniuse.com) have a universal virtual machine that can be targeted by virtually any programming language is still fascinating to me. What WebAssembly definitely needs is more attention from developers, and if all goes well, in a few years we’ll see even more products that weren’t possible before.

Wasm is an abbreviation, but not an acronym, and it is the capitalization that WebAssembly spec authors use (in addition to the all-lowercase “wasm”). Thus, we should follow the authors with this capitalization variant, unless you’re one of those, who writes “IOS”, “XCode” or “IPhone”. 🙈
↩

Unbreakable reference cycles in Swift no one is talking about

Mon, 17 Dec 2018 12:40:32 GMT

When using Swift, one of the most important things to consider is a difference between value types and reference types. We know that a static type system is useful to avoid type errors, similarly a guarantee that constant values stay immutable is quite handy to avoid errors in stateful code. Unfortunately, for certain reasons immutability and reference types in Swift are mutually exclusive by default. Also, value types and reference types involve different approaches to memory management: value types are implicitly copied while reference types only change their reference count when passed around. Without proper care, it’s easy to create reference cycles with reference types which cause memory leaks. Would it make sense to avoid classes altogether to avoid that and get immutability when needed as a nice bonus?

Not so fast, there might be more problems than one could anticipate. What follows is a result of my trial and error when using Swift and the last few sections describe nuances that I haven’t seen described anywhere, but in my opinion are quite easy to stumble upon.

Reference cycle = memory leak!

Wait, remind me how memory management works in Swift

If you have good knowledge of how to use weak keyword and how memory management works for value and reference types, feel free to skip to the section with more advanced examples. Otherwise, consider this super simple code:

struct S {
  init() { print("S init") }
}

func f1() -> S {
  // one allocation for S()
  // "S init" is printed here
  let original = S()
  // copy of `original` that can be optimised by the compiler
  let copy = original

  return copy
  // both `original` and `copy` out of scope here
}

// copy of `original` that can be optimised by the compiler
var result: S? = f1()

// value stored in `s` is dellocated here
result = nil

Here memory management is trivial:

A value of type S is allocated and assigned to original.
Storage of original is copied to copy.
On return from function f1 value original goes out of scope and is deallocated.
The return value from f1 is copied to result.
copy itself is deallocated as out of scope.
When nil is assigned to result, that result is deallocated.

All of these copies can be optimised away by the compiler and in the generated optimised code you’d only see one allocation, zero copies and one final deallocation. This means only steps 1 and 6 would execute (with result and original aliasing the same value), but from programmer’s perspective, the behaviour would stay the same.

Why the same? Note that "S init" is printed only once. There’s no notion of “copy initialiser” in Swift, creating a copy of a value only copies its storage without calling init. This means we don’t expect any code to be executed on these copies and some of them can be optimised away by the compiler without changing the behaviour of resulting executable code.

Now compare this to memory management with classes:

class C {
  init() { print("C init") }
  deinit { print("C deinit") }
}

func f2() -> C {
  // one allocation for C();
  // "C init" printed here;
  // also increment its reference count by 1
  let reference1 = C()
  // increment reference count by 1 (2 in total)
  let reference2 = reference1

  return reference2
  // both `reference1` and `reference2` out of scope here;
  // decrement reference count by 2;
  // no deallocation because of a new reference created
  // for the return value outside of this function
}

// increment reference count by 1, 1 in total
var result: C? = f2()

// decrement reference count by 1, 0 in total
result = nil
// "C deinit" printed here

Swift doesn’t allow adding deinitialiser code to a struct with deinit, but it’s possible for classes, which allows us to better track deallocations. Now memory management is a bit more involved. With this code, you’re guaranteed only one allocation and no copies will occur, but this also involves allocating storage for a counter that tracks all references. There’s also runtime overhead now for incrementing and decrementing the counter. In addition, reference counting in Swift is thread-safe, but this involves using atomic operations. This adds even more potential runtime overhead when compared to optimised code using only value types.

Ok, and what’s a reference cycle then?

Consider a tree-like data structure, where a node in this tree holds a reference to its children. It would be nice for a node to also hold a reference to its parent. Here’s a naive approach that expresses this with a class:

class TreeNode {
  private(set) var children = [TreeNode]()
  private(set) var parent: TreeNode?

  init() { print("TreeNode init") }

  deinit { print("TreeNode deinit") }

  func add(child: TreeNode) {
    children.append(child)
    child.parent = self
  }
}

func f3() {
  let root = TreeNode()
  // "TreeNode init" printed here

  for _ in 0..<3 {
    root.add(child: TreeNode())
    // "TreeNode init" printed here
  }
}

f3()
// "TreeNode deinit" printed 4 times here, no??? 🤔

Well, here’s a problem: a child and a parent both hold references to each other, which means their reference counts will never reach 0. So even if it looks like all references to TreeNode instances went out of scope when returning from f3, none of those instances were deallocated and you’ll never see "TreeNode deinit" printed even once!

How do I avoid reference cycles with classes?

Good news is that in Swift any variable of an optional class type can be declared weak. It will hold a “weak” reference to the instance without incrementing its reference count. This also means that this reference becomes nil when the instance is deallocated, you can’t have “weak” constants because of this:

// strong reference
var node1: TreeNode? = TreeNode()
// "TreeNode init" printed here

// weak reference, reference count untouched
weak var node2 = node1

// deallocate what's stored in `node1`
node1 = nil
// "TreeNode deinit" printed here

// what's referenced by `node2` then?
print(node2)
// "nil" printed here

Now let’s fix our TreeNode memory leak with a weak reference:

class TreeNode {
  private(set) var children = [TreeNode]()
  // note added `weak` added before `var parent`
  private(set) weak var parent: TreeNode?

  init() { print("TreeNode init") }

  deinit { print("TreeNode deinit") }

  func add(child: TreeNode) {
    children.append(child)
    child.parent = self
  }
}

func f4() {
  let root = TreeNode()
  // "TreeNode init" printed here

  for _ in 0..<3 {
    root.add(child: TreeNode())
    // "TreeNode init" printed here
  }
}

f4()
// "TreeNode deinit" printed 4 times here, yay! 🎉

You may have seen example code like above multiple times in many educational materials about Swift. Memory management based on compile-time guarantees and optimisations has these downsides that you need to be aware of. On balance it pays off as performance impact is predictable and deterministic. In Swift, you don’t need to worry that a garbage collector will unexpectedly pause everything in the middle of carefully optimised code for deallocations. This becomes critical in code that has anything to do with UI, especially AR/VR: you don’t want to drop rendered frames in the middle of a user interaction, especially when you need to deliver 120 freshly rendered frames per second.

Classes cause reference cycles, reference cycles are bad. Are classes bad?

Maybe it’s time to reconsider the situation: classes cause reference cycles, why not stop using classes? And besides, protocol-oriented programming is cool, we can use composition instead of inheritance, use structs, enums and protocols for everything, we don’t need those stinky classes with stupid reference cycles! 😜

Huh, that sounds quite attractive. Except that we forgot about yet another important reference type in Swift: closures! Yes, closures are reference types, they need to capture the environment outside to allow modifying that environment when a closure body is executed. This has the same implications we’ve discussed previously: assigning a closure to a variable will increase the reference count for that closure instead of copying it.

So what’s that kind of reference cycles no one’s talking about?

You can create a reference cycle with classes, you can create a reference cycle with closures and classes, but you can’t create a reference cycle with closures and value types, right?

No, it turns out you can even create unbreakable reference cycles with closures and value types! 😱 The big problem here is that capturing a value (not a class) in a closure implicitly creates a new reference to that value for closure’s environment:

var i = 0

let increment = { i += 1 }

increment()
print(i)
// prints "1"

So even though i is a value, not a class instance, i inside of the closure increment is a reference to i in closure’s environment. Not only increment stores a reference to the closure, but the closure itself also creates and stores a new reference!

You could say “just make these references weak”! Sure, that’s easy with a closure environment that only captures class instances:

class I {
  var x = 0

  var increment: (() -> ())?
}

let i = I()

// explicit capture list for capturing `i` weakly
i.increment = { [weak i] in i?.x += 1 }

i.increment?()

Cool, now i holds a strong reference to the closure, but closure holds a weak reference to i, no reference cycle. Why not try the same with value types?

struct I {
  var x = 0

  var increment: (() -> ())?
}

var i = I()

i.increment = { i.x += 1 }
// reference cycle!

i.increment?()

What’s worse, if you add [weak i] capture list to fix the reference cycle you’d get a compiler error like 'weak' may only be applied to class and class-bound protocol types, not 'I'. The only way to break the reference cycle is to explicitly set i.increment to nil when it’s no longer needed, which is less than ideal. 😞

Think twice before storing a closure as a property of a value type

Can we still avoid using classes with the caveat that we clean up our closures manually? I don’t think so, here’s why:

struct I {
  var x = 0

  var increment: (() -> ())?
}

var i = I()

i.increment = { i.x += 1 }
// reference cycle!

var copy = i
copy.increment?()
copy.increment?()
copy.increment?()
print(copy.x)
// guess what's printed here? 🤨

// break the reference cycle manually
copy.increment = nil
i.increment = nil

Guess what’s the value of copy.x printed above? 0! You’d probably expect 3 and that copy holds a copy of i and copy.increment?() increments copy.x. But remember that closures and their environment can’t be copied. That’s why copy is a “partial” copy of i. Value of x has been copied, but property increment of copy holds a reference to increment of i with x of i in the captured environment. Calling copy.increment?() will follow the reference and increment value of x on the original i instead of copy.

If you find yourself writing code similar to above with value types holding references to closures, take extreme care to avoid unexpected results.

Summary

We’ve compared memory management with value and reference types in Swift and had a look at different ways to create and break reference cycles. Reference cycles between different class instances are trivial, but when you start using closures this can get a bit more complicated. The most unexpected kind of reference cycles involves closures and value types and most frequently you would want to rearchitect code using those in a different way. In these situations breaking the reference cycle requires manual handling and can cause subtle errors due to the fact that the closure environment can’t be copied.

Many thanks to Swift Forums for giving an opportunity to discuss these issues. I really enjoyed learning a lot of interesting details about how references work (and could work in future versions of Swift) in this Swift Forums topic.

Are you interested in other memory management features of Swift? Have you been able to work around these reference cycles in a different way? I look forward to hearing your story, please shoot a message on Mastodon or Twitter.

Easy parsing of Excel spreadsheet format with Swift's Codable protocols

Mon, 12 Nov 2018 12:40:32 GMT

Back in the 90s and early 00s, when Google Docs didn’t exist yet and devices from Apple weren’t as popular, the primary way to create, edit and share documents and spreadsheets was Microsoft Office and its proprietary .doc and .xls binary formats. At that time working with these files outside of Microsoft’s ecosystem was a world of pain, there were multiple attempts to reverse engineer these formats, but none of them were good enough.

Image from en.wikipedia

Fortunately, later Microsoft transitioned towards using an XML-based format: XLSX. Even now I occasionally stumble upon a service that yields a file like this instead of a CSV. There is a plenty of apps that open these files without Microsoft Office installed, even standard QuickLook on iOS and macOS can give you a preview for it.

But previews and apps are only ok for manual operations. What if there’s a need for automation? For example, my specific use case is to transform an Excel spreadsheet using only specific rows and columns into a CSV file with a subset of columns from the original file. If you’re like me and would like to stay in the Swift ecosystem, there are no great options. There’s an Objective-C library that at the moment of publishing this article hasn’t been updated in more than 2 years. There’s another C library that can create and write XLSX files, but as far as I know, can’t read one.

And implementing support for a file format is a huge and complex task, right? There’s some compressed data involved, multiple entities to parse and there’s a ton of variation in different files which is hard to support?

Easy peasy, it’s just an archive of XML files!

Turns out, an XLSX file is a simple zip archive, you can poke at its raw content with a simple terminal command:

$ unzip file.xlsx
Archive:  file.xlsx
  inflating: _rels/.rels             
  inflating: docProps/core.xml       
  inflating: docProps/app.xml        
  inflating: xl/workbook.xml         
  inflating: xl/_rels/workbook.xml.rels  
  inflating: xl/theme/theme1.xml     
  inflating: xl/worksheets/sheet1.xml  
  inflating: xl/sharedStrings.xml    
  inflating: xl/styles.xml           
  inflating: [Content_Types].xml

When there’s a need to get data out of a single worksheet, there are only 3 files to parse:

_rels/.rels – this XML file stores paths to “documents” contained within the main file.xlsx archive
xl/_rels/workbook.xml.rels – this file referenced from _rels/.rels contains paths of worksheets that documents in the archive have
xl/worksheets/sheet1.xml – this is where worksheet data lives: rows, columns and cells.

What does “Codable” mean in Swift?

There are multiple ways to implement parsers for different formats. JavaScript, for example, comes with a standard JSON.parse function, which is able to parse JSON, but for any other format, you’re on your own. All 3rd-party libraries for JavaScript like to invent their own parsing APIs from scratch.

This was even worse not so long ago with the first few versions of Swift when we not only had ad-hoc APIs for other formats like XML but dozens of JSON parsing libraries as well. 😅 But I’m so happy to deal with Swift nowadays after it gained a standard API for almost any serialization format you’d need.

The main concepts in this serialization API in Swift are the Codable typealias:

typealias Codable = Decodable & Encodable

and the Decodable/Encodable protocols:

protocol Decodable {
  init(from decoder: Decoder) throws
}

protocol Encodable {
  func encode(to encoder: Encoder) throws
}

There are also Encoder and Decoder protocols mentioned above, but they don’t really matter in the day-to-day use of Codable. The most wonderful thing here is that Swift compiler is able to derive an implementation of Codable for your types automatically, as long as Codable implementation is available on types of properties that you use. And obviously, Codable is already implemented on all primitive types like Bool, Int, String etc.

Even better, implementation of Codable on your types can be reused for multiple formats if needed. For example Foundation module provides standard JSONEncoder and JSONDecoder types that allow serialising your data in and out of JSON in a standard way. But for our case, we only need a 3rd-party implementation of this for XML, like XMLCoder.¹

“Codable” in practice

As shown earlier, our first step towards reading data from an Excel file is parsing _rels/.rels in the archive, which looks like this:

<Relationships 
xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship 
  Id="rId1" 
  Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" 
  Target="docProps/core.xml"/>

  <Relationship 
  Id="rId2" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" 
  Target="docProps/app.xml"/>

  <Relationship 
  Id="rId3" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" 
  Target="xl/workbook.xml"/>

< /Relationships>

The most primitive node we’d like to handle in a type-safe manner is Type of the Relationship, let’s create an enum for it (I’ve replaced long schema urls with [...] for brevity):

enum SchemaType: String, Codable {
  case officeDocument = "[...]/officeDocument"
  case extendedProperties = "[...]/extended-properties"
  case coreProperties = "[...]/core-properties"
  case worksheet = "[...]/worksheet"
  case sharedStrings = "[...]/sharedStrings"
  case styles = "[...]/styles"
  case theme = "[...]/theme"
}

A complete version is available on GitHub.

Note the Codable conformance on this enum, we don’t need to implement anything for it manually as it will be generated automatically by the compiler for us. The next step is the Relationship node itself:

struct Relationship: Codable {
  let id: String
  let type: SchemaType
  let target: String
}

And then it’s only the root Relationships node left:

struct Relationships: Codable {
  let items: [Relationship]

  enum CodingKeys: String, CodingKey {
    case items = "relationship"
  }
}

Note the CodingKeys enum here conforming to the CodingKey protocol. It allows us to specify a different name for a property that contains the decoded data. In our case, there are multiple Relationship children nodes within the root Relationships node. It’s better when these nodes are stored in a property named items rather than a default relationship property you’d have to create without CodingKeys.

The main property we’re interested in here though is the target on a Relationship node with type officeDocument, it contains a path to the document. But also, remember that all of this XML is stored within a zip archive, how do we unzip it in the first place?

Unzipping an archive in memory and parsing the contents

A great indicator of Swift ecosystem maturity is the number of good libraries you can find for the most popular tasks when working on production apps. And it’s pretty good, well, except for XLSX libraries until now. 😂 But at the moment we also need to uncompress a zip archive in memory and it looks like ZIPFoundation is the best implementation that supports both Linux and Apple platforms.

Let’s create the main entry point for the public API of our XLSX library:

public struct XLSXFile {
}

The main type we need to work in ZIPFoundation is Archive, let’s add it as a private property and also create an instance of XMLCoder to reuse later:

public struct XLSXFile {
  public let filepath: String
  private let archive: Archive
  private let decoder: XMLDecoder

  public init?(filepath: String) {
    let archiveURL = URL(fileURLWithPath: filepath)

    guard let archive = Archive(url: archiveURL, accessMode: .read) else {
      return nil
    }

    self.archive = archive
    self.filepath = filepath

    decoder = XMLDecoder()
  }
}

Now we also need a generic way to parse an XML file from the archive, let’s add a function on XLSXFile and also a helper Error subtype for it. This parseEntry function should take a path like _rels/.rels and a type of representation of a root node and return an instance of that type or throw an error:

public enum XLSXReaderError: Error {
  case archiveEntryNotFound
}

public struct XLSXFile {
  // ...
  private let archive: Archive
  private let decoder: XMLDecoder

  /// Parse a file within `archive` at `path`. Parsing result is
  /// an instance of `type`.
  func parseEntry<T: Decodable>(_ path: String, 
                                _ type: T.Type) throws -> T {
    guard let entry = archive[path] else {
      throw XLSXReaderError.archiveEntryNotFound
    }

    var result: T?

    _ = try archive.extract(entry) {
      result = try decoder.decode(type, from: $0)
    }

    return result!
  }
}

And now we can use this function to get the list of documents within the archive. Here .convertFromCapitalized setting specifies we’d like to convert capitalised attribute names to lowercase properties so that Target becomes target, Type becomes type and Id is mapped to id.

public struct XLSXFile {
  // ...

  /// Return an array of paths to relationships of type `officeDocument`
  func parseDocumentPaths() throws -> [String] {
    decoder.keyDecodingStrategy = .convertFromCapitalized

    return try parseEntry("_rels/.rels", Relationships.self).items
      .filter { $0.type == .officeDocument }
      .map { $0.target }
  }
}

Parsing a worksheet

I omit a completely boring 20-line function parseWorksheetPaths where we parse a similar relationships file to get paths to the actual worksheets. While this function is going to be used later, it’s very similar to parseDocumentPaths we’ve just implemented above. Instead, let’s focus on a much more interesting model type Worksheet:

public struct Worksheet: Codable {
  public let sheetPr: SheetPr?
  public let dimension: WorksheetDimension
  public let sheetViews: SheetViews
  public let sheetFormatPr: SheetFormatPr
  public let cols: Cols
  public let sheetData: SheetData
  public let mergeCells: MergeCells?
}

This type directly represents a worksheet XML you’ll be able to find in most common XLSX files. Basically, the rest of the source code of the parsing library is struct declarations of the property types you find on the root Worksheet XML node and the rest of the types match its descendant nodes. For example, one such type is Cell:

public struct Cell: Codable, Equatable {
  public let reference: String
  public let type: String?
  public let s: String?
  public let inlineString: InlineString?
  public let formula: String?
  public let value: String?

  enum CodingKeys: String, CodingKey {
    case formula = "f"
    case value = "v"
    case inlineString = "is"
    case reference = "r"
    case type = "t"
    case s
  }
}

And sorry I don’t know what exactly the attribute s stands for ¯\_(ツ)_/¯. It’s still not easy to find detailed documentation on all of the attributes, but I’ve been able to provide sensible names to most of them.

For some reason worksheet XML nodes and attributes aren’t capitalised, so we need to reset the decoding strategy for parsing them to .useDefaultKeys. This will leave node and attribute names lowercase as they are.

public struct XLSXFile {
  // ...
  private let decoder: XMLDecoder

  /// Parse a worksheet at a given path contained in this XLSX file.
  public func parseWorksheet(at path: String) throws -> Worksheet {
    decoder.keyDecodingStrategy = .useDefaultKeys

    return try parseEntry(path, Worksheet.self)
  }
}

Using the library

Now we’ve got the library working, let’s read a simple file:

guard let file = XLSXFile(filepath: "./file.xlsx") else {
  fatalError("XLSX file corrupted or does not exist")
}

for path in try file.parseWorksheetPaths() {
  let ws = try file.parseWorksheet(at: path)
  for row in ws.sheetData.rows {
    for c in row.cells {
      print(c)
    }
  }
}

This will print every cell in every worksheet in an XLSX file provided. And that’s mostly all there is to it. 🙌

Summary

It seems like there are no cross-platform libraries for parsing XLSX available to use with Swift. Turns out, implementing file format support from scratch isn’t that hard with the great Codable API available in Swift standard library. XLSX files are actually zip archives with multiple XML files within. In this article, we had a look at the code that decompresses an archive in memory and parses the XML files to get cell data for any given worksheet.

I’ve published this as CoreXLSX package available to use with CocoaPods and Swift Package Manager. I hope this library saves you some time when you need to read something from an XLSX file in an automated way. Or maybe you could use it as an example for implementing other file formats in your apps and libraries. Either way, I’d appreciate your feedback on Twitter or Mastodon and would be very happy if you star the repository and create issues and pull requests at GitHub. 🤩

This library is a hard fork of a great XMLParsing package by Shawn Moore. Unfortunately, it looks like the original repository doesn’t accept PRs for known issues and hasn’t been updated in some time. Some of these issues were blocking my XLSX parsing implementation. To make matters worse, CocoaPods doesn’t allow dependencies on forks with the same name as original libraries, so I had to create a fork with a new name. I wish I could merge my contributions back. 😔
↩

Event loops, building smooth UIs, and handling high server load

Thu, 16 Aug 2018 12:40:32 GMT

How do closures and callbacks work? It’s turtles all the way down
Event loops, building smooth UIs, and handling high server load
Introduction to structured concurrency in Swift: continuations, tasks, and cancellation

Have you ever used an app that felt unresponsive? Not reacting to input on time, slow animations even for some simple tasks, even when there isn’t anything heavy running in the background? Most probably, an app like that is waiting for some blocking long-running computation to finish before consuming more user input or rendering animation frames. Scheduling all workloads correctly and in the right order might seem hard, especially as there are different approaches to choose from.

What does it mean to be “non-blocking”?

When developing native apps for iOS, we always have this thesis: “avoid blocking the main thread”. Due to the fact that UIKit and AppKit APIs are not thread-safe, most if not all UI rendering happens on the main thread. If you have a long-running blocking computation on that thread, your app isn’t able to respond to user input or to render UI updates.

For an app to feel smooth and interactive on a device with 60 Hz display refresh rate, it has to render 60 frames a second and update those in response to user input as close possible to real time. That means you as a developer only have about 16.6 milliseconds of run time in event handlers on the main thread to complete. Want the app to feel smooth on 120 Hz iPad Pro? That’s 8.3 milliseconds on the main thread at your disposal.

Here’s a conceptual diagram of CPU load on the main thread that refreshes UI at 60 Hz and runs a blocking operation on the main thread. Red solid spikes in CPU load are caused by UI rendering code, while blue ones are caused by HTTP client code.

As you can see, if an HTTP client operation is blocking and runs for more than 33 milliseconds, up to 3 UI frames would not be rendered. Imagine if the request runs on a slow network and takes seconds to complete, the app UI would freeze and be unresponsive during all that time.

The important thing to note on the diagram is that CPU stays idle while waiting for the network operation to complete, so in principle, it could have rendered the frames while waiting. This type of operation is called I/O-bound, which means that a bottleneck in the operation is I/O (filesystem access, networking, communicating with sensors and peripherals etc) rather than intensive computations on the CPU. On the contrary, operations where CPU load is a bottleneck are called CPU-bound operations. This distinction is quite important, it turns out it’s quite easy to make I/O-bound code non-blocking.

Event loops

How do people avoid blocking the main thread with I/O-bound code? Here’s one approach: as soon as main app initialisation has finished, an event loop is started (also known as a “run loop” in Cocoa/Foundation/GCD world). It is a loop that processes I/O events and invokes corresponding event handlers at each iteration. While the loop is not truly infinite, certain exit events, say a user closing the app, would clean up the resources and stop the loop. But it’s indefinite in a sense that usually there’s no predefined number of iterations when it starts.

Building smooth UIs

Most of the code an iOS/macOS developer writes is called from an event loop iteration. All gesture recognisers, sensors input and higher level event handlers such as button taps and navigation handlers are invoked on the main thread and are scheduled by an event loop. This is applicable to browser apps too: all your code (except web workers) runs on the same thread and blocking computations would make UI freeze. In the end, the browser is just a native application with its own event loop that forwards native events to your JavaScript code.

Here’s an example of a stacktrace of a native iOS app, which shows event loop functions at the bottom of the stack:

There's always an event loop there near the bottom of the call stack for UIKit apps.

I bet, in 90+% of the cases when debugging the main thread of iOS apps, you’d see these calls at the bottom of a stacktrace. It’s an implementation detail that’s hidden quite well from us, but a very important one.

How would an event loop fix our UI example with a blocking HTTP client? We saw from the CPU load on the diagram that this operation is composed of two parts: forming a request and parsing a response. Quite simply, we could run request formation as soon the operation starts and then schedule response parsing on a subsequent event loop iteration to be called only when this response is ready.

Here’s a diagram of the same UI example with an event loop:

A notable change here is the introduction of callbacks. Instead of performing an I/O-bound operation all at once, it is split into multiple parts, which are chained with a callback. For example, in Swift a callback could be created in a form of a closure:

let session = URLSession.shared
session.dataTask(with: URL(string: "https://your.api/call")!) {
  data, response, error in
  // ...
}

or a delegate object:

class Delegate: URLSessionTaskDelegate {
  func urlSession(_ session: URLSession,
  task: URLSessionTask, didCompleteWithError: Error?) {
    // ...
  }
}

let task = session.dataTask(with: URL(string: "https://your.api/call")!)
task.delegate = Delegate()

or even with target-action pattern (usually reserved for UI handlers):

class Controller: UIViewController {
  func viewDidLoad() {
    super.viewDidLoad()
    let button = UIButton(type: .custom)
    button.addTarget(self, action: #selector(handler),
                     for: .touchUpInside)
    view.addSubview(button)
  }

  @objc func handler() {
    // ...
  }
}

All of these patterns are enabled by event loops. On a higher level, the existing event loop is able to invoke these callbacks at some later iteration without blocking other code.

Handling high HTTP server load

Even if you aren’t working on the full stack, as a frontend dev you might be interested how those servers can handle the increased amount of requests from your smooth apps powered by event loops. And if you’re a backend dev, I hope that previous section was not too boring and you like this one even more. 😄

Now imagine an HTTP server processing a high amount of requests coming at the same time. Firstly, a request is parsed to get a few parameters and then the server issues a query to a database with the parameters. After the query is finished, a response is formed with the query result and sent to a client.

It’s easy to see with an abstract CPU load diagram how a blocking database query can kill the server’s throughput. On the following diagram there are three separate CPU load spikes for every request and response sequence:

While HTTP servers don’t drop UI animation frames like in the UI example, a blocking operation makes a client wait in a queue for a response until requests are processed one by one. Of 6 requests shown, only 4 were handled by the end of the diagram timeline. Again, it’s obvious that a database query is I/O-bound and you could have processed many requests simultaneously. This would also saturate CPUs more efficiently, which is quite important in reducing the cost of running servers.

You probably have guessed by this point, event loops come to the rescue! 😄 What if the server started parsing a response as soon as it’s received, not waiting for a database query of a previous request to complete? As I’ve marked three steps of the operation in different colours, you can see that parts of asynchronous request handling are executed out of order on a linear CPU timeline. It doesn’t mean anything’s wrong, as HTTP is a stateless protocol, you can assume that requests are independent and can be processed simultaneously.

Overall, we can’t say that database queries became faster when you look at a given request and response pair. But throughput is much better thanks to the introduction of an event loop (assuming your database is able to handle the increase). For 6 requests by the end of diagram’s timeline, 5 responses were issued, and it was done much earlier than it would have happened in a blocking version. The CPU load is more evenly distributed within one process, which reduces context switching overhead and server cost.

Current status of event loops on the server side

Nowadays, if you write server-side code, quite probably you already use an event loop under the hood. Let’s have a quick overview of how major languages and frameworks actually do this.

Node.js provides an implicit event loop in a single thread that you work with. setTimeout, setImmediate and setInterval functions schedule closures to be executed later by the default event loop. Turns out, ASP.NET Core supports non-blocking I/O out of the box. This may not be so surprising, given that C# supported async methods since 2012. If you’re into JVM ecosystem, Netty is the way to go with event loops. And you probably heard of it, Norman Maurer, one of the main contributors to Netty now works for Apple and is a top committer to the new SwiftNIO framework.

Now we’ve mentioned Swift, Vapor 3.0 already migrated to SwiftNIO and there’s also a “tech preview of Kitura on SwiftNIO” available. Interesting to note that SwiftNIO allows you to utilise event loops across multiple threads.

Scaling event loops across multiple threads is a very powerful concept and is something that’s also already available on the language level in Go and Elixir. While I have my share of scepticism for both Go¹ and Elixir², these are very interesting languages that I highly recommend to explore and wrap your head around.

In our day and age of diminishing returns from Moore’s law, being able to easily scale tasks across multiple CPU cores, GPUs and other devices is indispensable. Concurrency, parallelism and distributed computing is the new functional programming. 🤓 In some sense, these topics initially seem to be difficult and obscure, but can drastically improve how you approach different problems when you have at least some understanding of basic concepts.

How do you even deploy a backend app without an event loop?

For quite some time event loops weren’t as popular in backend software as they are now. Back in the 90s, spawning a new process for every HTTP request seemed normal, I refer you to the history of Common Gateway Interface for more info on this. A few optimisations followed, like SCGI and FastCGI, but they still maintained a clear separation between an HTTP server and request handling itself. An HTTP server (e.g. Apache) could have used an event loop on the lower level, but the application logic still lived in a separate process. It was possible to eke out a bit more performance by spawning multiple worker processes or threads, but this still caused context switching overhead and same blocking I/O bottlenecks as previously.

You could’ve asked: “who even writes blocking HTTP code these days?“. Well, if you’re writing code for Python 3.2 and older, most probably you don’t have access to asyncio, which is Python’s standard implementation of event loops. Most popular Python’s web frameworks like Flask and Django are synchronous, not powered by an event loop and are commonly deployed via WSGI. The most popular HTTP client library requests provides only blocking API as well.³ When you do have access to newer Python versions and to asyncio, event loops there are a bit more explicit than in Node.js, but the underlying concept is still the same.

While I don’t have much exposure to Ruby and Ruby on Rails, in my research I haven’t found any event loop frameworks that have become mainstream. It does look like most common solutions for deployment utilise multithreading and multiprocessing to improve scalability.

Similarly with PHP, while ReactPHP is about 5 years old at this point, you can’t beat inertia of deploying WordPress on Apache. 😄

How do event loops work?

There is a ton of details hidden under the hood that we don’t need to worry about on a daily basis. After all, event loops are meant to improve how we work with I/O-bound tasks and most of I/O stuff can get complicated real quick.

A good explanation is this pseudocode from SwiftNIO documentation. As SwiftNIO is primarily a server-side framework, a channel here means a server connection established by a client. But on a low level, this is applicable to UI event loops too. From a certain perspective, interactions with touch sensors, display drivers and GPUs can be considered I/O.

while eventLoop.isOpen {
  /// Block until there is something to process for 1...n Channels
  let readyChannels = blockUntilIoOrTasksAreReady()
  /// Loop through all the Channels
  for channel in readyChannels {
    /// Process IO and / or tasks for the Channel.
    /// This may include things like:
    ///    - accept new connection
    ///    - connect to a remote host
    ///    - read from socket
    ///    - write to socket
    ///    - tasks that were submitted via EventLoop methods
    /// and others.
    processIoAndTasks(channel)
  }
}

Here blockUntilIoOrTasksAreReady interacts with sockets or device drivers via system calls and provides events that are ready to process. In turn, processIoAndTasks dispatches those events to corresponding callbacks that were registered on previous event loop iterations.

Disadvantages of event loops

As I previously mentioned, the server-side event loop diagram is a bit harder to read when establishing the sequence of events. This especially might get in the way during debugging. In a function call stacktrace you probably would be able to see what kind of event led to a specific callback handler, but tracing it to the original code that scheduled the handler has to be done separately.

You might’ve stumbled upon a similar problem when debugging multithreaded code. A stacktrace of a particular thread can be retrieved, but by the time your point of interest executes, the original thread that scheduled the work has already moved on to completely different code.

In a situation with multiple threads, this can be further complicated by the use of synchronisation primitives and non-deterministic nature of thread scheduling. On the contrary, if your event loop code is single-threaded and tasks are scheduled and handled from the same thread, it’s not as bad.

A quite acceptable solution is to maintain a separate callback stack trace that can be examined later when needed. For example, SwiftNIO records file names and line numbers of futures and promises that were created. This information is then logged if a deallocated future was unfulfilled, indicating that there is a potential leak creating redundant future objects. In principle, a higher level framework (say an HTTP server) could attach richer information to its own stack of requests to be logged when something goes wrong.

Summary

It would be fair to say that an event loop is a great tool for building high-performance and scalable applications. We’ve looked into how it helps with both UI and server-side code. Specifically, on the server side, there are plenty of approaches, different languages and frameworks evolved in different ways that are still fundamentally the same under the hood.

Non-blocking I/O on a low level can be relatively tricky, and it’s great that event loops can abstract this away. There are a few caveats with regards to debugging event loop based code, but it’s something that can be overcome with tooling, better support from frameworks and runtime of a programming language that you use.

As with any tool, it’s important to know the use cases and apply it where it fits best. With event loops, you can get substantial gains in throughput and responsiveness of your apps if applied well, while paying a small cost of recording more runtime information to ease debugging if needed.

I hope I provided some information on that in the article, but please feel free to shoot a message on Twitter or Mastodon with your comments and questions. Talk soon. 👋

No generics in a statically typed language in 2018? Boilerplate error handling? Some say this all happened on purpose to keep things simple and minimalistic. Sorry, this doesn’t feel to me like minimalism, more like brutalism. 😄
↩
While Elixir is a great improvement on top of Erlang, limitations of dynamic virtual machines become too obvious when trying to write CPU-bound code. Calling into native binaries is quite difficult, but I love how Elixir makes distributed computing native to the language and its standard library.
↩
The situation with Python and blocking APIs is peculiar enough to be considered in more detail. I’m convinced that this is a great illustration of how important ergonomics of programming languages is. It was possible for a long time to build asynchronous non-blocking applications in JavaScript, especially with Node.js. New language features such as generators and async/await have given JavaScript mostly syntax sugar to help with patterns that have been available for a while. Compare this with Python, where even in 2018 with the availability of async/await and new libraries based on event loops, a lot of people still hesitate to make a transition to non-blocking I/O.

Admittedly, Python 2 to Python 3 migration could explain some of this conservatism, but it doesn’t explain the scarcity of callback-based APIs in Python 2. What is important to consider is a lack of a crucial, but frequently overlooked language feature: anonymous closures/lambdas with multiple statements. Lambdas in Python allow only a single expression within, and this prevents you from creating an ergonomic callback-based non-blocking API. While libraries such as Twisted existed at the time, their API based on delegates wasn’t very accessible.

In turn, delegates are pretty good when you’re able to express a required delegate shape with protocols/interfaces. Python lacks those too, although something similar can be hacked with abstract base classes.
↩

How do closures and callbacks work? It's turtles all the way down

Tue, 26 Jun 2018 12:40:32 GMT

How do closures and callbacks work? It’s turtles all the way down
Event loops, building smooth UIs, and handling high server load
Introduction to structured concurrency in Swift: continuations, tasks, and cancellation

The saying holds that the world is supported by a chain of increasingly large turtles. Beneath each turtle is yet another: it is “turtles all the way down”.

Wikipedia

By Pelf at en.wikipedia, public domain, via Wikimedia Commons

In a few episodes of great podcast Analog(ue) hosts Casey and Myke discuss Crash Course Computer Science series and how it presents abstractions. In software engineering and computer science, we constantly deal with layers of abstractions, but we don’t cross too many of them on daily basis. We work with software libraries that are built on top of a few modules and functions, which are written in a programming language, which is executed as binary code, which runs on CPUs and GPUs, which use logic gates built with transistors, to understand which you might need to understand chemistry and physics. Quite possibly someday particle physicists will discover a few more turtles further down the stack. But as long as you use that software library, you don’t need to care about logic gates, transistors and quantum tunnelling.

So here’s an abstraction that developers work with a lot: asynchronous computations. These days it’s hard to write code that doesn’t touch something asynchronous: any kind of I/O, most frequently networking, or maybe long-running tasks that are scheduled on different threads/processes. For something more concrete, consider a database query, which could be local disk I/O or something that sits somewhere on the network.

I want to write better code and build more abstractions where needed and where it makes the most sense. Because of that, I’ve recently spent a lot of time researching and trying to understand different ways to deal with asynchronous code. In a lot of programming languages callbacks is one of the ways to write it, but it’s also a relatively low level to deal with this abstraction. Nevertheless, it’s important to understand how it works on this level and what can be built on top of it. I hope my explanation could be useful to you as well.

Using closures

In Swift using callbacks is the main way to deal with asynchronicity. While Swift is taken as an example, I don’t use or discusss any advanced features here and I hope it’s going to be interesting even if you don’t use Swift on daily basis.

To pass a callback you could use a “closure”. The Swift Programming Language Guide introduces it this way:

Closures are self-contained blocks of functionality that can be passed around and used in your code. Closures in Swift are similar to blocks in C and Objective-C and to lambdas in other programming languages.

Closures can capture and store references to any constants and variables from the context in which they are defined. This is known as closing over those constants and variables.

[…]

Global and nested functions, as introduced in Functions, are actually special cases of closures. Closures take one of three forms:

Global functions are closures that have a name and do not capture any values.

Nested functions are closures that have a name and can capture values from their enclosing function.

Closure expressions are unnamed closures written in a lightweight syntax that can capture values from their surrounding context.

func example() {
  var a = 10

  func f(_ x: Int) -> Int {
    return x + a
  }
  f(5)
  // x = 5, a = 10, returns 15

  a = 15
  f(5)
  // x = 5
  // a in captured environment is 15
  // f returns 20

  let g = f
  // assigned closure f to a new constant g

  g(5)
  // x = 5
  // g now references same environment,
  // where a is set to 15
  // g returns 20

  a = 20
  f(5)
  // a in captured environment is 20
  // f returns 25

  g(5)
  // g shares environment with f,
  // where a is set to 20
  // g returns 25
}

At this point, we can say that a closure is just function code with some captured environment. “Environment” means variables and constants defined outside of closure body. “Capturing” means you have access to a variable value in the environment. If that variable was subsequently modified before closure execution, code within the closure would get the latest up-to-date value. Obviously, constant values are captured as well, but by definition, they can’t be changed.

The example code is wrapped in a function to demonstrate that environment can be local to a current scope as opposed to global environment. If variable a was declared globally, there wouldn’t be anything interesting in using its value, but capturing access to it in local scope requires special treatment in the language implementation.

As seen in the example above, closures have reference semantics, not value semantics. Assigning a closure to a variable doesn’t create a copy of that closure and its environment, but only creates a reference to that. If you were to pass a closure as an argument, it would be passed by reference, not by value.

A more interesting example of closure and callback use:

let backend = Backend()

func example() {
  let indicator = UIActivityIndicatorView()
  let label = UILabel()
  // non-blocking code
  backend.login(email, password,
    onCompletion: { success, failure in
    // code called when `backend.login` completes.

    // indicator variable captured here
    indicator.stopAnimating()

    // UILabel instance is captured here
    label.text = "\(success ?? failure)"
  })

  // ...
  // some other code here that
  // won't be blocked by `backend.login`
  // e.g. UI updates
  indicator.startAnimating()
}

How would you implement closures on a lower level?

Because explaining closures in terms of closures doesn’t make much sense, let’s imagine a programming language that doesn’t have them. To tell a story about the closure turtle, we need to place it on top of other turtles.

What follows is an example of how this could work. It doesn’t require any knowledge of how compilers work, it’s just a lower level representation of closures for our studies.

Consider a subset of Swift, where functions (including anonymous functions) can’t capture the outside environment. That is a language where this:

func example() {
  var a = 5

  func f(_ x: Int) -> Int {
    return x + a
  }

  let g = { x in return x + a }
}

would cause two compiler errors about a being undefined in the body of functions f and g.

To implement closures in this imaginary language, we’d need to use classes to get the reference semantic mentioned above. It’s also useful to have a protocol defining a generic closure shape. It could look like this:

protocol Closure: class {
  associatedtype Environment
  associatedtype Input
  associatedtype Output
  var env: Environment { get set }

  func willRun(_: Input) -> Output
}

And here’s a class conforming to this protocol and implementing our closure with example usage code:

class F: Closure {
  class Environment {
    var a: Int
    init(_ a: Int) {
      self.a = a
    }
  }

  var env: Environment

  init(_ e: Environment) {
    self.e = e
  }

  func willRun(_ x: Int) -> Int {
    return x + e.a
  }
}

func example() {
  var e = F.Environment(10)
  let f = F(e)
  f.willRun(5)
  // returns 15

  e.a = 15
  f.willRun(5)
  // returns 20

  let g = f
  g.willRun(5)
  // returns 20

  e.a = 20
  f.willRun(5)
  // returns 25

  g.willRun(5)
  // returns 25
}

Well, this is verbose. But it’s a pattern you might consider when writing in C, C++ before C++11 and its support for lambdas, or Objective-C before blocks were introduced. And here’s a point that I often don’t see mentioned when closures are explained: you can think of closures as syntactic sugar for anonymous delegates. If you have experience with Objective-C or Cocoa, you might have noticed the analogy already, I deliberately named the protocol function willRun similarly to Cocoa delegate function naming pattern.

Under the hood, a closure-capable compiler will generate a separate function body with a corresponding environment when it sees there are actual variable captures going on. In some implementations, like C++11, you have to specify a list of captured variables explicitly. In Objective-C, that’s what the __block modifier is for, while in Swift it’s automatic by default with a possibility to override it. The latter is quite handy when you want some variables to be captured with weak references to avoid reference cycles.

Callbacks and asynchronous code

In a lot of cases using the right abstractions saves us from verbosity in our code. Are callbacks a good abstraction for all asynchronous scenarios then?

Consider a more complex version of the code we’ve seen before:

let label = UILabel()
// non-blocking code
backend.login(email, password,
  onCompletion: { success, failure in
  // called when `backend.login` completes.
  // UILabel instance is captured here
  label.text = success

  guard !failure else {
    // ...
    // error handling here
    return
  }

  // notice `backend` is captured here as well
  backend.fetchUserInfo { userInfo, failure in
    guard !failure else {
      // ...
      // error handling here again
      return
    }

    if userInfo.isAdmin {
      backend.doAdminStuff { success, failure in
        guard !failure {
          // tired of repeated manual
          // error handling by this point...
          return
        }

        // ...
        // more code here to
        // handle admin stuff results
      }
    }
  }
})

// ...
// some other code here that
// won't be blocked by `backend.login`

To handle a sequence of async actions we need to use nested callbacks. Turns out it’s quite easy to start building these pyramids of doom. Error handling is quite tedious and overall this type of code becomes quite error-prone with shadowed variables all around: notice shadowed failure callback argument within all completion handlers. With plain callbacks, this isn’t an exaggerated scenario, you can often stumble upon this when building real apps that involve any kind of long-running non-blocking operation, e.g. networking.

Promises of future turtles

There is a way out, consider a concept called “futures”, also know as “promises”. Using BrightFutures library as an example, the pyramid of doom can be converted to this flat chain of futures:

let label = UILabel()
// non-blocking code
backend.login(email, password)
.flatMap { success in
  // called when `backend.login` succeeds.
  // UILabel instance is captured here
  label.text = success

  return backend.fetchUserInfo()
}
.onSuccess { userInfo in
  if userInfo.isAdmin {
    return backend.doAdminStuff()
    .onSuccess {
      // ...
      // more code here to handle
      // admin stuff results
    }
  }
}
.onFailure {
  guard !failure else {
    // ...
    // unified error handling here,
    // that can be triggered by any
    // future in the chain
    return
  }
}

// ...
// some other code here that
// won't be blocked by `backend.login`

That’s much better, we have only one error handler that will be triggered regardless of where an error might occur. There is only one nested callback after backend.fetchUserInfo() and only because we have other async code executed on a condition that our user is an admin. More readability and much easier to maintain and refactor if you need to re-order the async operations.

This code assumes you’ve converted all callback-based functions like login, fetchUserInfo and doAdminStuff to return futures. What’s a future? Think of it as a container that can only be opened at some later time (in the future) and it might contain either an actual result or an error. You can attach callbacks to a future “container” to be triggered when the computation is ready, and you can chain these containers together to run a sequence (or sometimes a parallel batch) of asynchronous computations. A simplified declaration could look like this:

class Future<Result> {
  func onSuccess(callback: (Result) -> ())
    -> Future<Result>
  func onFailure(callback: (Error) -> ())
    -> Future<Result>
  func map<NewResult>(transformer: (Result) -> NewResult)
    -> Future<NewResult>
  func flatMap<NewResult>(transformer: (Result) -> Future<NewResult>)
    -> Future<NewResult>
}

There’s a peculiar flatMap function here. In a few other Swift libraries implementing futures, it’s called then, which is a more straightforward name if you don’t focus on the container aspect of futures. In the JavaScript standard library the Promise class uses the name then as well.

So why name it flatMap? Turns out there is already a flatMap function in Swift standard library defined on the Sequence protocol, which is similar to map you’ve probably used if you’re into functional programming. Standard map transforms a container of elements of type A to a container of elements of type B with a closure of type (A) -> B. flatMap does the same for closures of type (A) -> [B], if we assume this container is an array. With simple map the end result would be of type [[B]], which is a container of containers. This isn’t something you’d always want, so to “flatten” these containers to only one level [B] use flatMap. It works the same way for all types of containers that implement the Sequence protocol.

To chain Future<A> with Future<B> that depends on result A, our result transformer closure would need to look like A -> Future<B>. Taking this analogy further, if you applied this closure to simple map, you’d get the end result of type Future<Future<B>>, which is bananas and doesn’t make any sense. Hence we use flatMap to get a “flat” result type.

More turtles coming…

We’ve just reviewed closures and had a quick look at how they’re used for callbacks. We tried to write asynchronous code with callbacks and found that it’s not very maintanable. In the end we tried using futures, which leveraged closures as well, but allowed us to structure the example code in a better way.

Admittedly, this futures stuff is an ok abstraction, but it doesn’t feel as smooth writing plain old synchronous code. If only we could write non-blocking asynchronous code that almost looked like usual synchronous code… Turns out, plenty of programming languages provide a few abstractions to work with asynchronous code and concurrency, like coroutines and async/await syntax sugar in JavaScript, Python, C# to name a few. Some take a different approach, e.g. Erlang/Elixir and Pony are built on actor model, while Go introduces goroutines and channels.

Acknowledgements

Special thanks to Neil Kimmett for feedback on draft versions of this article. Thanks to Thomas Visser for BrightFutures library, which is still the best helper for writing async code in Swift in my opinion.

Why I use GraphQL and avoid REST APIs

Mon, 28 May 2018 12:40:32 GMT

Server interactions take a significant amount of time and effort to develop and test in most mobile and web apps. In apps with most complex APIs I worked on, the networking layer took up to 40% of the development time to design and maintain, specifically due to some of the edge cases I mention below in this article. After implementing this a few times, it’s easy to see different patterns, tools and frameworks that can help with this. While we’re lucky (well, most of us are, I hope) not to care about SOAP anymore, REST isn’t the end of history either.

Recently I had a chance to develop and to run in production a few mobile and web apps built with GraphQL APIs, both for my own projects and my clients. This has been a really good experience, not least thanks to wonderful PostGraphile and Apollo libraries. At this point, it’s quite hard for me to come back and enjoy working with REST.

But obviously, this needs a little explanation.

So what’s wrong with REST?

Every REST API is a snowflake

To be fair, REST isn’t even a standard. Wikipedia defines it as

an architectural style that defines a set of constraints and properties based on HTTP

While something like JSON API spec does exist, in practice it’s very rare that you see a RESTful backend implementing it. In best case scenario, you might stumble upon something that uses OpenAPI/Swagger. Even then, OpenAPI doesn’t specify anything about APIs shape or form, it’s just a machine-readable spec, that allows (but not requires) you to run automatic tests on your API, automatically generate documentation etc.

The main problem is still there. You may say your API is RESTful, but there are no strict rules in general on how endpoints are arranged or whether you should, for example, use PATCH HTTP method for object updates.

There are also things that look RESTful on a first glance, but not so much if you squint: Dropbox HTTP API.

endpoints accept file content in the request body, so their arguments are instead passed as JSON in the Dropbox-API-Arg request header or arg URL parameter.

JSON in a request header? (╯°□°）╯︵ ┻━┻

That’s right, there are Dropbox API endpoints that require you to leave request body empty and to serialise a payload as JSON and chuck it an a custom HTTP header. It’s fun to write client code for special cases like this. But we can’t complain, because there is no widely-used standard after all.

In fact, most of the caveats mentioned below are caused by lack of a standard, but I’d like to highlight what I’ve seen in practice most frequently.

And yes, you can avoid most of these problems in a disciplined experienced team, but wouldn’t you want some of this stuff to be resolved already on a software side?

No static typing means caring about type validation

No matter how much you try to avoid this, sooner or later you stumble upon misspelt JSON properties, wrong data types sent or received, fields missing etc. You’re probably ok if your client and/or server programming language is statically typed and you just can’t construct an object with a wrong field name or type. You’re probably doing good if your API is versioned and you have an old version on /api/v1 URL and a new version with a renamed field on /api/v2 URL. Even better if you have an OpenAPI spec that generates client/server type declarations for you.

But can you really afford all this in all your projects? Can you afford setting up /api/v1.99 endpoint when during a sprint your team decides to rename or rearrange object fields? Even if it’s done, will the team not forget to update the spec and to ping the client devs about the update?

You sure you have all the validation logic right either on client or on server? Ideally, you want it validated on both sides, right? Maintaining all of this custom code is a lot of fun. Or keeping your API JSON Schema up to date.

Pagination and filtering is not so simple

Most APIs work with collections of objects. In a todo-list app, the list itself is a collection. Most collections can contain more than 100 items. For most servers returning all items in a collection in same response is a heavy operation. Multiply that by a number of online users and it can add up to a hefty AWS bill. Obvious solution: return only a subset of a collection.

Pagination is comparatively straightforward. Pass something like offset and limit values in query parameters: /todos?limit=10&offset=20 to get only 10 objects starting at the 20th. Everyone names these parameters differently, some prefer count and skip, I like offset and limit because they directly correspond to SQL modifiers.

Some backend databases expose cursors or tokens to be passed for next page query. Check out Elasticsearch API that recommends using scroll calls when you need to go through a huge list of resulting documents sequentially. There are also APIs that pass relevant information in headers. See GitHub REST API (at least that’s not JSON passed in headers 😅).

When it comes to filtering, it’s so much more interesting… Need filtering by one field? No problem, it could be /todos?filter=key%3Dvalue or maybe more human-readable /todos?filterKey=key&filterValue=value. How’s about filtering by two values? Hm, that should be easy, right? Query would look like /todos?filterKeys=key1%2Ckey2&filterValue=value with URL encoding. But often there is no way to stop the feature creep, maybe a requirement appears for advanced filtering with AND/OR operators. Or maybe complex full-text search queries together with complex filtering. Sooner or later you can see a few APIs that invent their own filtering DSL. URL query components are no longer sufficient, but request body in GET requests is not great either, which means you end-up sending non-mutating queries in POST requests (which is what Elasticsearch does). Is the API still RESTful at this point?

Either way, both clients and servers need to take extra care with parsing, formatting and validating all these parameters. So much fun! 🙃 As an example, without proper validation and with uninitialised variables you can easily get something like /todos?offset=undefined.

Not easy to document and test

Swagger mentioned above is probably the best tool for this at the moment, but it isn’t used widely enough. Much more frequently I see APIs with documentation maintained separately. Not a big deal for a stable widely used API, but much worse during development in an agile process. Documentation stored separately means it’s frequently not updated at all, especially if it’s a minor, but client-breaking change.

If you don’t use Swagger, it probably means you have specialised test infrastructure to maintain. There’s also a much higher chance you need integration tests rather than unit-tests, means testing both client and server-side code.

Relations and batch queries make it even more frustrating

This becomes a problem with much larger APIs, where you might have a number of related collections. Let’s go further with an example of a todo-list app: suppose every todo item can also belong to a project. Would you always want to fetch all related projects at once? Probably not, but then there are more query parameters to add. Maybe you don’t want to fetch all object fields at once. What if the app needs projects to have owners and there’s a view with all this data aggregated in addition to separate views displaying each collection separately? It’s either three separate HTTP requests or one complex request with all data fetched at once for aggregation.

Either way, there are complexity and performance tradeoffs, maintaining which in a growing application brings more headaches than one would like.

You need every endpoint implemented both on server and client

There is also a ton of libraries that can automatically generate a REST endpoint with some help from ORMs or direct database introspection. Even when those are used, usually they aren’t very flexible or extensible. That means reimplementing an endpoint from scratch if there is a need for custom parameters, advanced filtering behaviour or just some smarter handling of request or response payload.

Yet another task is consuming those endpoints in client code. It’s great to use code-generation if you have it, but again it seems to be not flexible enough. Even with helper libraries like Moya, you stumble upon the same barrier: there is a lot of custom behaviour to handle, which is caused by edge cases mentioned above.

If a dev team isn’t full-stack, communication between server and client teams is crucial, even critical when there’s no machine-readable API spec.

And how’s GraphQL better?

With all issues discussed, I’m inclined to say that in CRUD apps it would be great to have a standard way to produce and consume APIs. Common tooling and patterns, integrated testing and documentation infrastructure would help with both technical and organisational issues.

GraphQL has a draft RFC spec and a reference implementation. Also, check out GraphQL tutorial, which describes most of the concepts you’d need to know. There are implementations for different platforms, and there is plenty of developer tools available as well, most notably GraphiQL, which bundles a nice API explorer with auto-completion and a browser for documentation automatically generated from a GraphQL schema.

In fact, I find GraphiQL indispensable. It can help in solving communication issues between client and server-side teams I’ve mentioned earlier. As soon as any changes are available in a GraphQL schema, you’ll be able to see it in GraphiQL browser, same with embedded API documentation. Now client and server teams can work together on API design in an even better way with shorter iteration time and shared documentation that’s automatically generated and visible to everyone on every API update. To get a feeling of how these tools work check out a Star Wars API example that is available as a GraphiQL live demo.

Being able to specify object fields requested from a server allows clients to fetch only data they need when they need. No more multiple heavy queries issued to a rigid REST API, which are then stitched on the client just to display it all at once in app UI. You are no longer restricted to a set of endpoints, but have a schema of queries and mutations, being able to cherry-pick fields and objects that a client specifically requires. And a server only needs to implement top-level schema objects this way.

A quick example

A GraphQL schema defines types that can be used in communication between servers and clients. There are two special types that are also core concepts in GraphQL: Query and Mutation. Most of the time every request that is issued to a GraphQL API is either a Query instance that is free of side-effects or a Mutation instance that modifies objects stored on the server.

Now, sticking with our todo app example, consider this GraphQL schema:

type Project {
  id: ID
  name: String!
}

type TodoItem {
  id: ID
  description: String!
  isCompleted: Boolean!
  dueDate: Date
  project: Project
}

type TodoList {
  totalCount: Int!
  items: [TodoItem]!
}

type Query {
  allTodos(limit: Int, offset: Int): TodoList!
  todoByID(id: ID!): TodoItem
}

type Mutation {
  createTodo(item: TodoItem!): TodoItem
  deleteTodo(id: ID!): TodoItem
  updateTodo(id: ID!, newItem: TodoItem!): TodoItem
}

schema {
  query: Query
  mutation: Mutation
}

This schema block at the bottom is special and defines root Query and Mutation types as described previously. Otherwise, it’s pretty straightforward: type blocks define new types, each block contains field definitions with their own types. Types can be non-optional, for example String! field can’t ever have null value, while String can. Fields can also have named parameters, so allTodos(limit: Int, offset: Int): TodoList! field of type TodoList! takes two optional parameters, while its own value is non-optional, meaning it will always return a TodoList instance that can’t be null.

Then to query all todos with ids and names you’d write a query like this:

query {
  allTodos(limit: 5) {
    totalCount
    items {
      id
      description
      isCompleted
    }
  }
}

GraphQL client library automatically parses and validates the query against the schema and only then sends it to a GraphQL server. Note that offset argument to allTodos field is absent. Being optional, its absence means it has null value. If the server supplies this sort of schema, it’s probably stated in documentation that null offset means that first page should be returned by default. The response could look like this:

{
  "data": {
    "allTodos": {
      "totalCount": 42,
      "items": [
        {
          "id": 1,
          "description": "write a blogpost",
          "isCompleted": true
        },
        {
          "id": 2,
          "description": "edit until looks good",
          "isCompleted": true
        },
        {
          "id": 2,
          "description": "proofread",
          "isCompleted": false
        },
        {
          "id": 4,
          "description": "publish on the website",
          "isCompleted": false
        },
        {
          "id": 5,
          "description": "share",
          "isCompleted": false
        }
      ]
    }
  }
}

If you drop isCompleted field from the query, it’ll disappear from the result. Or you can add project field with its id and name to traverse the relation. Add offset parameter to allTodos field to paginate, and so allTodos(count: 5, offset: 5) will return the second page. Helpfully enough, you’ve got totalCount field in the result, so now you know you’ve got 42 / 5 = 9 pages in total. But obviously, you can omit totalCount if you don’t need it. The query is in full control of what actual information will be received, but underlying GraphQL infrastructure also ensures that all required fields and parameters are there. If your GraphQL server is smart enough, it won’t run database queries for fields you don’t need, and some libraries are good enough to provide that for free. Same with the rest of mutations and queries in this schema: input is type-checked and validated, and based on the query a GraphQL server knows what result shape is expected.

Under the hood, all communication runs through a predefined URL (usually /graphql) on a server with a simple POST request that contains the query serialised as a JSON payload. You almost never have a need to be exposed to an abstraction layer this low though.

Not too bad overall: we’ve got type-level validation issues taken care of, pagination is also looking good and entity relations can be easily traversed when needed. If you use some GraphQL -> database query translation libraries that are available, you wouldn’t even need to write most of the database queries on the server. Client-side libraries can unpack a GraphQL response automatically as an object instance of a needed type quite easily, as naturally the response shape is known upfront from the schema and queries.

GraphQL is this new hipster thing, a fad, right?

While falcor by Netflix seemed to be solving a similar problem, was published on GitHub a few months earlier than GraphQL and came up on my personal radar earlier, it clearly looks like GraphQL has won. Good tooling and strong industry support make it quite compelling. Aside from a few minor glitches in some client libraries (that since have been resolved), I can’t recommend highly enough to have a good look at what GraphQL could offer in your tech stack. It is out of technical preview for almost two years now and the ecosystem is growing even stronger. While Facebook designed GraphQL, we see more and more big companies using it in their products as well: GitHub, Shopify, Khan Academy, Coursera, and the list is growing.

There’s plenty of popular open-source projects that use GraphQL: this blog is powered by Gatsby static site generator, which translates results of GraphQL queries into data that are rendered into an HTML file. If you’re on WordPress, a GraphQL API is available for it as well. Reaction Commerce is an open-source alternative to Shopify that’s also powered by GraphQL.

A few GraphQL libraries worth mentioning again are PostGraphile and Apollo.

If you use PostgreSQL as your database on the backend, PostGraphile is able to scan a SQL schema and automatically generate a GraphQL schema with an implementation. You get all common CRUD operations exposed as queries and mutations for all tables. It may look like it’s an ORM, but it isn’t: you’re in full control of how your database schema is designed, and what indices are used. Great thing is that PostGraphile also exposes views and functions as queries and mutations, so if there is particularly complex SQL query that you’d like to map to a GraphQL field, just create that SQL view or function and it’ll appear automatically in GraphQL schema. With advanced Postgres features like row-level security, you can get complex access control logic implemented with only a few SQL policies to write. PostGraphile even has awesome things like schema documentation generated automatically from Postgres comments 🤩.

In turn, Apollo provides both client libraries for multiple platforms and code generators that produce type definitions in most popular programming languages, including TypeScript and Swift. In general, I find Apollo much simpler and manageable to use than, for example, Relay. Thanks to simple architecture of Apollo client library, I was able to slowly transition an app that used React.js with Redux to React Apollo, component by component and only when it made sense to do so. Same with native iOS apps, Apollo iOS is a relatively lightweight library that’s easy to use.

In a future article, I’d like to describe some of my experience with this tech stack. In the meantime, shoot me a message on Twitter about your experience with GraphQL or if you’re just interested how it could work in your app 👋.