Cocoa with Love

Using Copilot to write a raindrop audio synthesizer using AVAudioEngine

Wed, 25 Dec 2024 21:35:10 +1100

I’ve largely ignored the use of large language models (LLMs) as programming assistants, despite (or because of) the hype of the last 2 years. I’ve had a preconception that an LLM might not work well enough or might not meet my expectations of code quality.

Since Microsoft have recently made the lowest tier of GitHub Copilot for VS Code free, I wanted to test that preconception and see how helpful LLM-assisted programming might be when implementing a small project in Swift. And maybe this will make an interesting point of comparison to Apple’s Swift Assist (if and when that’s finally available).

As for the project itself: I wanted to explore sound synthesis using AVAudioEngine after stumbling across a GitHub repository that implied a raindrop could be synthesized using a very simple waveform. It seems unlikely that a simple waveform would produce a convincing raindrop sound but the project should be well within the “few thousand line” context limit for an LLM so I think it’s an achievable goal.

That buzzword: I won’t be using the term “AI” to describe these assistants. I wrote my engineering thesis on computer vision using neural networks more than 20 years ago and back then, the term “AI” was reserved for science fiction, “artificial general intelligence” or for use by people deceptively implying general intelligence when the truth was quite different.

The setup

I’m running Visual Studio Code 1.96.2 and using its built-in connection to Github Copilot (GPT 4o) that is currently free to use if you authorise via your GitHub account. In VS Code, I’ve installed the Swift v1.11.4 extension for Swift language server support and SweetPad 0.1.48 for building via Xcode and ensuring VS Code behaves better on Xcode Projects.

If you haven’t used SweetPad before, you need to set it up for each project by typing Command-Shift-P in VS Code and choosing “SweetPad: Generate Build Server Config” from the popup that appears and then selecting the build target so it can create a buildServer.json file. Additionally, the Swift extension might ask to configure itself (global is usually fine).

If you aren’t prompted when you launch VS Code, you may need to enable Copilot Free in VS Code to configure Copilot. When you want to ask Copilot something, press Command-Control-I and that will present a chat window where you can prompt Copilot to write new code or refactor existing code.

I haven’t really spent enough time configuring VS Code the way I like it so outside of interacting with Copilot, I’m likely to do most of my editing, building and running in Xcode itself.

Check it out: you can download the code for this article from the RainGenerator repository. The commit history includes most of the steps discussed in this article.

Alternative setup

Not to offer too much of a peek behind the curtain but I ran this same experiment nearly a month ago using Cursor (a fork of Visual Studio Code designed to focus on these LLM-based workflows). Thomas Ricouard has written a pretty good article on using Cursor for iOS development, if you’d like to know more. I think the Claude 3.5 LLM that Cursor uses by default did produce slightly better code than Copilot but the difference between VS Code and Cursor or Copilot and Claude wasn’t huge (the broad strokes are identical between each). This article will focus on my Copilot experience since I didn’t really document my Cursor experience (although the first commit in the repository still has a date of December 1 from the Cursor timeline).

Tone Generator

First effort

I wanted to start the project simple so to begin, I thought I’d ask Copilot to do something very simple that I’ve written about before: a tone generator. That code involves a huge amount of boilerplate that shouldn’t be rerequired in AVAudioEngine (the latest iteration of the same audio processing graph concept).

While I’ve read about AVAudioEngine (introduced between macOS 10.10 and 10.15) I haven’t really had the chance to use it so maybe Copilot can show me how it’s done.

Prompt: Create a Tone Generator that plays a sine, square, or sawtooth waveform and offers sliders to control volume and frequency.

The only context I’ve provided to Copilot is a ContentView.swift file, so I’m hoping it will understand that I’d like a SwiftUI interface. But I haven’t mentioned AVAudioEngine.

How does Copilot fair?

Copilot’s first effort

It has created an AudioEngine class that tries to render to a PCM buffer and play that in a loop. But it looks clunky (there’s no real need for separate “Play” and “Stop” buttons and that “Frequency” slider is using a step size of 1 with 2000 steps, making it slow and largely unusable) but worst of all, it doesn’t work. Hitting play throws an exception.

Not a great start.

Looking at the code, it’s pretty simple to see that the exception is because the format in the init function – as used to connect the player to the outputNode – is not the same as the format used in the start function and the mismatch is leading to a runtime exception.

    init() {
        engine.attach(player)
        let format = engine.outputNode.inputFormat(forBus: 0)
        engine.connect(player, to: engine.outputNode, format: format)
        try? engine.start()
    }

    func start(waveform: Waveform, frequency: Double, volume: Double) {
        let sampleRate = 44100
        let length = AVAudioFrameCount(sampleRate)
        let format = AVAudioFormat(standardFormatWithSampleRate: Double(sampleRate), channels: 1)!
        buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: length)
        buffer?.frameLength = length

Let’s see if Copilot can sort out this problem.

Prompt: The AudioEngine isn’t making a sound. Can you identify what is wrong?

Copilot adds a catch around the creation of the AVAudioEngine (previously it was using a try?):

do {
    try engine.start()
} catch {
    print("Error starting audio engine: \(error.localizedDescription)")
}

Yeah, it didn’t have a clue.

Maybe if I give Copilot the exact exception, it can fix the problem.

Prompt: Can you fix the following exception that is thrown when scheduleBuffer is called: “required condition is false: [AVAudioPlayerNode.mm:740:ScheduleBuffer: (_outputFormat.channelCount == buffer.format.channelCount)]”

With this, Copilot does make the audio play – by changing the format line in the start function to:

let format = engine.outputNode.inputFormat(forBus: 0)

However, even though the audio plays, it is mono, in the left speaker only. A proper fix would have been to take the format, as defined in the start function, and use it when connecting the player in the init function. I can do that manually and if I also remove the step from the Frequency slider in the UI (so the app doesn’t hang when trying to draw the slider), then the app “works”.

Second effort

I want to see if Copilot can handle a bit of cleanup if I give it the steps. Instead of pre-rendering a PCM buffer and looping that, I prefer to use a render function that generates the audio-on-the-fly.

Prompt: Refactor the AudioEngine to generate audio using an AVAudioSourceNode render block that calls a generateSample function. Move the @State variables from the ContentView into the AudioEngine and make the ContentView observe the AudioEngine.

Copilot follows all my instructions and the code now ends up looking better but it has gone from “working” to “not working”, again. Now the tone plays immediately on application startup and the “Play” and “Stop” buttons no longer work.

For some reason, alongside the requested changes, Copilot decided to change the start and stop functions to set the engine.mainMixerNode.outputVolume to 1 or 0 (instead of actually pausing the audio generation). This is a bad idea (you should either pause or stop when audio generation is paused by the user). But it doesn’t work because in the current state, the mainMixerNode is not being added to the graph at all, so setting volume on it has no effect.

Getting a little exhausted with these issues, I resort to manually editing the code: calling start() and stop() on the engine instead of changing the volume, removing the step parameter from the frequency slider that was making it practically unusable and replacing the separate “Play” and “Stop” buttons with a single toggle button that changes its label.

So far, I’ve spent about 20 minutes of cleanup, plus inspection and LLM prompting, on what’s less than 200 lines of code. I could probably have written the code myself in this time so I feel like it’s a borderline call about whether the LLM is helping at this point.

Let’s synthesize a raindrop sound

I had an ulterior motive with this entire exercise. I didn’t really want a tone generator. I really wanted to try a raindrop sound synthesizer. I had randomly stumbled across GitHub repository https://github.com/747745124/Raindrop-Generator and wanted to try the simple waveform it suggested might sound like a raindrop.

Schematic of the sound produced by a water droplet falling onto a liquid surface. Credit Stanley J. Miklavcic, Andreas Zita and Per Arvidsson

Grabbing the “drop_v2.hpp” file from that repository, I asked Copilot to swap the tone generator for a raindrop generator.

Prompt: The samples generated by generateSample in AudioEngine are a basic tone with either a sine, square or sawtooth waveform. Replace this tone generation with a raindrop sample generation. Use the algorithm in drop_v2.hpp for the raindrop sound.

This change broke the compile since it removed a number of parameters that the ContentView referenced but after cleaning that up, this step in the exercise was by far the most impressive help that Copilot was able to give.

Ordinarily, when given a new piece of code, in an unfamiliar language and told to integrate the algorithm into an existing codebase, most programmers would need time to process, time to understand and time to feel out the best way to apply.

For an LLM, translating from one context to another is their biggest strength. It’s no problem that one codebase is C++ and the other is Swift. You could argue that all an LLM ever really does is take the pattern and structure of content absorbed in one context and re-emitting that content in a way that follows on from a new context.

However, it’s difficult to tell that this code is working from the audio alone, since it is playing just one 20ms raindrop sound and then stopping.

We’re going to need more drops.

Prompt: The AVAudioSourceNode render function currently plays a single raindrop sound from the rainDrop variable which stops playing once time reaches tInit + deltaT3. This code should be changed so that instead of a single raindrop, there’s an array of raindrops. This array should initially contain just one raindrop but more raindrops should be added to the array after random intervals so that a target number of raindrops are added per minute.

For reasons that are not clear, Copilot ignored the request for “random” and instead the drops are being scheduled precisely sampleInterval apart.

After plugging in a rough “random” concept (I don’t think I’ve done a great job, here) and hooking up some sliders to the new sampleInterval and randomness properties that Copilot has decided to include, the app now looks like this:

A raindrop synthesizer that actually works

I’m not sure what that “randomness” parameter is supposed to be. It’s not randomizing the interval between drops and is instead hooked up to a number of internal parameters in a seemingly haphazard way.

Charting the waveform

The drops sometimes sound like raindrops on a tent, sometimes like small drops in a water glass and often like someone playing a toy xylophone. If nothing else, I’d like to confirm that my waveforms match that in the “A simple water droplet waveform” graph that I showed, above.

To do this, it would be helpful to plot the waveform.

Prompt: I would like to use Swift Charts in the ContentView to show a sample waveform generated by the AudioEngine that updates as the user adjusts the sliders in the ContentView.

This did add a Swift Chart but it showed nothing.

A little inspection revealed that it was plotting the first 1000 samples… of a 44kHz waveform, so just 250 microseconds. Additionally, it was trying to plot all raindrops but I wanted the waveform of a single raindrop.

Prompt: For the generateWaveform function, just generate the waveform from a single raindrop, created locally from the createNewRaindrop function.

Again, some cleanup was needed. I also decided to color code things and hook up sliders to all the key variables (asking Copilot to do this just made a mess).

The end result though is quite nice:

The waveform of the synthesized raindrop

This confirms that the synthesized raindrop is approximately the same as the target waveform.

Adding some noise

In terms of synthesizing the sound of a raindrop – it’s not great. I can tweak the parameters but it never really sounds like a raindrop and definitely never sounds like rain.

Most people who synthesize rain generally start with a noise generator. There are different types of noise (white, pink, brown). While I know how to write white noise, I’m not sure about brown and don’t have any knowledge of pink noise.

So I make Copilot do it.

Prompt: Add pink noise to the audio generated by the AudioEngine.

func generatePinkNoise() -> Float {
    let white = Float.random(in: -1.0...1.0)
    pinkNoiseState[0] = 0.99886 * pinkNoiseState[0] + white * 0.0555179
    pinkNoiseState[1] = 0.99332 * pinkNoiseState[1] + white * 0.0750759
    pinkNoiseState[2] = 0.96900 * pinkNoiseState[2] + white * 0.1538520
    pinkNoiseState[3] = 0.86650 * pinkNoiseState[3] + white * 0.3104856
    pinkNoiseState[4] = 0.55000 * pinkNoiseState[4] + white * 0.5329522
    pinkNoiseState[5] = -0.7616 * pinkNoiseState[5] - white * 0.0168980
    let pink = pinkNoiseState[0] + pinkNoiseState[1] + pinkNoiseState[2] + pinkNoiseState[3] + pinkNoiseState[4] + pinkNoiseState[5] + pinkNoiseState[6] + white * 0.5362
    pinkNoiseState[6] = white * 0.115926
    return pink
}

It got this right, first time. I think. Honestly, I don’t know what pink noise is supposed to do.

Looking around to see how pink noise generation should look, Copilot appears to have chosen an implementation of the “Voss-McCartney algorithm” for pink noise and it has a fairly long history.

Further adding brown noise and white noise and hooking up some sliders gives the final form of the app:

Raindrop and noise generator

Cleaning up thread safety

It seems that the AVAudioSourceNode closure is missing an @Sendable annotation so even though Swift 6 doesn’t give any warnings, the code at this point is thread unsafe. In fact, if you annotate AudioEngine with @MainActor, you’ll get a fatal error at runtime when the render closure is invoked, indicating that Swift 6 is under the (incorrect) assumption that the closure will run in the same context as the surrounding type.

I don’t think there’s anything that would crash the app if the thread safety is left unaddressed – just some parameters that may be invalid or fail to update correctly – but it’s not a good idea to write to the parameters on the main thread and read them from the audio render thread without some form of synchronization.

I asked Copilot to fix the problem:

Prompt: To ensure thread safety in the AudioEngine class, apply these steps:

Add the @MainActor annotation to the AudioEngine class.
Add the @Sendable annotation to the AVAudioSourceNode closure.
Add the nonisolated keyword to the generateAudio function.
Use Atomic values to copy parameters from the main actor to the generateAudio function.

Copilot ignored the request for an @Sendable annotation and used an NSLock instead of Atomic so it wasn’t exactly what I wanted. I can’t really fault Copilot since I’m also not sure how to correctly use Atomic to solve this problem. In the end, the final commit in this repository (applied manual during a final cleanup phase) adds thread safety via Swift’s new Mutex type. I’m not completely happy with that (you don’t generally want to deal with locks on the audio processing thread) but I’m not sure what the best pattern for exchanging data via Atomic would be.

Conclusion

Check it out: the final product plus most of the intermediate steps discussed in this article are available from the RainGenerator repository.

Is it a good rain synthesizer?

Not really but it was fun to play with, especially once I could see the waveform via the chart.

It turns out that the rough waveform came from a paper by Stanley J. Miklavcic; Andreas Zita; Per Arvidsson which goes more into depth about necessary randomization, distribution and spatial effects in order make the raindrops sound more real and even then concludes that other water, flowing and storm sounds are required to fill out the complete soundscape of rain.

What was Copilot good at?

I asked Copilot to perform a number of refactoring passes and it was generally good at following instructions and cleaning up the integration points. This project is less than 500 lines though, so I don’t know how well it might scale to a more functional sized app.

For SDKs where I wasn’t familiar, it was quicker to give Copilot a vague description of intent than to look up the documentation, read the documentation and integrate into the surrounding context. This is a big win and might help to eliminate the trepidation involved in working with new SDKs.

Copilot was really good at integrating existing code from another location, even when that code was in a different programming language.

It was also really good at looking up how to implement a relatively obscure algorithm like pink noise, even when it’s not an algorithm where the first result in a web search will give a good response.

Ways in which Copilot was better than expected but not great

I never had a syntax error.

I expected more hallucinations or references to non-existent symbols. I really only experienced one variable that didn’t exist (from the Claude chatbot) and one function that didn’t exist (from Copilot). The non-existant function was Float.clamped(to: ClosedRange<Float>) – which I simply implemented as it’s likely just an extension that Copilot has trained on without realizing it’s not a Swift extension.

Other compilation errors I experienced were generally minor (e.g. use of iOS only APIs on the Mac and a use of a variable before the init function had finished initializing) or an update to one file that breaks another file not included in the chat context.

What was Copilot bad at?

I immediately wanted to make minor changes to almost everything Copilot wrote.

The most common problems were violations of “Don’t repeat yourself”, “Keep it simple, stupid”, missing abstractions or unneeded indirection. Just about every common coding problem was there.

Copilot would repeat code a lot in SwiftUI with the same set of modifiers applied without any desire to avoid repetition. Copilot would also do goofy things like adding didSet or onChange handlers everywhere instead of simply changing the underlying data without a layer of indirection.

I ended up manually adding AudioEngine subtypes – Raindrop, Parameters and GeneratorState – to encapsulate parameters and state and simplify observing and updates because Copilot doesn’t seem to do any such tidy ups without explicit instruction.

As discussed, Copilot left the audio graph incompletely connected, failed to get audio formats aligned between functions. Unless two functions are directly interfacing, it doesn’t seem to check if they’re doing anything related that should be made common.

In some requests, it would outright ignore part of the instructions like “random intervals” or “add @Sendable” to this closure. Other requests like “tidy up the user interface so things are more compact and aligned” don’t seem to have any practical effect (though Copilot might respond by adding a bunch of repetitive modifiers like onChange to each slider for no reason).

Copilot never seemed to work out that I was writing a Mac app and kept trying to stick a green background with corner radius inside the Mac “bordered” buttons (really unsightly) and it tried color everything systemGray6 (I’m not sure why a color should be iOS-only but it is). Perhaps this is my fault for failing to inform the bot about the compile target but it’s just another way you need to work to keep an LLM assistant behaving correctly.

This Mac button already has a border, and even if this was iOS, that’s probably too much green

Languages and SDKs evolve pretty quickly and Copilot still seems to prefer @ObservableObject over @Observable and seems largely unaware of Swift 6, @Sendable, Atomic and other changes in the last 6 months. You’re limited to its training set and that’s never going to include as much “upcoming” code as “legacy” code.

Problems with VS Code + Copilot for Swift

Rounding out the negatives are a number of ergonomic problems related to VS Code and its current integration of Copilot.

Any time I manually made changes to the code there’s the problem that this can make the code out-of-sync with the chat window so if you do ask Copilot for more changes, it may behave like your manual changes don’t exist and revert them in its next refactor creating a situation where bugs and entire previous states of the app may reappear.

With code naturally spanning multiple files, it’s easy to forget to include all files in the chat context and have refactoring changes break the connections between two files. What I’d really like is an IDE that automatically detected which files and functions are actually relevant to the context and automatically include them with the request.

And finally, VS Code isn’t Xcode, so it’s not an environment focussed on Swift development. Another developer might be familiar with VS Code but I’m not and I found myself bouncing between IDEs a lot.

Was Copilot worth it?

Sometimes, yes. But not always and therein lies an estimation risk. Is it saving me time by writing code I need or wasting my time by making a mess or adding code I don’t want?

It can be hard to guess whether it would be faster to ask Copilot to improve its own code or to skip Copilot and apply the fix manually. Just typing out a detailed request for changes can take longer than making the changes myself – largely because I’m really accustomed to editing code but I find that being accurate in prose is a slow process. Trying to clean up code details by talking in chat with Copilot can start to feel like a sunk cost problem. Combined with the above-mentioned complication that blending Copilot and manual changes can cause chat to lose sync with the code, it becomes exhausting.

Working with an LLM assistant really does feel like training a very keen but very messy new developer – totally happy to write 1000 lines of code to solve a problem that should be solved in 100 lines and when the PR comes in, you need to slowly walk them through all the things they need to change before you can feel like the code is maintainable.

There is a big difference though: with the new developer, the time taken to help them fix their code isn’t time wasted. They’ll improve, get accustomed to the patterns and expectations of the codebase and in 6 to 12 months their PRs will be easier to review and they’ll start fixing your dumb mistakes.

By contrast: Copilot is not learning from my suggestions. There’s nothing to be won by making it clean up its own mess if a manual change would have been faster.

App architecture basics in SwiftUI Part 4: Services

Tue, 23 Mar 2021 08:37:06 +1000

This article is about adding a separated Services-layer to an app. A Services-layer is, in my opinion, the single best app architectural addition you can make, after the basic Model-View separation already implicit in SwiftUI. Model-View separation decouples the Model from the front-end but a Services-layer completes Model separation by separating the Model from the back-end and is one of the few app architectural changes you can point at and say: this change unlocks these capabilities.

I’ll be changing just 9 lines from the 127 line CwlFeedReader app from the previous article (plus a few lines of boilerplate in new files). It’s a relatively small change but it’s a topic with plenty of different opinions about the best approach so there’s a lot of discuss.

Let’s try to add tests to CwlFeedReader

Before we look in detail at what I mean by a “separated Services-layer”, I’d like to start by looking at the biggest capability this change will unlock: testing.

Let’s assume we want to do the bare minimum in testing. This generally means interface tests on the Model. By “interface”, I’m referring to the public functions of the Model (the module’s interface, not the user-interface). This type of test can detect major regressions (functionality that is accidentally broken when you add new features) and is a valuable addition to any app project due to its low time cost.

The interface to the Model looks like this:

public class Model: ObservableObject {
   @Published public private(set) var feed: Feed?
   @Published public var error: IdentifiableError?
   @Published public private(set) var isReadStatuses: [URL: Bool]
   
   public init()
   public func setIsRead(_ value: Bool, url: URL)
   public func reload()
}

To test this interface, we need tests that call each of:

init
setIsRead and
reload

that validate the behavior of these functions by reading the changes to feed, error and isReadStatuses.

I’ve written tests for all 3 functions in the CwlFeedReader repository but I want to focus on the test for the most important function in the program, reload. There’s a complication that reload is called from inside init so I’m going to simply construct Model() and – relying on the fact that reload delivers its results asychronously to the main thread – I will then examine the second value received via $feed and treat this as equivalent to the result of calling reload.

let feedFirstURL = URL(string: "https://www.cocoawithlove.com/blog/swiftui-natural-pattern.html")!
func testReload() {
   // Given a newly inited model and an expectation that stops on the second feed value
   let model = Model()
   let secondValue = expectation(description: "feed should emit 2 values.")
   let cancellable = model.$feed
      .dropFirst()
      .sink { _ in secondValue.fulfill() }
   
   // When the automatically invoked `reload()` completes
   wait(for: [secondValue], timeout: 30.0)
   cancellable.cancel()
   
   // Then the first feed URL should be the expected swiftui-natural-pattern.html
   XCTAssertEqual(model.feed?.items.map(\.url).first, feedFirstURL)
}

Everything looks good, right? I mean: there’s no bug in the code. Not exactly.

These tests are available from the part-four-broken-tests branch of the CwlFeedReader repository

The test fails.

Why? Because that feedFirstURL value was correct in late January when I wrote the test but it has already broken because the Cocoa with Love JSON feed has updated since then. We wanted this test to detect regression in the reload function but instead, we’ve merely detected that live-data has changed. This test is a waste of our time.

But the test isn’t the source of the problem, it is merely a symptom.

The true source of the problem is that it is not possible to isolate the code we’ve written from dependencies we use (the state of the network and data received from remote servers). If the upstream data changes, our tests fail. If the network is down, our tests fail. There are potentially worse problems that could occur if our tests overwhelm production servers or if our tests mistakenly change live data.

And even if live data isn’t a problem, our tests are much slower than they should be. The test relies on asynchronous I/O, causing the test to take between a few hundred milliseconds and a few seconds, instead of a couple microseconds. While this may seem like the least significant problem here, this adds up. Even small apps can have thousands of tests. Hundreds of milliseconds per test can become hours.

The conclusion here is straightforward: if you can’t isolate your application from the outside world, tests are practically useless. Even if you can endure unreliability, the best you can achieve are some basic app-server integration smoke tests. Any other kind of testing will be impossible.

The problem is broader than testing

It’s not just tests that are facing problems. We can’t do any useful work on the app if dependencies are unavailable. And dependencies are often, by their nature, beyond our control. If the server goes down, we’re blocked. If the server APIs are not finished, we’re blocked. Want to run a demo in a location without network access? You can’t.

Even the SwiftUI previews in CwlFeedReader construct the Model() and access the network for their content. Our SwiftUI previews can fail or misbehave when the network is unavailable. If we can’t usefully edit our views without working dependencies, then we’re in trouble.

Availability isn’t the only problem. Configuration of data is also a limitation. Want to debug a situation that requires specific data or user states? You’ll have to manually create those users and states each time.

These are the symptoms of an app that we can’t isolate from its dependencies but there’s another, more conceptual problem: we don’t even have a description of our app without its dependencies.

Yes, the user sees the Cocoa with Love JSON feed presented as a SwiftUI List and WKWebView but that’s not what’s in our Model-layer. What the user sees is a product of the data from connected dependencies flowing through the app.

If we remove all dependencies from consideration (including the View-layer), we’ve written a program that:

fetches a JSON list containing identifiers, including error handling on fetch
can re-fetch the JSON list when requested
fetches a dictionary of booleans, keyed by the same identifiers in the JSON list
can update and save the booleans for each identifier when requested

This could be the description of a to-do list app, an email client or a control app for a network-connected set of light-switches. The only difference is the dependencies we reference.

If we control how we reference our dependencies, we can develop, test and use our program with precision, be flexible between problem domains, and we can work without getting blocked.

Putting it in a diagram

Here’s a diagram of the CwlFeedReader app, showing the commonly identified Model-View-Controller components. Solid lines show references (use of concrete types or functions), dotted lines show data flow without reference. No solid arrow should ever point away from the Model – that would indicate a violation of Model isolation.

MVC representation of CwlFeedReader (solid lines are explicit references, dotted lines are decoupled interactions)

This diagram isn’t wrong but it shows only the front-end of the Model-layer. Here’s a more complete architectural diagram of the CwlFeedReader app including the back-end:

MVC+Services representation of CwlFeedReader (solid lines are explicit references, dotted lines are decoupled interactions)

Immediately, you should be able to see the problem: there’s a solid arrow pointing away from the Model. Our Model is not isolated because it directly references URLSession and UserDefaults – sources of side-effects that affect the app.

In the same way that we need to maintain separation between the Model and the Controller+View components at the front-end, we need to maintain separation between the Model and these side-effects at the back end or we compromise our ability to test, isolate and reason about our own application.

Some clarification around the word “Services”

There’s a few definitions of “services” around. The definition I’m using is:

Service: any type or function that provides side effects that can affect the testable behavior of the Model-layer

A side effect is a function (including methods and computed values) that might change its behavior despite being called with the same parameters. Typical examples are anything read from the network, disk, clock or operating system. In some cases, simply asynchronously returning results is side-effect (since it may change the ordering of results).

The difficulty with services is that they’re dependent on the state of the things (network, disk, other processes running on the system). For testing and development purposes, we want to keep all of this state constant so we can focus on whether our program has changed behavior.

Identification of services is only the first step. The second step is to move them into a Services-layer:

Services-layer: a collection of the app’s services and third-party dependencies, isolated so they are never directly referenced by the Model-layer, and replaceable at test or debug time with side-effect-free versions that offer robustly repeatable results.

The term “dependency injection” is commonly used to describe separation from dependencies. The term can accurately be applied to my approach but I tend to downplay this description due to its association with “dependency injection frameworks” (an approach that I avoid, as I’ll discuss later).

Notice that I’ve added “third-party dependencies”, along with “app’s services” in the Services-layer. The purpose of a Services-layer is that it lets the app swap components out at launch – good for removing services for testing, also good for removing third-party dependencies for updates, refactoring or replacements.

How can we decouple the Model from Services?

I want to separate the Model interface from the Services interface. Separating two interfaces from each other is a process usually called “decoupling”. Where do we draw a line for this separation?

Let’s consider the network-data request pipeline that involves URLSession in the CwlFeedReader app. The major features of the pipeline are:

the Cocoa with Love domain name
use of the URLSession type
use of the relative path for the feed.json file, parameters and JSON encoding/decoding to marshal parameters to URLSession

It’s possible to separate an app along any of these 3 lines. I consider only one of these choices “correct” but let’s look at the arguments used in favor of each.

1. Decouple from production server using different environments

It’s common to find apps that don’t change their code but change their data and re-point their app at a stub-server when testing or debugging.

For the CwlFeedReader app, you could imagine the Model taking an API base string in its init function (e.g. https://www.cocoawithlove.com) and at test time, passing a value like https://localhost:8080 as an alternate argument for this parameter. Assuming you’re running a webserver on port 8080 on the same machine, you could place a fixed version of the “feed.json” file at the same relative path as on the production server.

Pros

This approach lets you test every single line of code and, if retro-fitted to an existing codebase, requires the least effort.

Cons

This approach has many limitations:

Works for network dependencies but is harder to apply to other dependencies (like UserDefaults) so it isn’t really usable for general service isolation.
Even for network dependencies, it decouples network data but not network APIs. Our app can’t swap to a different network library or data source using this approach.
You need to start the stub server before testing, meaning that your tests don’t “just work” without extra setup.
Switching configurations on the server for testing requires side-channel configuration of the server.
Stub servers can be complex entities, often in another language, so they add additional learning overheads for Swift developers

2. Put a protocol around the smallest possible subset of URLSession

Another approach is to decouple the dependency in code but to keep this effort as simple as possible. In Swift, this means: create a protocol that describes our direct usage of each dependency.

We could define the following protocol:

public protocol NetworkService {
   func fetchData(with: URLRequest, handler: @escaping (Data?, URLResponse?, Error?) -> Void) -> AnyCancellable
}

and provide the following implementation to wrap our use of URLSession completely in a protocol.

extension URLSessionDataTask: Cancellable {}

extension URLSession: NetworkService {
   public func fetchData(with request: URLRequest, handler: @escaping (Data?, URLResponse?, Error?) -> Void) -> AnyCancellable {
      let task = dataTask(with: request, completionHandler: handler)
      task.resume()
      return AnyCancellable(task)
   }
}

If we only use URLSession through this protocol, then we become decoupled from URLSession as a dependency and source of side-effects.

Pros

Wrapping dependencies in protocols is relatively simple and the resulting code maintains the same basic structure as if it were using URLSession.

Cons

Doesn’t wrap URLRequest or handle other details. We still need to configure details like path and headers and handle work like JSON decoding so it’s more like we need to say “fetch a JSON list whose location is defined by this URLRequest” instead of the simple “fetch the feed”.

Marshalling parameters for network requests, filling in headers, selecting endpoints, decoding responses; this is all tedious work.

We could define the NetworkService to have an interface that matches what our Model needs.

public protocol NetworkService {
   func fetchFeed(handler: @escaping (Result<Feed, Error>) -> Void) -> AnyCancellable
}

This creates a much simpler interface – no URLRequest, no JSON decoding, just the simple transaction that the Model desires.

Pros

Matches our Model’s “fetch feed” intent and makes the service feel like a clean interface.

Cons

Adding different interfaces for each kind of request increases the service size – and remember, most services are implemented twice (once for the production services, once for the testing services) so this can be a significant additional burden.

Services themselves aren’t testable so putting more code into the service reduces potential test coverage. We’re putting Model-logic (correct headers for different endpoints, HTTP message encoding) in the untestable services.

Not reusable between different applications because it includes Model-specific logic.

Personal opinion

I think (2) is the best option: wrap dependencies with side-effects in a protocol that minimally wraps the features of the dependency that your app uses. You can change the interface slightly (as I changed dataTask to remove URLSesionDataTask from the interface) but such changes should be focussed on simplification without inclusion of any Model data or logic.

Using a stub server, as in option (1), just doesn’t solve enough problems and the problems it does solve aren’t solved cleanly. It can be good as a stop-gap if you have no other option and can serve other purposes (like cross-platform validation) but keeping it running on test machines is annoying and it will never deliver a clean solution across all dependencies.

At the other end, putting app-specific logic into a service (3) is a mistake. Model-logic should be tested but services aren’t testable (they’re supposed to a dependency, not your code). And the goal of (3) – to improve the abstraction of server communication – can be done by wrapping your services inside your Model-layer, translating from simplified model concepts (like “feed”) into expanded model details (like the URLRequest and the decoding of its result).

Using the Services-layer from the Model

Taking option (2) and wrapping our services as minimally as possible makes including it in existing code relatively painless. We can bundle all of the apps services together in a single struct:

public struct Services {
   let networkService: NetworkService
   let keyValueService: KeyValueService
}

With an instance of this struct available in the Model, we can replace the following use of URLSession:

task = URLSession.shared.dataTask(with: request) { data, response, error in /* ... */ }
task?.resume()

with

task = services.networkService.fetchData(with: request) { data, response, error in /* ... */ }

Replacing UserDefaults is similar:

UserDefaults.standard.set(try? JSONEncoder().encode(isReadStatuses), forKey: "isReadStatuses")

becomes:

services.keyValueService[key: "isReadStatuses", type: [URL: Bool].self] = isReadStatuses

It’s a drop-in replacement.

Constructing services

What I’ve ignored is exactly how and where the Services instance is constructed. The reason is that different developers choose different approaches.

Historically, dependency injection frameworks were used to satisfy this problem. Services in a class would be specially named, typed or attributed and at runtime, the dependency injection framework would intercept the construction of services and set them to appropriate values (fully constructed production services or specialized testing versions).

I don’t recommend dependency injection frameworks. The purpose of service isolation should be to prevent side-effects but using a runtime framework to manipulate the contents of your classes is a side-effect. It’s a conceptual conflict of interest and so completely unnecessary since manually managing services is so simple.

All we need to do configure the Model-layer with appropriate services is to pass them as a parameter at construction.

It’s weird when something so straightforward needs to be explained but I’ve seen developers go to extraordinary lengths to avoid passing a single parameter around. Here’s one approach commonly attempted to avoid passing services into the model – default constructed services:

public init(
   services: Services = Services(
      networkService: URLSession.shared,
      keyValueService: UserDefaults.standard
   )
)

At first, it seems highly practical because you don’t need to change how the Model class is constructed. The same Model() invocation will now construct the class with the production services and at test time, we can specify a different services argument for specialized testing services.

This approach works when Model is the only class in existence but as soon as you need other classes, it falls apart. It is not composable. If Model relies on class Submodel, then Model must construct Submodel with the same Services from Model, otherwise the two won’t agree. Letting Submodel default-construct its own Services is a potential source of bugs and should never occur. The only robust solution requires Services are always passed into the type from outside.

Here’s the construction of Model in the CwlFeedReaderApp:

@StateObject var model = Model(services: Services())

I would be possible to construct all the services inline but the list of services in an app tends to grow, and precisely configuring reusable services can get complex, so it’s a good idea to move this work into a dedicated init function for the construction of production services:

extension Services {
   public init() {
      self.init(networkService: URLSession.shared, keyValueService: UserDefaults.standard)
   }
}

Organize into modules to preserve separation

Now that we’ve added protocols, some implementations and some construction code, there’s a little organizing to consider to maintain the clean isolation we wanted.

Service protocols (NetworkService and KeyValueService) and the Services struct which holds them should go into the “Model” module (they are the Model-layer defining its own interface).

Service implementations (extension URLSession: NetworkService and extension UserDefaults: KeyValueService) must remain separated from the Model-layer. They can go into a new module named “ServiceImplementations”. This new module should be imported into the CwlFeedReaderApp (since it constructs the Services for the Model at startup) but shouldn’t be imported anywhere else.

A final diagram

The complete MVC+Services version of the app is available from the part-four branch of the CwlFeedReader repository

The result is that Model-layer only references service protocols, never service implementations. This means the Model-layer no longer has any solid references to any other layer:

MVC with separated Services-layer

The Controller’s role in pulling everything together is apparent – it has a solid line to every other layer. Fortunately, despite the many arrows, the Controller’s workload is minimal – the connection to the Services-layer is just a single function.

The line from Services to the Model has gone from dotted to solid, indicating that Services now concretely references the Model-layer (to access the service protocol definitions). Eventually, moving these service protocols into a Definitions module (to avoid Services becoming coupled with Model details) might be helpful but we’ve added enough modules for the moment.

The effect on code was minor, particularly if you consider only the impact on existing code: we’ve changed just 9 lines of the 127 line program.

There are 46 new lines in new files (two new protocols and their implementations, the Services struct and its constructor) but exactly how to count these is debatable. The protocols and their implementations are reusable between apps. Like the WebView and IdentifiableError – that I ignore when counting lines of code – this new code could be considered external to the app. Additionally, service implementations grow only occasionally; we could increase the remaining program by an order of magnitude without needing additional service implementation code.

Replacing the Services-layer at testing time

Now the Model-layer is cleanly separated from the Services-layer but we haven’t used it for any change in behavior. For this, we need test-friendly implementations of each service and an easy way to construct these test services, instead of the production services.

Here’s an implementation of NetworkService that pulls its data from a file resource instead of the network:

class MockNetworkService: NetworkService {
   func fetchData(with request: URLRequest, handler: @escaping (Data?, URLResponse?, Error?) -> Void) -> AnyCancellable {
      guard let method = request.httpMethod, let url = request.url else {
         handler(nil, nil, URLError(.badURL))
         return AnyCancellable {}
      }
      
      switch "\(method) \(url.absoluteString)" {
      case "GET https://www.cocoawithlove.com/feed.json": handler(mockFixture(name: "feed.json"), .successResponse(url), nil)
      default: handler(nil, .notFoundResponse(url), URLError(.fileDoesNotExist))
      }
      
      return AnyCancellable {}
   }
}

Stubs and mocks: I’ve referred to “stub servers” and now “mock services”. These names are conventions from projects that I’ve worked on. The terms “mocks” and “stubs” have specific definitions in testing (“stubs” record data and provide output data, whereas “mocks” record the order in which functions are invoked). Just to be confusing, both “stub servers” and “mock services” generally break this terminology because they don’t record and would more correctly be termed “fakes” (partially working, isolated implementations).

As with running the app against the production services, we can construct Services for testing in a simplified manner:

public extension Services {
   static var mock: Services {
      return Services(networkService: MockNetworkService(), keyValueService: MockKeyValueService())
   }
}

Now that we have this Services.mock implementation, all we need to fix the failing testReload() from the start of the article is to replace the let model = Model() with let model = Model(services: Services.mock) and ensure we’re testing the result expected from our “feed.json” file.

Finally, we have reliable, fast tests that won’t break over time (unless we break our code – which is the breakage we want to detect).

We can also run our SwiftUI previews without relying on the network by replacing the old preview code:

#if DEBUG
struct ListView_Previews: PreviewProvider {
   static var previews: some View {
      let model = Model()
      ListView(model: model)
   }
}
#endif

with the new Services.mock:

#if DEBUG
import MockServiceImplementations
struct ListView_Previews: PreviewProvider {
   static var previews: some View {
      let model = Model(services: Services.mock)
      ListView(model: model)
   }
}
#endif

This will let us pre-populate our SwiftUI previews however we desire, without needing the network to be available.

These tests and previews are available from the part-four branch of the CwlFeedReader repository

Some ugliness due to missing SE-0273 functionality

As with “ServiceImplementations”, the “MockServiceImplementations” should also be its own module (by now, you should be able to see why moving to a module-based build approach was so necessary in the previous article).

At a minimum, the tests will need to import “MockServiceImplementations” but ideally, the app should be able to import it too, for use in SwiftUI previews. We don’t really want to include the mock services module in release builds (since mock fixtures take up a lot of space and we’d rather not include our internal testing details in the released product) so we need to pass condition: .when(configuration: .debug) to the Swift Package Manger for the “MockServiceImplementations” library.

Unfortunately, the .when(configuration:) condition I just mentioned is still waiting for the Swift Package Manager developers to finish SE-0273.

Ahem.

Until then, we need some ugly workarounds to make “MockServiceImplementations” a debug-only dependency.

First, the “MockServiceImplementations” need to be built into a separate library. The Swift PackageDescription begins:

let package = Package(
   name: "CwlFeedReaderLib",
   platforms: [.iOS(.v14), .macOS(.v11)],
   products: [
      .library(
         name: "CwlFeedReaderLib",
         targets: ["Model", "ServiceImplementations", "Toolbox", "ViewToolbox"]
      ),
      .library(
         name: "MockServiceImplementations",
         targets: ["MockServiceImplementations"]
      )

Then in the “Build Phases” for the app target, we need to add “MockServiceImplementations” to the “Dependencies” but DO NOT add it to the list of libraries or linked files. Instead, find the “Other Linker Flags” setting in the “Build Settings” and expand it to reveal “Debug”/“Release” and under “Debug” add ${BUILT_PRODUCTS_DIR}/MockServiceImplementations.o.

That’s not too bad but our MockServiceImplementations module contains “fixtures” (fixed API responses in the form of JSON files) and we need to copy these into the app bundle for debug builds so we need a “Run script” build phase:

if [ "${CONFIGURATION}" = "Debug" ]; then
  echo "Copying ${SCRIPT_INPUT_FILE_0}"
  cp -Rf "${SCRIPT_INPUT_FILE_0}" "${SCRIPT_OUTPUT_FILE_0}"
fi

with input file:

$(BUILT_PRODUCTS_DIR)/CwlFeedReaderLib_MockServiceImplementations.bundle

and output file

$(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/CwlFeedReaderLib_MockServiceImplementations.bundle

Yuck.

Oh and it’s not really possible to establish a dependency on the tree of contents inside a folder so if you change the contents of a fixture without changing something that alters the date on the folder itself, you may need to uncheck the “Based on dependency analysis” checkbox on the build script, briefly, and build again to pick up the changes.

Double yuck.

Hopefully, a complete SE-0273 implementation is on its way and all of this agony goes away. Until then, if anyone knows a better dependency-observing way to copy Debug-only resources please let me know. Dependency analysis omissions don’t cause problems very often but when they do, it’s when you’re debugging a test failure and you swear you’ve fixed the problem but the test is still failing and… dammit I fixed the problem 20 minutes ago but it just wasn’t getting picked up by the build system.

Conclusion

App architecture is primarily about establishing roles throughout an app. By structuring our code according to roles, we aim to make code easier to write, easier to read and easier to manage. But these roles pertain only to the expression of logic and do not usually affect the output of that logic – so app architecture rarely affects the ultimate behavior of an app.

Switching to a separated Services-layer is unusual as an architectural change because, while the app’s behavior is unchanged in production, the app can also run in a second mode where the behavior is quite different – controlled and testing-friendly. A Services-layer unlocks real changes, even if these changes are limited to debugging, testing and development on non-production builds of an app.

Despite the benefits, service separation is far from widespread in the iOS app developer community. I’ve joined multiple projects where a couple tests exist in code repositories but due to lack of service separation the tests are necessarily limited and largely useless for detecting regressions. I’ve also worked on codebases where network services were separated but tests still broke each month as they relied on the system clock to select “this month’s data”. Separating the Model from services – including more services than just the network service – is a skill I hope more developers learn.

Even though I’m strongly advocating for a separate Services-layer, total isolation of all side effects is not necessarily a goal. I identified DispatchQueue.main.async as a “service” in CwlFeedReader but I chose not to separate it since it wouldn’t affect any of the tests I had written (my tests were already waiting for asychronous expectations). Service abstractions can be simple but they’re never free. I’d like to think that if a test broke due to asychronous behavior, I would take the effort to create a separate SchedulingService (see my previous Testing actions over time for possible approaches). Or would I try to avoid the problem another way? There isn’t a wrong answer, only a judgement call about what is right for your project.

App architecture basics in SwiftUI Part 3: Module-separated layers

Fri, 12 Feb 2021 08:37:06 +1000

In the previous article, I looked at how SwiftUI’s data-driven changes force a basic separation between Model and View. The separation is limited in scope, requiring only that there exist a state value or observable object that drives view updates.

If a cleaner separation between Model and View is desired, then slicing an app into modules (Swift’s name for discrete libraries) is the best technical step you can make. Separating architectural layers (e.g. Model, View, and optionally others) into their own modules lets you establish rules about how to connect your layers, which types and properties should be accessible and keeps the overhead low on adding new layers.

If you’ve ever wanted to improve your app’s architecture, simply moving your Model into a separate module is a step you should take before choosing to make any other architectural change. It can reveal problems you never realized you had and prevent future problems.

The problem

When I wrote the CwlFeedReader app, in the first article in this series, the Xcode project navigator looked like this:

Starting state of the CwlFeedReader app

The app is really just 5 files in a single folder. I’ve placed three “Utilities” into a separate folder but the primary reason for this is that these are components I didn’t really discuss during the article - they are dependencies and I don’t consider them part of the app.

Is there really any problem that we need to solve, here? The app is very small and simple; we don’t need to break it up.

The reasons I want to break up this project fall into the following three categories.

1. Interface design

Everything internal on Model is accessible by the View-layer types. The View could do ill-advised things like start its own downloads and store them directly on the URLSessionDataTask or update the feed following user changes and store it back in the same location – potentially conflicting with Model-driven updates.

These are the sorts of obviously-bad short-cuts which get written when developers are rushed or aren’t thinking clearly about encapsulation. If problems like this aren’t cleaned up before committing code, then suddenly the app is full of surprising bugs. Yes, we can prevent this in a simple way by marking these properties as private but then we remove the ability to break the Model class across multiple files (because everything that needs to access private must stay in the same file).

We either have a gigantic Model file with everything marked private or a leaky interface requiring constant vigilence.

Better to have Model live in a separate module. If something is View-safe, we mark it public. If something requires strong control, we can use private but internal access becomes truly useful – especially since internal is the default.

2. Connection rules

The Model-layer should never reference any types from the View-layer; the connection arrow must point from View to Model. In a single module, we can’t prevent the Model from accessing View types. Once we move the Model to a separate module, we can let the build system enforce that for us.

3. Unit testing

This is a technical consideration due to how Xcode projects work but everything about adding testing bundles to Xcode projects is higher friction than adding a testing target via the Swift Package Manager.

For example, if I were to add a unit testing bundle to this project it would add 130 lines to the pbxproj file and Info.plist. That addition is nearly as big as the Swift code-size of the app. Even though most of those lines are autogenerated, Xcode expects us to maintain all of these settings. The appearance alone of that much boilerplate in a git merge request is mind numbing.

Further, if we wanted unit tests for both macOS and iOS (remember, this is a multiplatform project) we would need to add two unit testing bundles. That’s 260 lines of Xcode project configuration.

The final insult is that trying run unit tests attached directly to the app is practically useless because the entire app will run whenever the testing bundle is loaded. Having an entire app running in the background is likely to interfere with tests and even if it doesn’t it will certainly slow down the tests.

Creating an inline Swift Package

Historically, I would solve some of the above-mentioned problems by creating child frameworks. You would go to the “File → New → Target” menu and create a new iOS Framework. If, for some reason, your project can’t use the Swift Package Manager then this remains the best approach.

However, separate frameworks have many of the problems listed under “Unit Testing”, above: there’s xcodeproj bloat and you need a separate framework per platform.

Fortunately, we have the Swift Package Manager and it offers a much better experience.

Documentation on the Swift Package Manager in Xcode is almost entirely focussed on adding dependencies from outside your project or creating libraries to be shared outside your project. Neither of these are features that interest us, here.

You don’t need to use the dependency management features of Swift Package Manager for it to be useful.

For the CwlFeedReader app, I selected “File → New → Swift Package…” from the menubar. When the “Save As:” dialog appears, I went to the same folder that contains the CwlFeedReader.xcodeproj file for the project, typed “CwlFeedReaderLib” in the “Save As:” name field and selected the “CwlFeedReader” project in the “Add to:” and “Group:” popup menus.

Creating an inline Swift Package

After the package was created, I went to the CwlFeedReader app’s Target and added CwlFeedReaderLib under the list of Frameworks, Libraries and Embedded Content.

Establishing the desired structure

Now, I can reorganize files in the project browser to place “Model.swift” under “CwlFeedReaderLib/Sources/Model”, the “IdentifiableError.swift” under “CwlFeedReaderLib/Sources/Toolbox” and “View+PlatformCompatibility.swift” and “WebView.swift” under “CwlFeedReaderLib/Sources/ViewToolbox”.

Desired state of the CwlFeedReader app

Updating the Package.swift file to include these locations gives the following:

// swift-tools-version:5.3

import PackageDescription

let package = Package(
   name: "CwlFeedReaderLib",
   platforms: [.iOS(.v14), .macOS(.v11)],
   products: [
      .library(
         name: "CwlFeedReaderLib",
         targets: ["Model", "Toolbox", "ViewToolbox"]
      ),
   ],
   targets: [
      .target(
         name: "Model",
         dependencies: ["Toolbox"]
      ),
      .target(
         name: "Toolbox",
         dependencies: []
      ),
      .target(
         name: "ViewToolbox",
         dependencies: ["Toolbox"]
      )
   ]
)

Notice that I’m already using the Swift Package Manager to create a few addditional modules with “Toolbox” and “ViewToolbox” keeping reusable dependencies outside the “Model” and “View” components.

The reason for this type of separation is to identify files that should contain no app-specific logic – it’s telling any reader of the code what to expect and promoting code re-use. Neither of these points is essential but since the effort is low, they are both good to promote.

Imports and access modifiers

Once we’ve actually separated our Model and Toolbox dependencies, everything will break.

The “Model.swift” file will need to import Toolbox. All four files remaining in the App folder will need to import Model and “DetailView.swift” will need to import ViewToolbox.

Once that’s done, everything the View needs to access in the Model module will need to be marked public.

I won’t list everything here but you can examine the diffs in the final commit on the “Part 3” branch of the CwlFeedReader code repository.

Submodules?

I’ve taken an Xcode project in a single repository and broken it into multiple internal modules.

Submodules is a proposed language feature that would be able to achieve a similar effect without the Swift Package Manager. All the code would reside in a single Swift module but you would be able to “namespace” some sections as residing in a separate submodule. Draft proposals exist to add them to the language. However, submodules has never moved past the draft proposal stage and it’s not clearly going anywhere.

It’s possible submodules will never be implemented but that doesn’t worry me. I usually dislike touching build-systems but I think this is one problem that might be more cleanly solved at the build-system level than the language level. Build-system enforced isolation makes accidental violations of encapsulation harder and therefore separation is cleaner.

However, potential changes to either Swift or Xcode do make me wonder what the lifetime of this article will be. The advice to “isolate your layers” will never be wrong but the implementation could be superceded.

Submodules could be implemented in Swift and introduce confusion about whether they’re better or worse for the job.

The xcodeproj format in Xcode could be replaced by Swift Packages with apps created as a single Swift Package with the basic “Model” and “View” modules immediately created by the “New Project” app template. Of course, I’ve been hoping for xcodeproj deprecation since 2015; I have no reason to believe it will change in the next couple years.

Conclusion

The full code for this article is available from the part-three branch of the CwlFeedReader repository.

As with most of this “App architecture basics in SwiftUI” series, I’m not doing anything revolutionary, here. I’ve spent about half this article giving a tutorial on how to add a Swift Package to an Xcode project.

The bigger message that I want to convey is that layer-isolation requires a tiny amount of up-front work but it yields clear benefits. When applying this type of separation to established projects, it’s common to discover large numbers of bugs and undesired behavior due to Model and View accessing each others internal details. It’s a change that informs us about our own laziness.

It’s also a change that has productivity benefits moving forward. New modules are now trivial to add. Remember the 130 lines times 2 platforms increase when adding a testing target? Now it’s 4 lines, total, without the possibility of the app running and interfering in the background.

Looking forward…

While I mentioned “tests” in this article, I never wrote any. That will change in the next article as I highlight the most important architectural inclusion that this app is still missing.

App architecture basics in SwiftUI, Part 2: SwiftUI's natural pattern

Tue, 19 Jan 2021 10:32:11 +1100

In the previous article, I wrote a simple SwiftUI app. During the writing, I deliberately kept the code simple – writing code only when needed to satisfy user-facing goals. I want to take a closer look at the application architecture that naturally emerges in SwiftUI when following this kind of functionally minimalist approach.

Perform a web search for “SwiftUI pattern” and you’ll find numerous discussions of SwiftUI that wonder if its use of model-bindings make it a form of Model-View-ViewModel (MVVM) or if its use of immutable views and view-state make it redux or Elm-like. While SwiftUI does include these components, the reality is much simpler: SwiftUI’s natural pattern is a form of Model-View-Controller (MVC), although very different from UIKit MVC.

In any case, the precise naming is less important than the components that work together to form the architecture. In this article, I’ll identify the different application architectural roles fulfilled by components of SwiftUI and talk about how they work together to form the overall pattern.

Changes triggered by model data

SwiftUI introduces many differences compared to macOS AppKit or iOS UIKit but a single difference has the biggest effect on application architecture: how changes are triggered.

Let’s start by looking at how UIKit triggers changes. In UIKit, you construct a tree of view-objects. These objects are reference types and you can hold onto those references to trigger a change.

let window = UIWindow()
window.makeKeyAndVisible()

DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(1)) {
   let label = UILabel(frame: window.frame)
   label.text = "Boo!"
   window.addSubview(label)
}

Here, I’ve created a view (window) and I’ve changed its content after 1 second by holding onto the window reference and adding a new subview which triggers the update.

Here’s how it might look in SwiftUI:

struct ContentView: View {
   @State var showSubview: Bool
   var body: some View {
      ZStack {
         Color.white
            .onAppear {
               DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(1)) {
                  self.showSubview = true
               }
            }
         if showSubview {
            Text("Boo!")
         }
      }
   }
}

Oh look, I’ve managed to find one of the few scenarios where UIKit is more syntactically efficient than SwiftUI.

Let’s ignore that because there’s a more important difference.

In UIKit, I changed the subviews of the window – a UIKit property – and that triggered the view update.
In SwiftUI, I changed showSubview – my own property – and that triggered the view update.

What difference does that make?

It means my own values are the source of truth for the View, not the state of a view-tree. I must create data which represents the current view-state. This is a Model (or a Model-interface*) and it is mandatory in SwiftUI whereas in UIKit is was possible to create an app without one.

* A Model is a repository of domain logic, not data. Data and definitions exist in the Model only to communicate (interface) with other layers. Please don’t look at this @State var showSubview: Bool and think that’s all a Model should do. Ideally, the timing details and the assignment would be expressed inside the Model but I’m trying to keep things simple.

Construction role

In UIKit, lots of components can, and do, fulfill parts of the view-construction role. Some of them are scattered across storyboards, UIViewController lifecycle methods, methods in UITableViewDelegate (among others) and UIViews themselves. Nominally, construction is a UIViewController responsibility but implementation-wise, it’s a bit of a mess.

In SwiftUI, it should be obvious that Views construct themselves however, it’s not as simple as that. While SwiftUI doesn’t have a direct counterpart to UIViewController, there are some Views that focus on construction and some that focus on layout and drawing.

To explain how this works, I want to look a little closer at the two different kinds of View:

built-in views return Never from their body function
compositional views return another View from their body function because they really just serve to configure and aggregate underlying views and may hold observable state

You could break each of these into sub categories but this is enough for the purposes of this article.

We can’t write the first kind of View ourselves because they are effectively the rendering primitives in SwiftUI (like CoreGraphics functions in UIKit). They draw the text, fill and stroke the beziers and position elements.

By contrast, all of the views we actually write in SwiftUI primarily serve to group, layout, bind to data and construct these built-in views.

Let’s look at the default Xcode template for the ContentView, used as the placeholder View in the code for the previous article:

struct ContentView: View {
   var body: some View {
      Text("Hello, world!")
         .padding()
   }
}

In this example, ContentView is a compositional view but Text and the ModifiedLayout produced by the .padding() call are built-in views and are specially handled by the SwiftUI system.

@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
extension Text : View {
    public typealias Body = Never
}

It’s not possible to have a Body = Never for our own views. It is feature of built-in views, only.

It should be clear that compositional views (particularly the higher level ones) are the scene constructors in SwiftUI and the built-in views fulfilling the rendering role.

Event handling role

For view interaction to work, there must be code that receives “events” and can trigger code in other parts of the system.

In SwiftUI this is handled by action closures, sometimes as part of a visible View (like a Button) and sometimes as a standalone on event-handler.

The .onAppear transformation appends an event-handling view – another SwiftUI built-in view – which calls a closure that captures our view and can access its @State variable.

struct ContentView: View {
   @State var showSubview: Bool
   var body: some View {
      ZStack {
         Color.white
            .onAppear {
               DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(1)) {
                  self.showSubview = true
               }
            }

         /* ... other code omitted ... */
      }
   }
}

In some respects, this is similar to the Target-Action pattern in UIKit. However, the immutable nature of SwiftUI views encourages the notion that destination of an event should be one of the mutable SwiftUI model properties, like the @State in this example.

This enforces the notion that events come from view-hierarchy elements and the interaction is sent directly to the Model – an improvement compared to Target-Action in UIKit which typically sent interactions via the Controller-layer.

I’m making the claim that all @State properties in SwiftUI (like the showSubview property) are Model-layer entities since they are decoupled, observable and directly drive View-updates. SwiftUI’s View-state is similar to the Elm architecture where View-state is just a kind of Model-state, compared to UIKit where View-state was an unobserved side-effect.

Data binding role

Where the event-handling role is concerned with incoming changes triggered by the View-layer, data-binding is concerned with outgoing changes from the Model-layer.

UIKit traditionally (prior to Combine) had no data-binding beyond key-value observing and NotificationCenter. Cocoa on macOS had Cocoa Bindings, which could be powerful but were difficult to extend, opaque to the reader and have been effectively deprecated for a decade.

SwiftUI, on the other hand, is built around data-bindings – tracking which Views are dependent on which DynamicProperty (@State, @ObservedObject, et al) state properties and making sure views are re-generated when the state changes. While the exact machinery inside these property wrapper attributes is opaque to us, we don’t typically need to worry – just use the state and the binding is established automatically.

Once again, this is a role assigned to our compositional views, since they are the ones which host Model properties like @ObservedObject and @State properties.

In the showSubview example, above, the ContentView is responsible for establishing a connection between the showSubview View-state and the appearance of the Text.

struct ContentView: View {
   @State var showSubview: Bool
   var body: some View {
      ZStack {
         /* ... other code omitted ... */

         if showSubview {
            Text("Boo!")
         }
      }
   }
}

Taken together, what does all this mean?

We have:

A Model, enforced by SwiftUI’s approach to change management
Built-in views handle all the drawing
Composite views handle construction
Composite views establish Model-to-View bindings
Event views route events using Model references provided by composite views

With separate Model and View roles, plus an amalgam of Construction, Event and Binding roles around our composite views, SwiftUI is really just Model-View-Controller, with the composite views acting as the Controller.

If you pay attention only to the names State and View, you could be forgiven for thinking that SwiftUI’s natural pattern is Model-View but the roles performed by composite views clearly cover the responsibilities of the Controller in MVC, even if SwiftUI makes the syntactic overhead so low that you could overlook it.

The boundary that I’ve drawn between a composite and built-in view is blurred (many built-in views may be internally composite and many of our own views might be static and behavior-less). However, this blurry boundary is not a new complication in an MVC pattern. The UIKit UIViewController could perform view styling and didn’t need to have data or behaviors; and container UIViews would often function as controllers, applying data connections and establishing links between events and the model.

Why is the pattern not MVVM?

I want to address MVVM for two reasons:

I’ve seen commenters make the mistake of claiming that SwiftUI is, or uses, MVVM.
I will talk about ViewModels in a later article of this series and I want the distinction to be clear.

In general MVVM programs should aim to follow these two principles:

every data-driven property in the View should be driven by a unique Model property;
presentation-logic (like sorting or string formatting) should be applied in the Model before the property is exposed to the View.

Lets focus on two lines from detailView in the code for the CwlFeedReader app in the previous article:

let isRead = model.isReadStatuses[article.url] ?? false

and

Text(isRead ? "Mark as unread" : "Mark as read")

These lines clearly show:

the detailView reading model.isReadStatuses (a property used in multiple parts of the program and definitely not unique to this button label in the detailView)
the code performs two transformations on the value: x ?? false to give a default value when nil and then isRead ? a : b to transform the Bool into a display String.

Each of these are violations of the principles that an MVVM program should aim to follow.

You might point out – particularly with the second point – that this is some very minor presentation-logic. And its true that most implementations of MVVM permit some transformations in the View – often including this type of boolean logic. But I’m using this example to highlight in a simple way that SwiftUI allows for an unbounded amount of logic in the View and ultimately this is contrary to MVVM which tries to put all presentation logic in the ViewModel.

If SwiftUI wanted to force an MVVM pattern, it could have made @Published properties a single-use, one-to-one binding, to address the first requirement. Upcoming Swift “Ownership” features like consumable and move-only types would make this possible. They were not used.

Similarly, SwiftUI could have taken steps to prevent or limit arbitrary logic in the body of View. In .NET, the domain-specific language XAML is used to achieve this goal. SwiftUI could have introduced a subset of Swift that permitted only combining operators. SwiftUI did introduce a domain-specific language with @ViewBuilder but it is focussed on simplifying composition, not limiting logic.

SwiftUI didn’t take any of these steps so it’s clear that SwiftUI is not MVVM.

Why do people claim SwiftUI is MVVM?

In researching this article, I found multiple articles and forum responses claiming that SwiftUI is or uses MVVM. Why would people jump to this conclusion?

Is it the Model-data bindings?

The @Published and @ObservedObject attributes used in SwiftUI do make observing data changes much easier – especially since some form of data observing is required to perform view updates. Good data observing can significantly improve MVVM where you might have dozens of bindings between each view-model and view.

But the reality is that good MVC apps also use data observing – it is not unique to MVVM. UIKit offered some out-of-the-box tools and most developers supplemented this with their own additions.

The @Published attributes make no effort to limit observing to one-to-one scenarios so really, this isn’t a boost to MVVM as much as it is a rejection of programming without data observing.

Is it Combine?

Apple introduced the Combine framework alongside SwiftUI. Combine is a reactive programming framework and reactive programming frameworks have been commonly used on iOS/macOS to implement bindings as part of an MVVM pattern.

The incorrect implication here, is that SwiftUI implies Combine implies MVVM.

I stated above that Model-data bindings (even reactive programming bindings) don’t imply MVVM but the other implication is also incorrect: just because you’re using SwiftUI doesn’t mean you have to use Combine. SwiftUI offers good interoperability with Combine but any reactive programming when using SwiftUI is a totally optional addition.

Yes, there are some parts of the SwiftUI data flow that internally use Combine (most notably @Published and ObservableObject) but these are internal implementation details. My CwlFeedReader in the previous article did not import Combine or use reactive programming.

Is it just because UIViewController is gone?

The original Smalltalk definition of MVC had the Controller filling a role closer to “event handling role” than anything else in this article. As I discussed in Looking at Model-View-Controller in Cocoa the precise definition of MVC is platform specific, making a precise declaration of whether or not something is MVC a little difficult.

To be honest, I think this might be close to reality.

When MVC in UIKit was discussed, people were not discussing MVC in general. MVC on UIKit meant UIViewController and the way it dominated iOS development. UIViewController was the screens, the storyboards, the delegate and 80% of the rest.

To many UIKit developers, UIViewController defined the Controller in Model-View-Controller. Without it, what do we have?

Conclusion

I think SwiftUI’s pattern is best described as Model-View-Controller. The Controller role is downplayed and mixed with the View, but that’s common in MVC+Bindings approaches like SwiftUI. However, top-level “composite” views retain the contruction, binding and event routing roles that the Controller in UIKit fulfilled.

Even if we call SwiftUI’s pattern “The SwiftUI pattern” to distinguish from UIKit’s MVC, I think the more important point is to understand that SwiftUI includes:

Models and view-state
Render-primitive-like built-in views
Construction
Event handling and model-interactions
Data observing and binding

and even though all of these can appear in a 10 line SwiftUI View, they are distinct roles and you should be able to identify them separately.

As a developer who has focussed heavily on application architecture, I’m struck by how straightforward the architecture around the View is in SwiftUI. In AppKit/UIKit, there was a continuous question around how to set up observing, where to perform View construction and configuration and whether to bother with the overhead of bindings and event handling. SwiftUI doesn’t eliminate bad architecture but in my experience so far, a good architecture feels much more natural than it ever did in UIKit.

Looking forward…

In SwiftUI there are fewer application architecture problems to solve around the View-layer and View-bindings but there are still plenty of places for improvement. In the next couple articles, I’m going to look at some architectural patterns to improve the Model-layer.

App architecture basics in SwiftUI, Part 1: Coding through iteration and integration

Thu, 31 Dec 2020 22:29:53 +1100

In this series of articles, I’ll look at fundamental app architectural concepts and how they apply to an app written in SwiftUI.

To begin the series, I want to start with something small: a JSON feed reader app in SwiftUI. I want to focus on the order of the steps, not the code itself and answer a common question: which should you write first, View-code or Model-code?

The short answer is “both” (or “neither”) but properly answering the question offers a segue into a more important question: how can I make reliable progress as a programmer when I’m uncertain about what I’m doing or the blocks of work seem too big to manage?

Where to start?

The app I want to write is a JSON feed reader for the Cocoa with Love JSON feed. The app will be a macOS/iOS SwiftUI app that looks like this:

End goal for the CwlFeedReader app

You have to start somewhere. Where should you begin? Model? View?

Apps are made of multiple components (data, models, views) and these components all depend on each other, leading to a chicken-and-egg problem of which component should be written first.

Where you start doesn’t matter. What matters is that you work in small steps (iterate) and ensure that changes are immediately extended out into every major component in the app (integrate). Between iteration and integration, the most important is integration – that’s how you find problems and ensure you’re progressing in the right direction. Iteration is simply writing small blocks of code so you can get back to integration, again.

I’m going to follow this approach with some fairly concrete steps:

placeholders
stubs
implementation
iteration

Placeholders

If we want early integration, then we need something to act as both Model and the View as early as possible. It shouldn’t be the real Model or the real View or have any substantial property of the real layers. It will merely be a name.

This is the concept of a placeholder.

View placeholder

Create an application from Xcode’s SwiftUI project templates and you’ll get a ContentView that looks like this:

struct ContentView: View {
   var body: some View {
      Text("Hello, world!")
         .padding()
   }
}

That’s our placeholder View. It has no behavior and it has the wrong structure but it has a name and that’s all we need.

Answering the question “which should you write first, View-code or Model-code”: the View appeared first but I didn’t write it. Not the most helpful answer.

Model placeholder

Let’s create a placeholder for the Model. The Model for a JSON feed app might initially be just the JSON feed itself.

let articles = ""

This alone would work as a Model placeholder – it has a name.

I think I can take an extra half-step to give it array arrity here because the important part about JSON feed is that it contains an array of articles.

let articles = ["one", "two", "three"]

This array of articles is not a representation of a JSON feed but it will work as a placeholder. I have ensured that it has equivalent “cardinality” (it’s an array, not a single object) which will help me segue into the next iteration.

Answering the question “which should you write first, View-code or Model-code”: the first line of code that I wrote was the Model placeholder but it’s not going to survive through the next iteration. Maybe it’s not the most useful question.

Placeholder integration

Before we iterate further, we need to integrate – which is nothing more than putting the model inside the view.

struct ContentView: View {
   let articles = ["one", "two", "three"]
   var body: some View {
      Text("Hello, world!").padding()
   }
}

This integration was straightforward. We’ll see a more substantial integration in the next section before choosing to change the order and make Model changes before View changes.

Stubs

Stub views

This is the start of the second iteration and that means throwing away code from an old iteration. In this case, we throw away the entire contents of the ContentView.body property.

In its places, we can stub out a List using the array of articles.

struct ContentView: View {
   let articles = ["one", "two", "three"]
   var body: some View {
      NavigationView {
         List(articles, id: \.self) { article in
            NavigationLink(destination: Text(article)) {
               Text(article)
            }
         }
         Color.clear
      }
      .navigationViewStyle(DoubleColumnNavigationViewStyle())
   }
}

Our stub view has the basic components: a DoubleColumnNavigationViewStyle with List and a NavigationLink but the views have no real content and do nothing.

Stubbing out views is probably the best aspect of SwiftUI. In 14 lines of code (5 of which are largely empty) you can see the entire program.

This code runs and give the following app:

As we add refinements and features in SwiftUI, the details can dwarf the basic structure. Hiding details, without hiding structure, should be the goal of any good SwiftUI developer. It’s important to remember what your view looks like at the stub stage and continually refactor to resurface this underlying structure.

Stub model

As we did when we started the stub view, we’re throwing away the entire stub model. It was just a name and there’s nothing to carry forward (we’re not even going to keep the name).

What do we want instead? The primary requirement of a stub Model it that it needs to adopt the expected structure of the data, so we’re going to add a much larger block of code here.

The Feed and Article types are dictated by the format of the JSONFeed standard, so it’s not difficult to write.

struct Feed: Codable {
   let items: [Article]
}

struct Article: Codable {
   let url: URL
   let title: String
   let content: String

   enum CodingKeys: String, CodingKey {
      case url, title, content = "content_html"
   }
}

class Model: ObservableObject {
   @Published var feed: Feed? = Feed(
      items: [
         Article(url: URL(string: "mock://x/a1.html")!, title: "Article1", content: "One"),
         Article(url: URL(string: "mock://x/a2.html")!, title: "Article2", content: "Two"),
         Article(url: URL(string: "mock://x/a3.html")!, title: "Article3", content: "Three")
      ]
   )
}

Stub integration

In the above code, I made Model conform to ObservableObject and offered feed as a @Published property. This is the technical requirement to connect this version of the Model with the View.

On the other end of the connection, we must make the ContentView reference this new Model. We remove the articles stub and instead include our new model.

struct ContentView: View {
   @ObservedObject var model: Model
   
   // ...
}

All ContentView construction will now need to pass a Model and the List needs to be updated to follow the new structure of the data.

List(model.feed?.items ?? [], id: \.url) { row in
   NavigationLink(destination: Text(row.content)) {
      Text(row.title)
   }
}

Running the app now show that our stub model is visible in the view:

Functional implementations

Model functional implementation

We’re now at the point where it’s time for the Model to load the actual feed. Since this implementation has no effect on the Model’s interface, it doesn’t matter whether this step occurs before or after similar changes in the View.

The placeholder construction of the feed is thrown away. Instead, we’re going to get real data using URLRequest:

var task: URLSessionDataTask?
init() {
   let request = URLRequest(url: URL(string: "https://www.cocoawithlove.com/feed.json")!)
   task = URLSession.shared.dataTask(with: request) { data, response, error in
      do {
         if let error = error { throw error }
         let feed = try JSONDecoder().decode(Feed.self, from: data ?? Data())
         DispatchQueue.main.async { self.feed = feed }
      } catch {}
   }
   task?.resume()
}

View functional implementation

The View-equivalent of functional implementation in the Model are display changes unrelated to model data. Again, as with the Model functional implementation, this could happen before or after the Model changes.

There’s less throwing away code in this implementation, it’s more a progressive refactoring pass. I’ve added nav bar titles, nav bar styling, and a UIViewRepresentable-wrapped WKWebView for feed content instead of a simple Text view). The ContentView body function is updated as follows:

func detailView(_ row: Article) -> some View {
   SharedWebView(content: row.content)
      .navigationTitle(Text(row.title))
      .navigationBarTitleDisplayModeIfAvailable(.inline)
}
   
var body: some View {
   NavigationView {
      List(model.feed?.items ?? [], id: \.url) { row in
         NavigationLink(destination: detailView(row)) {
            Text(row.title)
         }
      }
      .navigationTitle(Text("Articles"))
      .navigationBarTitleDisplayModeIfAvailable(.inline)
      
      Color.clear
   }
   .navigationViewStyle(DoubleColumnNavigationViewStyle())
}

Here’s how it looks:

At this point, we now have an end-to-end functioning version of the app. By focussing on a single data pipeline (the feed) we’ve avoided complications and can now build on the core by adding the additional buttons and visual changes from our goal design.

Iterate on the implementation

I want the “is-read” statuses for each article and I want them to be persistent. Let’s add those now.

In the Placeholder and Stub sections, I wrote the View before the Model but at each stage, the integration required after the Model changes grew. Now that we have a non-empty View, it becomes easier to start changes at the Model so we can combine updates to the View with any required integration steps.

As you fill out a structure and pattern for your program, it becomes easier to handle more complex changes in each step. The key is to observe whether you’re able to write your code continuously – without loss of focus, mistakes or backtracking. If you find these problems occurring, it’s a sign that you should attempt iterations in smaller steps.

Model iteration

In this case, I’m going to add the “is-read” status in one step. The “is-read” implementation in Model looks like this:

@Published var isReadStatuses: [URL: Bool]

init() {
   self.isReadStatuses = UserDefaults.standard.data(forKey: "isReadStatuses")
      .flatMap { try? JSONDecoder().decode([URL: Bool].self, from: $0) } ?? [:]
   // ... feed loading omitted
}
   
func setIsRead(_ value: Bool, url: URL) {
   isReadStatuses[url] = value
   UserDefaults.standard.set(try? JSONEncoder().encode(isReadStatuses), forKey: "isReadStatuses")
}

View iteration

This latest Model change can alter the state of the detailView after it is presented (by changing the “is-read” status). For a NavigationView to change, it must observe the Model for itself (it cannot rely on the parent’s observation or else the old state will remain presented when the state changes) so we need to move the detailView into its own View implementation:

struct DetailView: View {
   @ObservedObject var model: Model
   let article: Article

   var body: some View {
      let isRead = model.isReadStatuses[article.url] ?? false
      
      return SharedWebView(content: article.content)
         .navigationTitle(Text(article.title))
         .navigationBarItems(
            trailing:
               Button {
                  model.setIsRead(!isRead, url: article.url)
               } label: {
                  Text(isRead ? "Mark as unread" : "Mark as read")
               }
         )
         .navigationBarTitleDisplayMode(.inline)
         .onAppear { model.setIsRead(true, url: article.url) }
   }
}

and use this new implementation from the primary column:

List(rows, id: \.url) { row in
   NavigationLink(destination: DetailView(model: model, article: row)) {
      HStack {
         let isRead = model.isReadStatuses[row.url] ?? false 
         Image(systemName: isRead ? "checkmark.circle" : "circle")
         Text(row.title)
      }
   }
}

Further iterations

As you can see from the this iteration, we’ve transitioned from iterating where code is thrown away to simpler feature development where new code is added but little is removed. That’s okay; that’s a sign that the core is complete.

The following features were added in this way to the final code:

Error handling
Feed reloading
Manually toggling “is-read” status on each article

and we’ve reached the goal state for the app:

Isn’t this all obvious?

Reading over what I’ve said, I don’t feel like I’ve said anything that isn’t completely obvious. Write a couple lines of code, hit build-and-run, confirm that it runs, then add more. That’s what everyone does whenever they program, isn’t it?

Despite the apparent obviousness, working in tight iterations is one of the best rules that I, too often, fail to follow.

If I were perfectly disciplined, I would merge code on my projects roughly twice per day, with each merge being between 100 and 400 lines. When this frequency is maintained, pull requests are manageable and readable, other team members can comment on direction before too much code is written and stories move right at a predictable cadence.

Unfortunately, it’s very easy to think about the bigger picture and accidentally start work on everything at once. Larger units of code are much slower to work on. It’s not an exponential increase but it’s worse than linear – integrating a 2000 line change will usually take more than 10 times longer than integrating a 200 line change. Larger code changes are also harder to reason about – team members reviewing your change are more likely to mentally disengage than give useful feedback. And mistakes tend to be bigger, harder to address and, with the time-investment, sunk-cost fallacies are more common.

If small iterations and integrations are “obvious”, why aren’t they more natural on real-world projects?

The difficulty occurs when you’re not applying a clear “iteration” and “integration” as much as you’re refactoring one shape of code into another. Finding small clear steps becomes a challenge. The stages “placeholder”, “stubs”, “functional implementation” and “further iterations” become much messier.

A few options can help…

Parallel implementations

Instead of tearing down 5000 lines of code in one block, start a new, independent implementation alongside the old one and move components from the old implementation to the new implementation, one-at-a-time. In this way, you can apply a large refactor like you might create clean new code. Code and use the new implementation for those components moved across but the old implementation for those components yet to be migrated.

Feature toggles

If the reason you can’t commit a new block of code is because it doesn’t work, then you can always turn it off with a feature toggle (a buildtime or runtime condition in the code that skips over the new code). This allows you to commit incomplete or non-functional code to the repository, get feedback and track progress. It’s not as good an option as a parallel implementation (which can be partially used from the outset) but it can still allow you to maintain momentum.

Architectural isolation

The best option to keep code changes small is to have a codebase where all definitions and functionality are isolated and no app-specific definition extends across more than a few thousand lines of code.

This approach gets difficult when your app is tens or even hundreds of thousands of lines of code but I’ll be looking at this topic further in later articles in this series.

What’s next?

In this article, I answered the question “which should you write first, View-code or Model-code” with a resounding, “maybe it’s not the most useful question”.

In the next article, I want to answer the following question: what app design pattern have I used here? I promise the answer will be more straightforward.

The code for this article is available on github and each of the iteration phases is available as a separate commit in the history.

22 short tests of combine – Part 3: Asynchrony

Sun, 18 Aug 2019 10:16:01 +1000

Looking at everything in one article got much too long so I broke it into three parts:

re-implementing the core protocols of Combine
a trio of topics: shared computation, shared reference lifetimes and sharing subscribers
asynchrony, threading and performance

This final part will look at asynchronous delivery scenarios. What happens in Combine when the next value arrives while the previous is being processed; in what ways is Combine thread-safe? Can values arrive out-of-order? Can delivered values overwhelm the subscriber? I’ll finish up with a quick look at Combine’s performance.

Download: The code for this series, CombineExploration, is available on github.

Warning: This is not a tutorial for Combine. I won’t be using Combine in anything resembling a conventional manner. This is going to be a look at some edge cases in Combine, testing behaviors that aren’t really documented and may therefore change in future.

Asynchronous problems

Asynchronous problems are those that process events that occur over time. Most programming languages have no representation of time so we’re reliant on operating-system mediated trickery (blocking, threads and event queues) to let our programming languages handle asynchrony.

Reactive programming offers abstractions over a number of different time-related operating system features but you can primarily treat reactive programming like an event queue, since the events passing through your pipelines will usually be triggered by events from an operating system event queue.

What are the problems that affect event queues?

events which overwhelm their consumers
consumers which block other processing while waiting on events
events on multiple threads triggering memory races
events on multiple threads triggering logical races

These problems are what I’ll focus on in this article.

Reactive programming generally takes a “non-blocking” approach to its API so I won’t consider point (2). While a “non-blocking” approach largely eliminates blocking as a source of problems, it means that rendezvous-based synchronization is not possible as a means of addressing point (1) (see Go’s CSP channels for an example of rendezvous-based synchronization).

Supply and demand

I’m going to start by looking at how Combine handles events which overwhelm their consumers. It’s a weird place to start because Swift’s primary audience (iOS app developers) rarely ever encounter this problem. In front-end application development, the primary source of events is user-interaction and this event stream is usually slow compared to the application’s ability to process it. I’ve chosen this as a starting point though because Combine has a lot of quirks around its design to handle supply and demand scenarios. In this case, I consider a quirk to be a feature that’s more surprising and difficult to manage than it is helpful.

Combine uses a concept called “demand” (an implementation of what is elsewhere called “backpressure”) to determine how many values a downstream subscriber will accept. When an upstream event source generates more values than the subscriber will accept, Combine throws the values away.

In the first part of this series, I implemented the following receive function (a per-subscription function that passes values to the downstream Subscriber function with the same name) like this:

func receive(_ input: Input) -> Subscribers.Demand {
   if demand > 0 {
      let newDemand = downstream.receive(input)
      demand = newDemand + (demand - 1)
      return newDemand
   }
   return Subscribers.Demand.none
}

You can see that if the current known downstream demand is zero, any received input is simply discarded. All subscriptions are expected to behave this way: if they don’t know that the downstream subscriber wants a value, they must discard it.

In synchronous scenarios, it’s uncommon to see this causing a problem because most subscribers will immediately request Demand.unlimited. To see this happening in a controlled scenario, I’ve created a special Sink implementation that allows a custom demand value and subsequent custom increases in demand.

func testDemand() {
   var received = [Subscribers.Event<Int, Never>]()
   let subject = PassthroughSubject<Int, Never>()
   let sink = CustomDemandSink<Int, Never>(
      demand: 2,
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   subject.subscribe(sink)
   
   subject.send(sequence: 1...3, completion: nil)
   sink.increaseDemand(2)
   subject.send(sequence: 4...6, completion: .finished)
   sink.increaseDemand(2)
   
   XCTAssertEqual(received, [1, 2, 4, 5].asEvents(completion: .finished))
}

The initial demand is for 2 values (i.e. the 1, 2 in the received array). The 3 value sent in the first sequence exceeds that demand and is discarded. The demand is increased by 2, 3 more values are sent and again, the last value is discarded.

Is discarding values ever a good idea?

As a quick look at demand shows: Combine handles inputs overwhelming consumers by discarding inputs. The problem here is that the discarding of data is not accompanied by an error response indicating “server/queue busy” or anything to that effect. It’s a silent failure.

There are very few situations where throwing away data without some kind of special handling of the discarded data is a good idea. The two scenarios where it would make sense to me are when:

we want only the “most recent update” to be handled
we can respond to the sender with a “server busy error”

If you carefully construct your Combine graph, you can handle the first scenario:

func testDemandWithBuffer() {
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let sink = CustomDemandSink<Int, Never>(
      demand: 1,
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   subject.buffer(size: 1, prefetch: .byRequest, whenFull: .dropOldest).subscribe(sink)
   
   subject.send(sequence: 1...3, completion: nil)
   sink.increaseDemand(1)
   subject.send(sequence: 4...6, completion: .finished)
   sink.increaseDemand(1)
   
   XCTAssertEqual(received, [1, 3, 6].asEvents(completion: nil))
}

Bizarrely, as indicated by the .asEvents(completion: nil) at the end, the .buffer prevents completion being emitted when used with .dropOldest (which seems like a bug). The completion is emitted when .dropNewest is used.

The buffer lets us ensure “scenario 1” (“most recent update”) is correctly handled.

However, “scenario 2” (responding with a “server busy error”) is much harder. Yes, buffer supports a .customError case for the whenFull parameter but that causes the entire pipeline (the “server”) to fail, rather than the request. Sending errors to the upstream requester would require giving every value in the input a sequence number and triggering a side-effect when values in the sequence are omitted – a careful task that you’d need to manually handle.

In summary, discarding values due to supply exceeding demand can work but you need to carefully build your reactive pipeline appropriately. It’s far more likely that you want to build pipelines that, by design, will never discard values.

Accidentally discarded asynchronous values

The purpose of this article is to look at asynchronous problems but I haven’t written any asynchronous code. I will, I promise, but let’s look at one last synchronous test case, to establish a baseline:

func testReceiveOnImmediate() {
   let e = expectation(description: "")
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let c = subject
      .receive(on: ImmediateScheduler.shared)
      .sink(
         receiveCompletion: { 
            received.append(.complete($0))
            e.fulfill()
         },
         receiveValue: { received.append(.value($0)) }
      )
   
   subject.send(1)
   subject.send(completion: .finished)
   wait(for: [e], timeout: 5.0)

   XCTAssertEqual(received, [1].asEvents(completion: .finished))

   c.cancel()
}

This is close to the original Combine test I showed in the first part of this series. It sends a value (1) and completes. The test calls .receive(on: ImmediateScheduler.shared) and waits on an expectation that is fulfilled at the completion of the signal but these steps do practically nothing here because everything completes synchronously.

Let’s try to use receive(on:) to perform this work on a background thread:

func testReceiveOnFailure() {
   let queue = DispatchQueue(label: "test")
   let e = expectation(description: "")
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let c = subject
      .receive(on: queue)
      .sink(
         receiveCompletion: { 
            received.append(.complete($0))
            e.fulfill()
         },
         receiveValue: { received.append(.value($0)) }
      )
   
   subject.send(1)
   queue.async { subject.send(completion: .finished) }
   wait(for: [e], timeout: 5.0)

   XCTAssertEqual(received, [].asEvents(completion: .finished))
   
   c.cancel()
}

I’ve added a custom DispatchQueue, used by the .receive(on: queue) line and I’m sending the completion on this same queue.

The important result to notice is that the received array in the XCTAssertEqual contains the completion: .finished but the value (1) has disappeared. If I hadn’t changed the completion to be sent asynchronously on the queue, then even the completion would fail to be received.

What happened to the value we sent? Why does trying to send values asynchronously in Combine cause them to fail?

The answer gets back to “demand”, again.

Earlier in this article, I showed “demand” being sent synchronously via the receive(_ input: Input) -> Subscribers.Demand function. However, when values are asynchronously received, the demand is communicated asynchronously, via the separate request(_ demand: Subscribers.Demand) function on the specified queue.

This is the cause of our lost values: the request(_ demand: Subscribers.Demand) function had not run on the background queue by the time we called subject.send(1), so the “demand” known to the PassthroughSubject is at a default of zero and it simply discarded our value.

Let’s look at this in detail with the .debug() publisher:

func testReceiveWithLogging() {
   let subject = PassthroughSubject<Int, Never>()

   print("Start...")
   var received = [Subscribers.Event<Int, Never>]()
   let cancellable = subject
      .debug()
      .receive(on: DispatchQueue.main)
      .sink(receiveValue: { received.append(.value($0)) })
   
   print("Phase 1...")
   subject.send(1)
   XCTAssertEqual(received, [].asEvents(completion: nil))
   
   print("Phase 2...")
   RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.001))
   XCTAssertEqual(received, [].asEvents(completion: nil))
   
   print("Phase 3...")
   subject.send(2)
   XCTAssertEqual(received, [].asEvents(completion: nil))
   
   print("Phase 4...")
   RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.001))
   XCTAssertEqual(received, [2].asEvents(completion: nil))
   
   cancellable.cancel()
}

Instead of running on a background DispatchQueue, I’m running everything on the main thread so I can run the RunLoop at controlled points.

The debug() line here logs each lifecycle event through it so we can see what happens at each point:

Start...
testReceiveWithLogging(), line 163: subscription PassthroughSubject
Phase 1...
Phase 2...
testReceiveWithLogging(), line 163: request unlimited
Phase 3...
testReceiveWithLogging(), line 163: output 2
Phase 4...
testReceiveWithLogging(), line 163: cancelled

The subscription occurs immediately but the request for unlimited values happens only after we let the main scheduler run. Until that point, values we might expect to be sent are completely lost.

This behavior of receive(on:) in Combine is dangerously bad to the point where I don’t think receive(on:) should ever be used in isolation in its current state. When you create a pipeline of publishers and subscribers, you should be able to immediately send values.

Safe use of receive(on:)

Bluntly, I think that receive(on:) should always include .buffer behavior. Here’s a construction that lets receive(on:) work as I would expect it to work:

func testBufferedReceiveOn() {
   let subject = PassthroughSubject<Int, Never>()
   let e = expectation(description: "")
   var received = [Subscribers.Event<Int, Never>]()
   let c = subject
      .buffer(size: Int.max, prefetch: .byRequest, whenFull: .dropNewest)
      .receive(on: DispatchQueue(label: "test"))
      .sink(
         receiveCompletion: {
            received.append(.complete($0))
            e.fulfill()
         },
         receiveValue: { received.append(.value($0)) }
      )
   
   subject.send(1)
   subject.send(completion: .finished)
   wait(for: [e], timeout: 5.0)

   XCTAssertEqual(received, [1].asEvents(completion: .finished))

   c.cancel()
}

Thread safety

Now that we see how “demand” and asynchronous receiving work, we can see that the testReceiveOnFailure test case was really an example of a race condition. There was no memory race (multiple threads accessing the same memory at the same time) but there was a logical race (where steps were not performed in the expected order due to thread timing). We fixed this race by including a buffer (which establishes demand synchronously) but this does raise the question: what actions are thread-safe in Combine? Are any actions explicitly thread unsafe?

It’s difficult to know what thread safety guarantees exist in Combine because the documentation is surprisingly empty of thread safety discussion. A web search across the Combine documentation reveals only: “Canceling a Subscription must be thread-safe” on the description of the Subscription protocol.

Let’s try some crazy things and see if we can get some thread-unsafety.

Is cancelling a subscription thread-safe?

As I showed at the end of the previous article, cancelling a subscription is not asynchronously safe:

func testSinkCancellationPlusAsyncDelivery() {
   var received = [Subscribers.Event<Int, Never>]()
   let sink = Just(1)
      .receive(on: DispatchQueue.main)
      .sink(event: { e in received.append(e) })

   sink.cancel()
   XCTAssertEqual(received, [].asEvents(completion: nil))

   RunLoop.main.run(until: Date(timeIntervalSinceNow: 0.001))
   XCTAssertEqual(received, [1].asEvents(completion: .finished))
}

This test shows us cancelling a sink, at which point we have received no values. Later a value arrives, even though we our cancelled sink.

This isn’t a memory race between threads (the narrowest definition of thread-safety) but this is a failure to preserve semantics when threads act in a valid but unexpected order could be considered thread-unsafe broader definitions. Certainly, the problem is likely to cause headaches in a number of threaded and asynchronous scenarios.

This is probably just a bug but it speaks of a lack of testing in Combine around asynchronous scenarios. The problem itself is easily fixed once you’re aware that the problem can occur. I’ve implemented one possible solution (by checking for a subscribed state when receiving) in my CustomSink, so the test will pass when swapping customSink in place of sink:

   func testSinkCancellationPlusImmediateAsyncDelivery() {
      var received = [Subscribers.Event<Int, Never>]()
      let sequence = Just(1)
         .receive(on: DispatchQueue.main)
         .customSink(
            receiveCompletion: { c in received.append(.complete(c)) },
            receiveValue: { v in received.append(.value(v)) }
         )
      
      sequence.cancel()
      XCTAssertEqual(received, [].asEvents(completion: nil))
      
      RunLoop.main.run(until: Date(timeIntervalSinceNow: 0.001))
      XCTAssertEqual(received, [].asEvents(completion: nil))
   }

Mutual exclusion

Let’s simulate a possible cause of memory races by trying to run a closure simultaneously on multiple threads.

What happens if we simultaneously send a value to a Subject/Subscriber pair from a hundred different threads at the same time? Will our Subscriber’s handler closure be concurrently invoked, causing thread safety problems?

func testSubjectOrder() {
   let sequenceLength = 100
   let subject = PassthroughSubject<Int, Never>()
   let semaphore = DispatchSemaphore(value: 0)
   
   let total = AtomicBox<Int>(0)
   var collision = false
   let c = subject
      .sink(receiveValue: { value in
         if total.isMutating {
            // Check to see if this closure is concurrently invoked
            collision = true
         }
         total.mutate { total in
            // Make sure we're in the handler for enough time to get a concurrent invocation
            Thread.sleep(forTimeInterval: 0.001)
            total += value
            if total == sequenceLength {
               semaphore.signal()
            }
         }
      })
   
   // Try to send from a hundred different threads at once
   for _ in 1...sequenceLength {
      DispatchQueue.global().async {
         subject.send(1)
      }
   }
   
   semaphore.wait()
   c.cancel()
   XCTAssertEqual(total.value, sequenceLength)
   XCTAssertFalse(collision)
}

This test confirms the receiveValue closure is never invoked simultaneously on multiple threads.

Inspecting the call to receiveValue in the debugger reveals that the PassthroughSubject.Conduit.offer function appears to block in an os_unfair_lock if another thread is sending through the PassthroughSubject.

Short answer: Combine does appear to be thread-safe due to mutexes applied by Subjects.

Sequence ordering

What happens if we do something thread unsafe in the middle of a pipeline?

Instead of sending values from 100 threads at one pipeline, lets send 100 values down one pipeline via a concurrent (and therefore non-ordered) scheduler.

func testDeliveryOrder() {
   var received = [Subscribers.Event<Int, Never>]()
   let sequence = Publishers.Sequence<ClosedRange<Int>, Never>(sequence: 1...10)
   let e = expectation(description: "")
   let c = sequence
      .receive(on: DispatchQueue.global())
      .receive(on: DispatchQueue.main)
      .sink(
         receiveCompletion: {
            received.append(.complete($0))
            e.fulfill()
         },
         receiveValue: { received.append(.value($0)) }
      )
   withExtendedLifetime(c) { wait(for: [e], timeout: 5.0) }
   XCTAssertNotEqual(received, (1...10).asEvents(completion: .finished))
}

If you use a concurrent queue, you lose your sequence ordering. I guess that makes sense but it’s worth keeping in mind that if ordering is important, then don’t use DispatchQueue.global().

Re-entrancy

Does Combine allow same-thread re-entrancy?

func testReentrancy() {
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let subscriber = Subscribers.Sink<Int, Never>(
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { v in
         if v < 3 {
            subject.send(v + 1)
         }
         received.append(.value(v))
      }
   )
   subject.subscribe(subscriber)
   
   subject.send(sequence: 1...1, completion: .finished)
   XCTAssertEqual(received, [3, 2, 1].asEvents(completion: .finished))
   
   subscriber.cancel()
}

Yes, it does. Despite using an os_unfair_lock (usually non-reentrant) as its mutex, PassthroughSubject allows same-thread re-entrancy. This operates as classic functional recursion and has the expected consequences (here, the values are appended in the reverse order to which they arrive).

For comparison, here’s another test that attempts re-entrancy via a second thread (attempting a send from the main thread onto a background thread for a Subject that is already sending):

#if false
// NOTE: this test deadlocks
func testDeadlock() {
   let subject = PassthroughSubject<Int, Never>()
   let semaphore = DispatchSemaphore(value: 0)
   
   let sequenceLength = 100
   var total = 0
   let t = mach_absolute_time()
   let c = subject
      .sink(receiveValue: { value in
         total += value
         if total < sequenceLength {
            DispatchQueue.main.sync { subject.send(1) }
         }
      })
   DispatchQueue.global().async { subject.send(1) }
   while total < sequenceLength {
      RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.001))
   }
   c.cancel()
   
   XCTAssertEqual(total, sequenceLength)
}
#endif

As you’d expect, given a recursive mutex, it deadlocks.

Performance

Do you need maximum performance in your reactive programming framework? Probably not.

For the reactive programming framework to cause performance problems, you need to be sending a lot of messages between components. Tens thousand messages per second is the point where you might start to care about the speed of the reactive programming framework, rather than the code it invokes. In these cases, it would be possible for a poorly implemented message transport mechanism to become a bottleneck.

This is not common when using reactive programming for bindings in user-applications. User-initiated events rarely exceed hundreds per second. However, if you’re using reactive programming as part of a processing queue then it becomes easily possible.

Even with a poorly performing reactive programming framework, you can usually avoid bottlenecks in your transport mechanism by aggregating inter-component messages. However, it’s nice to know that your transport is high performance so you can wait longer before needing to take optimizing steps and you won’t have to make decisions that trade latency for throughput.

A few scenarios

I ran a three-way performance test between Combine, RxSwift and CwlSignal.

	Combine	RxSwift	CwlSignal
Subject send	5.021	3.826	4.495
Sequence send	1.154	0.288	1.052
Async send	0.200	0.359	1.280
Deep pipeline	2.624	1.814	0.176

Performance on macOS 10.15 beta 6 in millions of values sent per second (higher is better)

What do these numbers tell us? Frankly, none of these numbers are too bad.

The “async send” number (critical for most operations queues where performance really matters) is a little low for Combine. Part of this slow performance is because I put a .buffer in the pipeline ahead of the receive(on:) (without this .buffer the number would be closer to 0.5 than 0.2 but that’s still a little slow).

Annoying workarounds and async issues notwithstanding, Combine is a good, high performance framework. While modern CPUs can perform billions of operations per second, it is difficult to reach 5 million iterations per second in code involving generics and mutexes, so Combine has done well.

These figures are from macOS 10.15 beta 6, running on my Mac Book Pro 2018. In beta 4, the Combine numbers looked like this:

	Combine	RxSwift	CwlSignal
Subject send	0.891	3.782	4.512
Sequence send	1.011	0.277	0.998
Async send	0.140	0.359	1.112
Deep pipeline	0.954	1.888	0.180

Performance on macOS 10.15 beta 4 in millions of values sent per second (higher is better)

You can see that since beta 4, Combine has dramatically improved on most tests. However, these numbers have been bouncing around from beta to beta (in macOS 10.15 beta 5, Combine briefly peaked at 7 million values per second on the “Subject send” test and has since dropped down to 5 million).

Conclusion

Download: The code for this series, CombineExploration, is available on github.

I’ve been hard on Combine in these three articles. I don’t think Combine is a bad framework but in its current state, I think there are a few critical areas where it works badly. I think these problem areas are going to cause reliability issues for many developers until they are addressed.

To me, the most important improvements Combine should make are:

Subscription and other “black boxes” should be fully documented (we shouldn’t be guessing about thread safety and graph lifecycles)
support buffered subjects and other ways of sharing cached computations
support scenarios where demand must never be zero
receive(on:) should synchronously establish initial demand (only subscribe(on:) should asynchronously complete construction)

I’ve shown that we can work around these problems but proper fixes will need to occur in Combine itself.

It’s apparent that Combine has kept to many of the overall goals of the Reactive Streams initiative. This initiative is promoted by groups that work with networked, multi-client, server-limited processing. The strict mandates for subscriptions and asynchronous backpressure support that use case but in my use cases (view-bindings and single-client operation queues), I’ve found the entire concepts of backpressure and subscriptions to be a hinderance and a source of spurious failures and design challenges.

What I want from Combine is to better support scenarios where multi-subscribing and demand are effectively disabled (have no measurable effect) and to focus more on caching sequences emitted by hot publishers for sharing between dynamically changing subscribers because this is the natural way to program in an imperative programming language.

22 short tests of combine – Part 2: Sharing

Sat, 17 Aug 2019 10:16:01 +1000

Looking at everything in one article got much too long so I broke it into three parts:

re-implementing the core protocols of Combine
shared computation, shared reference lifetimes and sharing subscribers
asynchrony, threading and performance

This article will be the middle third, an investigation spanning a trio of topics with “shared” in the name: shared computation, shared reference lifetimes and sharing subscribers.

Download: The code for this series, CombineExploration, is available on github.

Warning: This is not a tutorial for Combine. I won’t be using Combine in anything resembling a conventional manner. This is going to be a look at some edge cases in Combine, testing behaviors that aren’t really documented and may therefore change in future.

Hot and cold publishers

In the previous article, I focussed on Combine’s largely hidden Subscription type and the fact that Combine creates a new graph of Subscription types for every new subscriber. Using this independent subscription graph allows Combine to follow the “cold publisher” model:

A cold publisher is one where the emitted sequence of values is lazily constructed and traversed when requested by a downstream subscriber. Asynchronous tasks begin on subscription, not construction of the publisher. The graph may not change structure for the entire duration of the sequence.

The terms "cold publisher" and "hot publisher" are usually "cold observable" and "hot observable" in other Rx frameworks. I've changed the terminology to match Combine's terms but the ideas are equivalent.

In a “cold publisher” graph, you don’t need to cache values because a value exists only at the moment it is requested by a subscriber and immediately handed over. A subscriber cannot re-request old values and any request for values made by a new subscriber is really a request to calculate the values again. Caching values emitted from a “cold publisher” graph doesn’t make sense.

However, this model isn’t practical outside of strict functional programming languages. Aside from the fact that we don’t want to waste time calculating the same values, there is also the problem of network data, the filesystem, host time, user interactions and other side effects that may start before our program is ready and run independent of any Combine graph we may have created and will never play nicely with a “cold publisher” model.

In imperative programming, we need “hot publishers”.

A hot publisher may produce values at any time and at any rate, regardless of the demand from downstream subscribers. The graph may continue to change in structure during the sequence. Publishers must encode rules about what to do with values that exceed downstream demand or how to handle new subscribers joining an existing value sequence.

In almost all cases, a “hot publisher” in Combine will use a Subject (either externally or internally). Subjects play an important role in “hot” graphs because a Subject is a publisher with a single shared identity (most publishers create a new independent identity for each downstream subscription).

The essential part of working with a graph that contains “hot publishers” is that you must be able to handle new subscribers joining in the middle of a sequence.

In the previous article, I discussed the idea that there were 5 different kinds of approach to handling multiple subscribers:

multicast
caching
latest value
custom caching
resubscribe

but I looked only at resubscribe because this is the “cold publisher” favored option in Combine.

In my testOverlappingABCD example showing “resubscribe” behavior, I used Deferred to simulate a “cold publisher” while still offering the ability to manually send values into each subscription. Let’s change this example to remove the independent PassthroughSubjects created inside a Deferred closure and instead use a single, shared PassthroughSubject (without Deferred).

func testSharedSubjectABCD() {
   let subjectA = PassthroughSubject<Int, Never>()
   let scanB = subjectA.scan(10) { state, next in state + next }

   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = scanB.sink(event: { e in receivedC.append(e) })
   subjectA.send(sequence: 1...2, completion: nil)
   
   var receivedD = [Subscribers.Event<Int, Never>]()
   let sinkD = scanB.sink(event: { e in receivedD.append(e) })
   subjectA.send(sequence: 3...4, completion: .finished)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
   XCTAssertEqual(receivedD, [13, 17].asEvents(completion: .finished))
   
   sinkC.cancel()
   sinkD.cancel()
}

This no longer behaves like “resubscribe”. Now, D receives only 2 values – related to the two values sent after it connected.

This is almost what we’d expect in a “multicast” scenario except that D doesn’t receive the same 16, 20 that C receives. Instead, it receives 13, 17. What happened?

This graph has two conflicting ideas:

The shared PassthroughSubject is a shared “hot” publisher
scan is a “cold” publisher and a separate value of the state is created for each subscriber

While the PassthroughSubject is shared between C and D, there are two separate Subscription instances created for the scan (with different values of state) so we get different outputs.

This is an example of hot publishers and stateful cold publishers playing poorly together. To eliminate this strangeness, we need to entirely enclose the scan publisher in “hot” endpoints so that only one scan subscription is ever created.

We can do this by putting a Publishers.Multicast after the scan publisher:

func testMulticastABCD() {
   let subjectA = PassthroughSubject<Int, Never>()
   let multicastB = subjectA
      .scan(10) { state, next in state + next }
      .multicast { PassthroughSubject() }
   let cancelB = multicastB.connect()
   
   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = multicastB.sink(event: { e in receivedC.append(e) })
   subjectA.send(sequence: 1...2, completion: nil)
   
   var receivedD = [Subscribers.Event<Int, Never>]()
   let sinkD = multicastB.sink(event: { e in receivedD.append(e) })
   subjectA.send(sequence: 3...4, completion: .finished)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
   XCTAssertEqual(receivedD, [16, 20].asEvents(completion: .finished))
   
   sinkC.cancel()
   sinkD.cancel()
   cancelB.cancel()
}

We now have C and D correctly receiving a “multicast” version of the same stream. D receives the same 16, 20 values that C receives after it subscribes.

Caching computation

The other forms of “shared computation” that I mentioned (“caching”, “latest value” and “custom caching”) are all forms of holding onto recently emitted values.

Combine offers just one built-in way of doing this: CurrentValueSubject, which offers “latest value” caching. We can use this by replacing the PassthroughSubject<Int, Never>() in the previous test with CurrentValueSubject<Int, Never>(0). Running the test in this way confirms the following values:

XCTAssertEqual(receivedC, [0, 11, 13, 16, 20].asEvents(completion: .finished))
XCTAssertEqual(receivedD, [11, 13, 17].asEvents(completion: .finished))

A CurrentValueSubject is great for user-interfaces that always need a value and need only the latest “state” from an publisher or service.

Beyond user-interfaces though, we often need more of the stream than the latest value.

You might think that the Publishers.Buffer operator in Combine could help with this, however, this operator is actually for managing demand between a hot publisher and a downstream subscriber and doesn’t apply to buffering between downstream subscriber. The Record publisher also doesn’t seem quite right as it doesn’t really stream values from an upstream publisher. Unless I’m missing something, there isn’t a way to multicast with a playback buffer greater than one value in Combine.

What would be needed is a Subject, like CurrentValueSubject, that can buffer more than just the latest value (and doesn’t force an initial value, if none has yet been received).

I’ve implemented a custom subject to handle this scenario: BufferSubject. Dropping BufferSubject(limit: Int.max) in place of the subject constructor in the last test confirms the following values:

XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
XCTAssertEqual(receivedD, [11, 13, 16, 20].asEvents(completion: .finished))

This is a completely cached, “playback” sequence, shared between C and D. Values pass through scan and are sent immediately to C but buffered and replayed for D when it subscribes.

Reference lifetimes

In the previous test cases, I’ve been carefully calling cancel() on the Subscribers.Sink and the connect() results. This behavior is not because I wanted to cancel these values but instead because I wanted to guarantee that I was keeping their references alive so their associated subscriptions don’t get cancelled until the end of the function.

Is carefully keeping references alive strictly necessary?

The answer is complicated to test for two reasons:

In Release builds, Swift may release references in the middle of a scope (like a function) but in Debug builds, Swift usually won’t release until the end of the scope.
AnyCancellable is a reference that calls cancel() automatically on deinit. Other types of Cancellable will usually not but might (you never know).

Neither of these rules make accurate analysis easy. Let’s start with some examples that use AnyCancellable (avoiding complications with point 2) and deliberately create our own dummy scopes (which will avoid most complications with point 1).

This is how AnyCancellable behaves:

func testAnyCancellable() {
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()

   weak var weakCancellable: AnyCancellable?
   do {
      let anyCancellable = subject.sink(event: { e in received.append(e) } )
      weakCancellable = anyCancellable
      subject.send(1)
   }
   XCTAssertNil(weakCancellable)
   
   subject.send(2)
   XCTAssertEqual(received, [1].asEvents(completion: nil))
}

The anyCancellable falls out of scope at the end of the do {}, cancelling the subscription so sending the second value (send(2)) has no effect.

This is probably the behavior that is most in-line with expectations but let’s look instead at raw use of Subscribers.Sink, which conforms to Cancellable but does not offer the same “auto-cancel when released” guarantee:

func testSinkCancellation() {
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   
   weak var weakSink: Subscribers.Sink<Int, Never>?
   do {
      let sink = Subscribers.Sink<Int, Never>(
         receiveCompletion: { received.append(.complete($0)) },
         receiveValue: { received.append(.value($0)) }
      )
      weakSink = sink
      subject.subscribe(sink)
      
      subject.send(1)
   }
   XCTAssertNotNil(weakSink)
   
   subject.send(2)
   weakSink?.cancel()
   subject.send(3)
   XCTAssertEqual(received, [1, 2].asEvents(completion: nil))
}

The Sink is not strongly referenced outside the do {} but is still alive when the send(2) value reaches the received array. It is only when we explicitly call cancel() that further values stop being delivered.

If we drop all our strong references to Sink, it can continue to receive values while there is an active subscription. In fact, we can drop our PassthroughSubject, too:

func testOwnership() {
   var received = [Subscribers.Event<Int, Never>]()

   weak var weakSubject: PassthroughSubject<Int, Never>?
   weak var weakSink: Subscribers.Sink<Int, Never>?
   do {
      let subject = PassthroughSubject<Int, Never>()
      weakSubject = subject
      let sink = Subscribers.Sink<Int, Never>(
         receiveCompletion: { received.append(.complete($0)) },
         receiveValue: { received.append(.value($0)) }
      )
      weakSink = sink
      subject.subscribe(sink)
   }
   XCTAssertNotNil(weakSubject)
   XCTAssertNotNil(weakSink)

   weakSubject?.send(1)
   weakSubject?.send(completion: .finished)

   XCTAssertNil(weakSubject)
   XCTAssertNil(weakSink)
   XCTAssertEqual(received, [1].asEvents(completion: .finished))
}

We don’t have to hold any references to the graph. It continues to stay alive, all on its own, until the current subscription completes.

This is a dangerous scenario. In short, to have sane memory management with Combine, you must ensure there is at least one AnyCancellable connected to your graph.

Multiple subscriptions

Many of these test cases have focussed on what happens when there are multiple Subscribers connected to the same Publisher.

What happens if you do the inverse: take a single Subscribers.Sink and subscribe it to multiple Publishers?

func testMultipleSubscribe() {
   let subject1 = PassthroughSubject<Int, Never>()
   let subject2 = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let sink = Subscribers.Sink<Int, Never>(
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   subject1.subscribe(sink)
   subject2.subscribe(sink)

   subject1.send(sequence: 1...2, completion: .finished)
   subject2.send(sequence: 3...4, completion: .finished)
   
   XCTAssertEqual(received, (1...2).asEvents(completion: .finished))
}

Short answer: the Sink remains subscribed to the first subject and ignores everything from the second. However, it’s not an error of any kind, just a silent failure. It seems like sharing a Subscriber isn’t something you should ever do.

This test isn’t just abstract interface abuse. I want something that offers the ability to subscribe multiple times to different upstream subscriptions with this kind of simplicity. For the first subscription to a Publisher, the downstream Subscriber will own the subscription and will cancel it if the downstream nodes are cancelled. It’s elegant and self-contained but handles just one subscription.

The only multi-subscribable interface in Combine, by default, is Subject:

func testMultiSubjectSubscribe() {
   let subject1 = PassthroughSubject<Int, Never>()
   let subject2 = PassthroughSubject<Int, Never>()
   let multiInputSubject = PassthroughSubject<Int, Never>()
   let cancellable1 = subject1.subscribe(multiInputSubject)
   let cancellable2 = subject2.subscribe(multiInputSubject)
   var received = [Subscribers.Event<Int, Never>]()
   let multiInputCancellable = multiInputSubject.sink(
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   
   subject1.send(sequence: 1...2, completion: nil)
   subject2.send(sequence: 3...4, completion: .finished)
   
   XCTAssertEqual(received, [1, 2, 3, 4].asEvents(completion: .finished))

   cancellable1.cancel()
   cancellable2.cancel()
   multiInputCancellable.cancel()
}

This works – the multiInputCancellable receives from both subject and subject2 – but you must hold onto each AnyCancellable and there’s no implicit cancellation of upstream subscriptions the subject falls out of scope.

Fortunately, it’s very easy to set up a better approach where these upstream Cancellables are held internally and automatically cancelled when the downstream is cancelled. It involves little more than a combination of the subjects and sinks from the previous test, hidden behind a clean interface:

func testMergeSink() {
   var received = [Subscribers.Event<Int, Never>]()
   let subject1 = PassthroughSubject<Int, Never>()
   let subject2 = PassthroughSubject<Int, Never>()
   let input = MergeInput<Int>()
   subject1.merge(into: input)
   subject2.merge(into: input)
   let cancellable = input.sink(receiveValue: { received.append(.value($0)) })

   subject1.send(sequence: 1...2, completion: .finished)
   subject2.send(sequence: 3...4, completion: .finished)
   
   XCTAssertEqual(received, [1, 2, 3, 4].asEvents(completion: nil))

   cancellable.cancel()
}

This MergeInput interface does not receive completion from upstream publishers. This is an intentional choice: for this type of multi-input scenario, you generally don’t want one input to close the MergeInput and cut off all other inputs.

Subscriber reactivation

The previous tests revealed that a Subscriber will not accept new subscriptions while it already has an active subscription. A related question is: what happens if you subscribe to a second Publisher after the first subscription completes? Can you “reactivate” a completed subscriber?

func testSinkReactivation() {
   var received = [Subscribers.Event<Int, Never>]()
   let sink = Subscribers.Sink<Int, Never>(
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   
   weak var weakSubject: PassthroughSubject<Int, Never>?
   do {
      let subject = PassthroughSubject<Int, Never>()
      weakSubject = subject
      subject.subscribe(sink)
      
      subject.send(1)
   }
   XCTAssertNotNil(weakSubject)
   
   weakSubject?.send(completion: .finished)
   
   // At this point, the first subscription to sink is finished
   XCTAssertNil(weakSubject)
   XCTAssertEqual(received, [1].asEvents(completion: .finished))
   
   // Try to start a new one
   let subject2 = PassthroughSubject<Int, Never>()
   subject2.subscribe(sink)
   subject2.send(2)
   
   #if false
      // Prior to macOS 10.15 beta 6...
      XCTAssertEqual(received,
         [1].asEvents(completion: .finished) + [2].asEvents(completion: nil)
      )
   #else
      // In macOS 10.15 beta 6...
      XCTAssertEqual(received,
         [1].asEvents(completion: .finished)
      )
   #endif
}

This is an example of behavior that changed while I was writing this series on Combine. Until macOS 10.15 beta 7, it was possible to reuse a subscriber, once any previous subscription completed.

Apparently, that changed in beta 7. Now, a Subscriber is strictly a non-shareable object. It lives for the duration of a subscription and subsequently declines to do anything more.

Conclusion

Download: The code for this series, CombineExploration, is available on github.

I don’t personally like cold publishers. I think they are a counter-intuitive solution to some edge cases that can create problems in some common cases. Any interaction between hot publishers and stateful cold publishers needs to be carefully managed to achieve consistent outputs.

Combine offers no built-in way to cache more than a single value. Fortunately, I’ve shown that it isn’t particularly difficult to buffer additional values by creating a custom BufferSubject that you can use with Multicast.

The subscriber graph in Combine maintains a reference counted loop while a subscription is active. If you’re using .sink (or a handful of other convenience methods) as part of your graph, this won’t matter, since the returned AnyCancellable will break the loop. However, more manual constructions – like using Subscribers.Sink – don’t offer the same convenience so be careful to wrap types in AnyCancellable as appropriate to avoid memory leaks.

Tests reveal Subscribers.Sink will not trigger any kind of error if you subscribe it multiple times but it will not listen to new subscriptions.

If you want a sink that handle multiple inputs, you must use a Subject. The default Publisher.subscribe(Subject) is a little fussy (requiring you hold onto additional Cancellable instances) so I provided a convenience merge(into:) for the purpose.

Looking forward…

Given the tested behavior showing Subscriber ignores subsequent subscriptions and attempts at reuse after completion, you might expect that Subscriber will never emit values once it reaches the end of a sequence or is cancelled.

You’d be wrong.

func testSinkCancellationPlusAsyncDelivery() {
   var received = [Subscribers.Event<Int, Never>]()
   let sink = Just(1)
      .receive(on: DispatchQueue.main)
      .sink(event: { e in received.append(e) })

   sink.cancel()
   XCTAssertEqual(received, [].asEvents(completion: nil))

   RunLoop.main.run(until: Date(timeIntervalSinceNow: 0.001))
   XCTAssertEqual(received, [1].asEvents(completion: .finished))
}

This test shows us cancelling a sink, at which point we have received no values. Later a value arrives on our cancelled sink.

There’s a possibility that this behavior is Combine “behaving as expected” but realistically there is no scenario where this is a good outcome. Combine has some serious rough edges around anything asynchronous and this is not the only scenario that causes problems.

In the final part of this series, I’ll look at why this behavior occurs and some possible workarounds until Combine fixes its design to eliminate these problems.

22 short tests of Combine – Part 1: Protocols

Fri, 16 Aug 2019 10:16:01 +1000

I wrote some experiments around Combine, Apple’s reactive programming framework, to gain insight into how Combine handles edge cases that have caused problems for me in other reactive programming frameworks. How do subscriptions work? How do I cache computations? When are publishers and subscribers released? Under what circumstances is Combine thread-safe? Is re-entrancy possible? Does Combine guarantee delivery-order? How does Combine’s performance compare to pre-existing reactive frameworks?

Looking at everything in one article got much too long so I broke it into three parts:

re-implementing the core protocols of Combine
a trio of topics: shared computation, shared reference lifetimes and sharing subscribers
asynchrony, threading and performance

This article will be the first third of my investigation, covering an effort to re-implement the three key protocols of Combine: Publisher, Subscriber and Subscription.

Download: The code for this series, CombineExploration, is available on github.

Warning: This is not a tutorial for Combine. I won’t be using Combine in anything resembling a conventional manner. This is going to be a look at some edge cases in Combine, testing behaviors that aren’t really documented and may therefore change in future.

Publisher and Subscriber

Apple’s Combine is built around two key protocols, Publisher and Subscriber.

The naïve intepretation of Combine is that a Publisher emits a sequence of values.

This common interpretation is not accurate but the distinction between this “naïve” interpretation and an “accurate” interpretation is rare enough that we often ignore the difference.

Publisher is defined as:

protocol Publisher {
   associatedtype Output
   associatedtype Failure : Error
   func receive<S>(subscriber: S) where S : Subscriber, Self.Failure == S.Failure, Self.Output == S.Input
}

According to the protocol, a Publisher does not emit values but receives Subscribers. Of course, depending on what a Subscriber is, the Publisher might still directly emit values into these Subscribers that it receives.

So let’s look at the Subscriber protocol for a clearer picture:

protocol Subscriber : CustomCombineIdentifierConvertible {
   associatedtype Input
   associatedtype Failure : Error
   func receive(_ input: Self.Input) -> Subscribers.Demand
   func receive(completion: Subscribers.Completion<Self.Failure>)
   func receive(subscription: Subscription)
}

Ignoring that last function for now, the other functions here on Subscriber appear to support the “naïve” interpretation: the Publisher receives Subscribers and can send Input values or Completion events directly to all known Subscribers.

Let’s establish a “control case” to which we can compare other tests, starting with a fairly standard test of the Publisher and Subscriber model where a Subscribers.Sink (a typical Subscriber) is subscribed to a PassthroughSubject (not exactly a typical Publisher but helpful in tests since it lets us inject values easily from outside) and we record the values that pass from the subject to the sink.

func testSubjectSink() {
   let subject = PassthroughSubject<Int, Never>()
   var received = [Subscribers.Event<Int, Never>]()
   let sink = Subscribers.Sink<Int, Never>(
      receiveCompletion: { received.append(.complete($0)) },
      receiveValue: { received.append(.value($0)) }
   )
   
   subject.subscribe(sink)
   subject.send(sequence: 1...3, completion: .finished)
      
   XCTAssertEqual(received, (1...3).asEvents(completion: .finished))
}

This test includes a few of my own additions to make the tests easier:

Subscribers.Event is just an “either” over the Value and Completion types of a Combine sequence
send(sequence:completion:) sends all values in the sequence and the completion
asEvents creates an array of Subscribers.Event from an array of Value and a Completion.

This test conforms to the “naïve” interpretation: values are sent to the subject are received by the closure we passed to the sink.

Graph mutations over time

Imagine a basic subject, A, that generates values over time (e.g. a network connection), followed by a stateful transforming node B (e.g. a scan or similar streaming processor), followed by an observer C (e.g. a Sink):

func testScan() {
   let subjectA = PassthroughSubject<Int, Never>()
   let scanB = Publishers.Scan(upstream: subjectA, initialResult: 10) { state, next in state + next }
   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = Subscribers.Sink<Int, Never>(
      receiveCompletion: { receivedC.append(.complete($0)) },
      receiveValue: { receivedC.append(.value($0)) }
   )

   scanB.subscribe(sinkC)
   subjectA.send(sequence: 1...4, completion: .finished)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
}

There’s an extra transformation line (the scanB line) but relative to the original control case it’s not much different.

Now, what happens when, halfway through A streaming its data, a new observer D subscribes to B, totally unaware that B is already in the middle of its output?

Should the new listener D get half the data it expected, even though it doesn’t know about C and the fact that the connection is already started?

The answer is complicated. Depending on your program’s logic, you may want any of the following options:

multicast – D receives the second half of the values that C receives
caching – the first half is buffered and D immediately receives the first half of the message upon joining and new values like multicast
latest value – D receives the last emitted value immediately and new values like multicast
custom caching – D receives only as much as needed (e.g. since the last keyframe or resume point) and new values like multicast
resubscribe – D should trigger all upstream nodes to restart their work, go all the way back to the network and re-request all data, performing all calculations, again

In this article, I will focus only on the last of these options since it is, arguably, the default behavior in Combine. In the next article, I’ll look at the other approaches.

For now though, here’s an example of resubscribe behavior:

func testSequenceABCD() {
   let sequenceA = Publishers.Sequence<ClosedRange<Int>, Never>(sequence: 1...4)
   let scanB = Publishers.Scan(upstream: sequenceA, initialResult: 10) { state, next in state + next }
   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = Subscribers.Sink<Int, Never>(
      receiveCompletion: { receivedC.append(.complete($0)) },
      receiveValue: { receivedC.append(.value($0)) }
   )
   var receivedD = [Subscribers.Event<Int, Never>]()
   let sinkD = Subscribers.Sink<Int, Never>(
      receiveCompletion: { receivedD.append(.complete($0)) },
      receiveValue: { receivedD.append(.value($0)) }
   )

   scanB.subscribe(sinkC)
   scanB.subscribe(sinkD)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
   XCTAssertEqual(receivedD, [11, 13, 16, 20].asEvents(completion: .finished))
}

None of the nodes here are recreated and most importantly, the B node – the stateful scan processor – is shared between subscriptions, yet each of C and D receive an independent version of the values.

In case you think something weird is happening because the sequences don’t actually overlap in time, here’s an equivalent test where the sequences values are manually delivered in an overlapping fashion:

func testOverlappingABCD() {
   var subjects = [PassthroughSubject<Int, Never>]()
   let deferred = Deferred { () -> PassthroughSubject<Int, Never> in
      let request = PassthroughSubject<Int, Never>()
      subjects.append(request)
      return request
   }
   let scanB = Publishers.Scan(upstream: deferred, initialResult: 10) { state, next in state + next }
   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = Subscribers.Sink<Int, Never>(
      receiveCompletion: { receivedC.append(.complete($0)) },
      receiveValue: { receivedC.append(.value($0)) }
   )
   var receivedD = [Subscribers.Event<Int, Never>]()
   let sinkD = Subscribers.Sink<Int, Never>(
      receiveCompletion: { receivedD.append(.complete($0)) },
      receiveValue: { receivedD.append(.value($0)) }
   )

   scanB.subscribe(sinkC)
   subjects[0].send(sequence: 1...2, completion: nil)
   scanB.subscribe(sinkD)
   subjects[0].send(sequence: 3...4, completion: .finished)
   subjects[1].send(sequence: 1...4, completion: .finished)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
   XCTAssertEqual(receivedD, [11, 13, 16, 20].asEvents(completion: .finished))
}

This test case shows that the “naïve” interpretation of Combine cannot properly describe how Combine works in all cases. While there are two PassthroughSubjects, two Subscriber.Sinks, there is only one scanB node in the Publisher graph, yet it behaves like two completely different nodes – one for the sinkC and one for the sinkD.

Subscription, the mostly-hidden type

How does this work?

Despite the programmer creating a single graph of Publishers, there is a shadow graph of other instances that really performs the value processing and sending. We can see this shadow graph in the last function in Subscriber protocol.

func receive(subscription: Subscription)

Every Publisher in your graph is shadowed by one instance of Subscription per active Subscriber.

We didn’t see the effects of this shadow Subscription graph in the first testScan example because the shared PassthroughSubject tied all the subscriptions together but when we moved to using Deferred, the graphs become untied and independent and we could see the effects of multiple Subscriptions at the scan node.

The accurate interpretation of Combine is that values are sent and processed through a graph of Subscription instances, lazily constructed by Publisher instances on a per-subscribe basis.

We don’t usually interact with Subscription instances. Subscription instances are created automatically by Publishers when a Subscriber subscribes. The graph of Subscription instances mirrors the graph of Publishers.

You can see why the distinction between the Publisher graph and the Subscriber graph (the distinction between the “naïve” and “accurate” interpretations) can be confusing. Further adding to the confusion is that there are no usable public implementations of Subscription (I’m ignoring Subscriptions.empty which is a placeholder that ignores everything).

The subscription concept was introduced by the Reactive Extensions for .NET, attempting to make each mutation of the graph behave like a completely separate, unrelated graph – as it might appear in a strict functional programming language. However, strict functional programming languages cache function results, so redundant recalculation of upstream values is avoided. In Swift, if we don’t cache it ourselves, everything is repeated.

If I wanted to repeat all the processing, I would have recreated the publisher graph.

When I wrote my own reactive programming framework, CwlSignal, the main Signal instances were the delivery graph – the “naïve” interpretation was the same as the “accurate” interpretation. I handled the problem with multiple subscribers a different way: Signal nodes allowed only a single child to observe. For those specific cases where you need multiple listeners, CwlSignal offered a special SignalMulti node that encoded choices like “multicast”, “continuous” (cache latest), “playback” (cache all). But a re-subscribe option deliberately wasn’t offered.

In any case, let’s look under the hood at the definition of Subscription:

public protocol Subscription : Cancellable, CustomCombineIdentifierConvertible {
    func request(_ demand: Subscribers.Demand)
}

It’s pretty terse. If this is the entire definition of the shadow value sending graph, it’s not revealing much.

Custom implementations

Fortunately, Subscription isn’t impossible to understand. It generally just performs all the roles of the Publisher and Subscriber in the “naïve” interpretation: it receives values, processes them and passes them down the line.

A Subscription should replicate everything important from its associated Publisher, copying any closures and state from the initial values stored in the Publisher. In this way, the Subscription is independent and has everything needed to handle the processing, without further assistance from the Publisher.

The trickiest part is working out when to create a Subscriber from a Publisher and getting everything to piece together. I arrived at the following steps, centered on Publisher.receive, after a little experimentation:

NOTE: the words Subscriber and Subscription are very similar. I’m sure this is going to get confusing (it was confusing to write).

You invoke Combine’s subscribe function on your Publisher, passing your Subscriber.
This will call through to your Publisher’s receive function passing the Subscriber you provided to the subscribe function
In the receive function Publisher creates a custom Subscription instance, which should also conform to Subscriber and should hold a reference to the downstream Subscriber.
Your Publisher calls subscribe on its upstream Publisher (if any) passing the custom Subscription (this is why it should conform to Subscriber).
The upstream Publisher calls receive on your custom Subscription, passing its own subscription instance.
Your Subscriber should call receive on its downstream Subscriber
The downstream Subscriber will invoke request on your Subscription and your Subscription should invoke request on its upstream Subscription.

The exact steps tend to vary based on whether your Publisher has an upstream Publisher or is a Subject.

Let’s focus on a transforming Publisher with an upstream Publisher, since that’s the canonical case. Such a Publisher would have a receive function that looks like this:

public func receive<S>(subscriber: S) where S: Subscriber, Failure == S.Failure, Output == S.Input {
   let downstream = AnySubscriber(subscriber)
   let behavior = CustomTransformer.Behavior(
      downstream: downstream,
      processor: processor,
      state: initialState)
   let subscription = CustomSubscription(behavior: behavior)
   upstreamPublisher.subscribe(subscription)
}

There’s a very important trick here: even though we are a downstream node (and could implement Subscriber for ourselves), we don’t pass ourselves to the upstreamPublisher. Instead we pass the newly constructed Subscription instance instead. This is why Subscription implementations are often Subscriber implementations too. The Subscription instances are their own, independent delivery graph, connected only to other Subscription instances.

I chose to design my custom subscription in two parts: a wrapper (to apply mutex behaviors) and a behavior protocol (used to apply Publisher specific behaviors inside the mutex). The mutex wrapper is therefore implemented just once and the behavior content is simpler.

Here’s the wrapper interface:

public struct CustomSubscription<Content: SubscriptionBehavior>: Subscriber, Subscription {
   public typealias Input = Content.Input
   public typealias Failure = Content.Failure
   
   public var combineIdentifier: CombineIdentifier { return content.combineIdentifier }
   let recursiveMutex = NSRecursiveLock()
   let content: Content
}

and the SubscriptionBehavior inside it looks like this:

public protocol SubscriptionBehavior: class, Cancellable, CustomCombineIdentifierConvertible {
   associatedtype Input
   associatedtype Failure: Error
   associatedtype Output
   associatedtype OutputFailure: Error

   var demand: Subscribers.Demand { get set }
   var upstream: Subscription? { get set }
   var downstream: AnySubscriber<Output, OutputFailure> { get }
   
   func request(_ d: Subscribers.Demand)
   func receive(_ input: Input) -> Subscribers.Demand
   func receive(completion: Subscribers.Completion<Failure>)
}

The implementations are then straightforward: values arrive via the receive functions and are processed as appropriate for the publisher that created the instance and emitted to the downstream AnySubscriber.

You can see the full implementation of CustomSubject, CustomScan, CustomSubscription and CustomSink in the CombineExploration repository.

Is this how the implemention of Subscription looks in Combine? Almost certainly not. As far as I can tell, Combine uses a type called Conduit which applies its mutex once at the start, rather than once for every Publisher stage in the pipeline. Conduit does use a recursive mutex implementation (more on that in part 3 of this series) but it appears to be implemented on top of os_unfair_lock (which is usually a non-recursive mutex).

However, these implementations do appear to behave correctly and interoperate correctly with the official Combine implementations.

Here’s the previous testOverlappingABCD rewritten with these implementations, showing that they function as drop-in replacements for the default implementations:

func testCustomABCD() {
   var subjects = [CustomSubject<Int, Never>]()
   let deferred = Deferred { () -> CustomSubject<Int, Never> in
      let request = CustomSubject<Int, Never>()
      subjects.append(request)
      return request
   }
   let scanB = CustomScan(upstream: deferred, initialResult: 10) { state, next in state + next }
   var receivedC = [Subscribers.Event<Int, Never>]()
   let sinkC = CustomSink<Int, Never>(
      receiveCompletion: { receivedC.append(.complete($0)) },
      receiveValue: { receivedC.append(.value($0)) }
   )
   var receivedD = [Subscribers.Event<Int, Never>]()
   let sinkD = CustomSink<Int, Never>(
      receiveCompletion: { receivedD.append(.complete($0)) },
      receiveValue: { receivedD.append(.value($0)) }
   )

   scanB.subscribe(sinkC)
   subjects[0].send(sequence: 1...2, completion: nil)
   scanB.subscribe(sinkD)
   subjects[0].send(sequence: 3...4, completion: .finished)
   subjects[1].send(sequence: 1...4, completion: .finished)
   
   XCTAssertEqual(receivedC, [11, 13, 16, 20].asEvents(completion: .finished))
   XCTAssertEqual(receivedD, [11, 13, 16, 20].asEvents(completion: .finished))
}

Conclusion

Download: The code for this series, CombineExploration, is available on github.

We frequently talk about our Publisher graphs as though they perform a calculation and emit values but this isn’t really true. Values in Combine are sent by the Subscription graph and the calculation is repeated for each Subscription graph.

The distinction between Publisher and Subscription graphs exists to prevent separate subscribers from interferring with each other. For this to work, all stream processing state you set up in a custom Publisher must be copied into a Subscription and mutated there, exclusively.

Looking forward…

In most cases, we don’t want redundant calculations. Where possible, we want values calculated once per Publisher graph and we want the latest value shared between all subscribers.

How do we avoid “resubscription” in Combine? How do we get multicast or cached results? Will we need to use connect or hold redundant subscribe cancellables as we do in RxSwift? For that matter, what is needed, in general, to keep Combine subscriptions alive? What are the rules by which Combine keeps anything (Publishers, Subscribers or Subscriptions) alive?

This is what I’ll look at in the next article: sharing.

Cocoa with Love

Using Copilot to write a raindrop audio synthesizer using AVAudioEngine

The setup

Alternative setup

Tone Generator

First effort

Second effort

Let’s synthesize a raindrop sound

Charting the waveform

Adding some noise

Cleaning up thread safety

Conclusion

Is it a good rain synthesizer?

What was Copilot good at?

Ways in which Copilot was better than expected but not great

What was Copilot bad at?

Problems with VS Code + Copilot for Swift

Was Copilot worth it?

App architecture basics in SwiftUI Part 4: Services

Let’s try to add tests to CwlFeedReader

The problem is broader than testing

Putting it in a diagram

Some clarification around the word “Services”

How can we decouple the Model from Services?

1. Decouple from production server using different environments

Pros

Cons

2. Put a protocol around the smallest possible subset of URLSession

Pros

Cons

3. Expand the protocol boundary to include related busy-work

Pros

Cons

Personal opinion

Using the Services-layer from the Model

Constructing services

Organize into modules to preserve separation

A final diagram

Replacing the Services-layer at testing time

Some ugliness due to missing SE-0273 functionality

Conclusion

App architecture basics in SwiftUI Part 3: Module-separated layers

The problem

1. Interface design

2. Connection rules

3. Unit testing

Creating an inline Swift Package

Establishing the desired structure

Imports and access modifiers

Submodules?

Conclusion

Looking forward…

App architecture basics in SwiftUI, Part 2: SwiftUI's natural pattern

Changes triggered by model data

Construction role

Event handling role

Data binding role

Taken together, what does all this mean?

Why is the pattern not MVVM?

Why do people claim SwiftUI is MVVM?

Is it the Model-data bindings?

Is it Combine?

Is it just because UIViewController is gone?

Conclusion

Looking forward…

App architecture basics in SwiftUI, Part 1: Coding through iteration and integration

Where to start?

Placeholders

View placeholder

Model placeholder

Placeholder integration

Stubs

Stub views

Stub model

Stub integration

Functional implementations

Model functional implementation

View functional implementation

Iterate on the implementation

Model iteration