Copy-on-write teaches you EVERYTHING about Swift Internals 🐮

isKnownUniquelyReferenced through the standard library, compiler, and runtime

There is a global function in Swift that, when you fully understand it, will teach you everything you need to know about Swift internals.

You’ll never guess what it is, because I guarantee you’ve used it less than 3 times in the real world, if you’ve even heard of it.

isKnownUniquelyReferenced().

If you know, you know: this function powers the copy-on-write optimisation (a.k.a. CoW, a.k.a.k.a. 🐮).

It pretty much only ever comes up if a) you’re a library author, or b) you’re interviewing someone and want to rate their power level when it comes to Swift internals*

*I never let interviews get to this point, because I burn 45 minutes responding to their first question about weak references.

I wanted to understand how this function worked, and little did I know that it would take me on an odyssey through every single layer and sublayer of the Swift source code. Seriously. Every layer.

As it happens, it’s pretty much the perfect candidate for doing this. type(of:) comes close, but doesn’t quite stick the landing in as satisfying a way.

Will learning all this make your hairline recede another inch? Yes.

Are you going to come on a fun journey to learn Swift Internals™? Also yes.

Let’s work through the various sublayers of the p̶l̶a̶n̶e̶t̶ Swift Source Code and discover once and for all how isKnownUniquelyReferenced works.

I kind of wanted to do a Donkey Kong Bananza bit with each section representing a different sublayer but I truly did not think enough people would get the reference.

Journey to the centre of the 🐮

(yes we’re really going through all these)

• What is 🐮?

  • Value and reference semantics

  • 🐮 In the Swift Standard Library

• Implementing 🐮

• The Swift Standard Library

• Builtins

• (Interlude) The Swift Compiler

  • Our isKnownUniquelyReferenced Compass

• The Abstract Syntax Tree

  • Builtins on the AST

  • Synthesising a Builtin Function

  • The Builtin Module

  • AST Recap

• Swift Intermediate Language

• LLVM Intermediate Representation

• The Swift Runtime

  • Checking the Docs

  • SwiftObject

  • HeapObject

• SwiftShims

• The isKnownUniquelyReferenced Meme

• Last Orders

---

This article is extremely detailed, and so your email client will probably cut it off.

Read on my website for the best experience:

---

What is 🐮?

For anyone who hasn’t brushed up on their interview prep recently:

🐮 optimises the performance of a Swift struct to get the best of both worlds:

• easy-to-reason-about value semantics.

• low memory overhead from reference semantics.

“Uhh, I just said I wasn’t doing interviews, can you not drop terms like “reference semantics” as if I remember what they are?” I hear you say from the future.

Right. Sorry.

---

Value and reference semantics

Value semantics = copies are independent entities

Reference semantics = copies point to the same underlying memory on the heap

structs that utilise 🐮 store their data in a memory buffer on the heap.

When the struct is copied, all the properties are copied, including the 64-bit pointer to the backing data, referencing the memory address 0x00000000d34db33f.

This is a shallow copy. Each copy of the reference still points to the same underling memory. This underlying memory is shared. This is reference semantics.

When the value of the data on a copy of a 🐮 struct changes, value semantics kick in.

The struct allocates a new buffer of memory on the heap, copies the updated data there, then points at the new buffer. A deep copy. It leaves the original memory block, and other instances of the struct pointing to it, unchanged.

---

🐮 In the Swift Standard Library

Many fundamental types in the Swift Standard Library utilise the 🐮 (copy-on-write) optimisation:

• Array

• Set

• Dictionary

• String

• Data (actually an impostor from Foundation, but it’s one of the gang).

When using these data structures in your code, or even types that contain them, you reap the benefits of the underlying 🐮 optimisation for free.

But it’s possible to implement 🐮 in your own types, too!

---

Implementing 🐮

Very senior iOS engineers will tell you how you can implement your own types that utilise 🐮. Check out this sample robbed straight from Apple’s Swift Optimisation Tips:

In short, you place your struct, T, in Box.

Box wraps T in a reference, Ref, placing the structure on the heap.

You can read the value inside Box trivially.

When you write the value, we check if the memory inside Ref is uniquely referenced, that is, if there is only one pointer to this instance. If it is unique, the value mutates in-place. Otherwise, the heap memory buffer under Ref is copied into a new address before mutation. The Ref pointer inside Box changes to point to this new address.

This illustrative example shows how isKnownUniquelyReferenced can be used to implement 🐮, but it’s kind of sh*tty for real life code: you’re polluting your type with slower reference access semantics to make copying a bit more efficient.

It’s only a good idea when copying is expected and there is enough memory that it makes sense to place it on the heap.

A mysterious function, isKnownUniquelyReferenced, is the secret sauce that makes this optimisation possible.

As it turns out, it’s fucking mysterious, because I originally spent about 3 weeks traversing megabytes of C++ (in 2023, before AI tooling could even touch this kind of task) to understand what the hell it was doing.

---

The Swift Standard Library

First things first.

Let’s download the Swift source code, search for isKnownUniquelyReferenced, and take a gander at the implementation.

Or, you can just CMD+Click that bad boy in Xcode.

It’s holed up in ManagedBuffer.swift, underneath the definition of ManagedBufferPointer. I don’t love putting global functions in the same file as semi-related data structures, but who am I to question the wisdom of our Cupertinoverlords?

Here’s the implementation of isKnownUniquelyReferenced I’ve been searching for in all its glory:

All in a day’s work.

I’ll head to the pub now for a well-deserved beverage.

---

Builtins

I’ve got my beer!

Uh, I suppose I don’t have much else on.

Perhaps we can dive a little bit deeper and find out what _isUnique is doing.

Much deeper. Including Builtins, The Swift Compiler, The Abstract Syntax Tree, Swift Intermediate Language, LLVM Intermediate Representation, The Swift Runtime, SwiftShims, and The isKnownUniquelyReferenced Meme.

Upgrade to read this article right now, or wait until January 19.

Paid members get several benefits:

🌟 Access Elite Hacks, my exclusive advanced content
🚀 Read my free articles a month before anyone else
🧵 Master concurrency with my full course and advanced training

---

Like Ebenezer Scrooge, I’ve been tightfisted and stingy with my paid subscriptions. Also like Scrooge, I’ve been overdoing it on the antihistamines lately, and suffering the subsequent fitful nights haunted by various Christmas-themed ghosts.

AND I’M PASSING THE SAVINGS ONTO YOU!
Claim your free month this Christmas.