You can find video version of this article here.

In the previous article, we covered the key aspects of Swift Concurrency to build a solid mental model of it. In this article, we will discuss structured and unstructured tasks. You’ll see that their behavior can be tricky in some scenarios, but we’ll break it down into rules to make it clear.

⚠️ : I assume you are familiar with the basic concepts of Structured Concurrency like async let and task group. If not, you can start here.

Structured and Unstructured Tasks

From previous article, we know that to switch gears from sync context to async context we need to use tasks. However, that is not the only use case for tasks. Tasks are, in fact, a much broader concept in Swift Concurrency.

💡: Tasks are units of asynchronous work you can run from your code.

• Every async function is executing in a task. In other words, a task is to asynchronous functions, what a thread is to synchronous functions.

• A task runs one function at a time; a single task has no concurrency.

• Synchronous functions do not necessarily run as part of a task, but they can.

In terms of Structured Concurrency, there are 2 kinds of tasks:

• Structured Concurrency Tasks (we will call them simply Structured Tasks)

  • Represented by async let and task group

• Unstructured Concurrency Tasks (we will call them simply Unstructured Tasks)

  • Represented by regular unstructured task (Task { … }) and detached task (Task.detached { … })

⁉️ : What is the difference between Structured and Unstructured tasks?
Why they are actually called “structured” and “unstructured”? What does it mean? To understand the difference we need to understand the parent and child relation for tasks.

Parent and Child Tasks

• Parent Task is a task that spawns one or more subtasks (child tasks). Parent task is responsible for managing its child tasks.

• Child Task is a subtask created within the context of a parent task. Child tasks return their results (if any) to the parent task (if explicitly awaited).

Parent and child tasks together form a task tree structure, that simplifies control over related tasks completion, cancellation and resource management.

Root Task is an initial task in task tree (root node), which can be parent if it spawns child tasks.

• Structured task can be a child or parent task (or both). But it can’t be root node in the task tree.

• Unstructured task can’t be a child task. But it can be a parent task if you create new child structured tasks from them. In other words, unstructured task can only be a root node in task tree structure.

That's why they are called "structured" and "unstructured" tasks:

• Structured tasks always join the current task tree structure as child tasks.

• Unstructured tasks never join the current task tree. They start a new, independent task tree as a root node with no parent-child relation to the original task, with child tasks created later if needed.

⚠️ : Although we can nest one unstructured task within another, don’t be misled by that - it doesn’t create a parent-child relationship between them, regardless of whether the tasks are regular or detached. Later, we will demonstrate through examples that the behavior defined for a task tree hierarchy is fundamentally different for nested unstructured tasks.

Structured tasks

Structured tasks in Swift are represented by async let and task group.

Although it may not be obvious with async let, both of them create child tasks within the parent task where they are used. The child tasks created by async let and task group are designed to be executed concurrently.

async let

With async let, you can start multiple tasks that run concurrently.

func fetchData() async {
    async let first = fetchPart1()
    async let second = fetchPart2()
    async let third = fetchPart3()

    let result = await (first, second, third)

    print(result)
}

Although it is not explicitly stated in code, three new child tasks are created here, one for each async let.

The lifecycle of async let is bound to the local scope where it is created, such as a function, closure, or do/catch block.

TaskGroup

If you need to create a dynamic number of concurrent tasks, a task group is the better choice:

func fetchData(count: Int) async {
    var results = [String]()

    await withTaskGroup(of: String.self) { group in
        for index in 0..<count {
            group.addTask {
                await fetchPart(index)
            }
        }
        for await result in group {
            results.append(result)
        }
    }

    print(results)
}

Important difference with async let is the order of awaiting results. Unlike async let, where the order is code-driven, task group follows a "first finished → first handled" approach, this is how an AsyncSequence works.

Lifecycle of task group is bound to the closure inside withTaskGroup function.

💡: You can find more insights about async lets and task groups here.

Unstructured tasks

Unstructured tasks are usually used as a bridge between sync and async contexts.

If we create some structured child tasks inside of unstructured task, unstructured task will be a root task (node) in the task tree, and parent task for structured tasks.

Unstructured tasks are represented by regular (it is not a common term, we will call it regular just to give it a distinctive name) and detached tasks.

Task { // regular task
    let result = await fetchData()
    print(result)
}
Task.detached { // detached task
    let result = await fetchData()
    print(result)
}

💡: Lifecycle of unstructured tasks does not bound to the local scope or a single closure like async let or task group. When execution leaves local scope unstructured task will simply continue it’s execution.

💡: Unstructured tasks can be nested, but nested task doesn’t have parent/child relation with outer unstructured task. You can think about unstructured task like about initiating new task tree root. It could have no child tasks at all but it is independent from parent/child relation with context where it is created.

⁉️ : What is the difference between regular and detached tasks? When to use each of them?

We’ll discuss this in more detail later, but for now, we can say that a regular task inherits the execution context, while a detached task does not. It's quite hard to think of a specific scenario where a detached task would be useful, so in most cases, using a regular task is the better choice.

Rules of Structured Concurrency

The task tree structure enables cooperative operations, offering features such as priority escalation, which means when setting a higher priority on a child task, the parent task’s priority is automatically escalated.

We can consider some of those features as some kind of structured concurrency rules:

• Error Propagation Rule

• Group Cancellation Rule

• Group Completion Rule

💡 : If you like acronyms for better memorization, you can use EGG 🥚.

We will explore how these rules work within structured concurrency tasks and compare them with the behavior of nested unstructured tasks. You will see that these rules apply to tasks that are part of a single task tree structure, but they do not work for nested unstructured tasks.

Group Completion Rule

👉 Group Completion Rule: In a parent task, you can’t forget to wait for its child tasks to complete. Parent task can’t complete until child tasks are completed.

let parentTask = Task {
    async let first = fetchPart1()  // returns 1
    async let second = fetchPart2() // returns 2
    async let third = fetchPart3()  // returns 3

    let result = await (first, second, third)
    print(result)
}

let result = await parentTask.value
print("parentTask completes")

// Prints:
// (1, 2, 3)
// parentTask completes

Awaiting parentTask’s value means waiting until it completes. "parentTask completes" will not be printed until all child tasks created by async lets are completed first. For task group inside of unstructured parent task, behavior will be the same.

But it doesn’t work the same way for nested unstructured tasks once there are no parent/child relation there:

let rootTask = Task {
    let nestedTask = Task {
        print("nestedTask started")
        try? await Task.sleep(nanoseconds: 10_000_000_000) // 10 secs
        print("nestedTask ended")
    }
}
let result = await rootTask.value
print("rootTask completes")

// Prints:
// rootTask completes
// nestedTask started
// ...after 10 seconds
// nestedTask ended

As you can see in this example, rootTask completes even before nestedTask is started.

But we can achieve the desired behavior if we explicitly await nestedTask inside root task:

let rootTask = Task {
    let nestedTask = Task {
        print("nestedTask started")
        try? await Task.sleep(nanoseconds: 10_000_000_000) // 10 secs
        print("nestedTask ended")
    }
    let result = await nestedTask.value
    print("nestedTask completes")
}
let result = await rootTask.value
print("rootTask completes")

// Prints:
// nestedTask started
// ...after 10 seconds
// nestedTask ended
// nestedTask completes
// rootTask completes

We just need to await both nested and root unstructured tasks.

To sum up:

• async lets will be implicitly awaited when execution leaves the local scope, which allows parent task to complete after that as well, so group completion works as expected. ✅

• Task group will implicitly await the completion of its child tasks when execution exits the task group closure, so parent task could complete after that as well, ensuring that group completion rule works as expected. ✅

• Nested unstructured task, if not awaited, will not cause the external task (rootTask) to wait for its completion. It behaves like a "spawn and forget" mechanism, which means it doesn’t follow the group completion rule. ❌ (which is expected, because it is unstructured and has no parent).

Group Cancellation Rule

👉 Group Cancellation Rule: If parent task is canceled, each of its child tasks is also automatically canceled.

Structured Concurrency promotes us to think about operation cancellation. But we need to understand precisely how it works.

⚠️ : Keep in mind that cancelling the task does not stop the task, it only marks that results are not gonna be needed. Swift concurrency uses a cooperative cancellation model. Each task checks (with Task.isCancelled or Task.checkCancellation()) whether it has been canceled at the appropriate points in its execution, and responds to cancellation appropriately. Depending on what work the task is doing, responding to cancellation usually means one of the following:

• Throwing an error like CancellationError

• Returning nil or an empty collection

• Returning the partially completed work

Let’s consider an example where we have child structured task and parent unstructured task:

func asyncWork() async {
    do {
        /// If current task is canceled before the time ends,
        /// sleep function throws `CancellationError`.
        try await Task.sleep(nanoseconds: 10_000_000_000) // 10 secs
    } catch {
        print("Cancelled as a child task with \\(error)")
        return
    }
    print("Not cancelled -> not child task!")
}

let parentTask = Task {
    async let result = asyncWork()
    await result
}
parentTask.cancel()

// Prints:
// "Cancelled as a child task with CancellationError()" 
// right after parentTask cancellation

Once unstructured task can only be a root task in a task tree, it can’t be cancelled automatically (has no parent). It can be cancelled only explicitly with cancel() method. Doing that will cancel all child structured tasks in the task tree. That means 👉 Group Cancellation Rule works as expected ✅ for structured tasks.

⁉️ : Can we cancel single structured child task without cancelling it’s parent task? To cancel single async lets child task, we have to cancel parent task, which will cancel all child tasks together. For task group we also have an option without parent task cancellation - call group’s cancelAll() method.

But 👉 Group Cancellation Rule doesn’t work ❌ for nested unstructured tasks.

let rootTask = Task {
    Task {
        await asyncWork() 
        // prints "Not cancelled -> not child task!" after 10 seconds
    }
    Task.detached {
        await asyncWork() 
        // prints "Not cancelled -> not child task!" after 10 seconds
    }
}
rootTask.cancel()

Nested unstructured tasks aren’t cancelled when rootTask is cancelled.

We have only explicit cancellation option with cancel method called when rootTask is cancelled:

let rootTask = Task {
    let nestedTask = Task {
        await asyncWork() 
        // prints "Cancelled as a child task with CancellationError()" 
        // right after rootTask cancellation
    }
    if Task.isCancelled {
        nestedTask.cancel()
    }
}
rootTask.cancel()

Error propagation Rule

👉 Error Propagation Rule: If error is propagated outside of local scope, all child tasks are implicitly cancelled and implicitly awaited.

An async function can throw errors by being marked with both the async and throws. Error propagation in Swift refers to the process of passing errors up the call stack, allowing higher-level code to handle or respond to issues that occur during execution.

Let’ check this rule with examples.

When we leave the local scope due to error, async lets and task group child tasks will be implicitly cancelled and implicitly awaited ✅ :

func fast() async throws {
    print("fast started")
    do {
        try await Task.sleep(nanoseconds: 5_000_000_000)
    } catch {
        print("fast cancelled", error)
    }
    print("fast ended")
    throw TestError1() // <- ERROR IS THROWN HERE
}
func slow() async throws {
    print("slow started")
    do {
        try await Task.sleep(nanoseconds: 10_000_000_000)
    } catch {
        print("slow cancelled", error)
    }
    print("slow ended")
    throw TestError2() // <- ERROR IS THROWN HERE
}

func testErrorPropagation() async throws {
    async let f = fast()
    async let s = slow()
    try await (f, s)
    print("leaving local scope") // <- will not be printed
}

//    Prints:
//    slow started
//    fast started
//    fast ended // after 5 secs
//    slow cancelled CancellationError()
//    slow ended
//    external catch TestError1()

After fast throws TestError1, execution leaves the local scope because the error is propagated outside of it. As a result, slow is implicitly cancelled and implicitly awaited.
TestError1 is propagated and caught outside of local scope. TestError2 was not propagated because TestError1 was handled first.

What about error propagation in unstructured tasks?

Throwing an error in unstructured nested task doesn’t cancel other unstructured nested tasks:

let externalTask = Task {
    let nestedTask = Task {
        print("Nested Task 1 started")
        do {
            try await Task.sleep(nanoseconds: 5_000_000_000)
        } catch {
            print("Nested Task 1 cancelled", error)
        }
        print("Nested Task 1 ended")
        throw TestError1()
    }
    let nestedTask2 = Task {
        print("Nested Task 2 started")
        do {
            try await Task.sleep(nanoseconds: 10_000_000_000)
        } catch {
            print("Nested Task 2 cancelled", error)
        }
        print("Nested Task 2 ended")
        throw TestError2()
    }

    try await nestedTask.value
    try await nestedTask2.value
}

do {
    try await externalTask.value
} catch {
    print("Caught error \\(error)")
}

//    Prints:
//    Nested Task 1 started
//    Nested Task 2 started
//    Nested Task 1 ended // after 5 secs
//    Caught error TestError1()
//    Nested Task 2 ended // after 10 secs

As you can see, when we throw TestError1 from nestedTask, error is propagated and get caught outside. nestedTask2 was not cancelled and ended later after that. That means:

👉 Error Propagation Rule doesn’t work ❌ for nested unstructured tasks.

💡: There is another rule that works for both structured and unstructured tasks (including nested) related to error propagation: 👉 Error is propagated from task only if that task is awaited explicitly. No await → no propagation.

In this example, even though error is thrown we will leave the task group closure without error propagated because child tasks are not awaited:

try await withThrowingTaskGroup(of: Void.self) { group in
    group.addTask {
        try await fast() // throws error
    }
    group.addTask {
        try await slow() // throws error
    }

    print("leaving task group closure without error propagated”)
}

Context Inheritance

Even though it’s not the part of defined structured concurrency rules, let’s also discuss how structured and unstructured tasks inherit properties from the context they are created from.

Regular unstructured task inherits:

• Task Priority

  • In an async context, when you create an unstructured task without specifying a priority, it inherits the priority from the current task.

  • In sync context it will use the priority of the thread or queue from which it was called.

      override func viewDidLoad() {
          super.viewDidLoad()
    
          Task {
              print(Task.currentPriority) // Prints `.high`
          }
          Task {
              DispatchQueue.global(priority: .low).async {
                  print(Task.currentPriority) // Prints `.low`
              }
          }
          Task(priority: .background) {
              Task {
                  print(Task.currentPriority) // Prints `.background`
              }
          }
          Task(priority: .background) {
              DispatchQueue.main.async {
                  Task {
                      print(Task.currentPriority) // Prints `.high`
                  }
              }
          }
      }
    

• Task local values

  • Swift lets us attach metadata to a task using task-local values, which are small pieces of information that any code inside a task can read. A task-local value is bound and read in the context of a task. It is implicitly carried with the task, and is accessible by any child tasks it creates. If we create unstructured task, is also inherit it from the task it was created from.

      enum TaskLocalStorage {
          @TaskLocal static var requestID: String?
      }
    
      func checkTaskLocalValue() async {
          await TaskLocalStorage.$requestID.withValue("12345") {
              print("RequestID: \\(TaskLocalStorage.requestID ?? "No Request ID")") 
              // Prints: Request ID: 12345
    
              Task {
                  // Regular unstructured task inherits task-local values.
                  print("Regular unstructured RequestID: \\(TaskLocalStorage.requestID ?? "No Request ID")") 
                  // Prints: Regular unstructured RequestID: 12345
              }
    
              // async let and task group will inherit task local values as well.
              // Only detached task is "detached" from TaskLocalStorage.
    
              Task.detached {
                  // Detached task does not inherit task-local values.
                  print("Detached Task RequestID: \\(TaskLocalStorage.requestID ?? "No Request ID")") 
                  // Prints: Detached Task RequestID: No Request ID
              }
          }
      }
    

• The actor we’re currently running on (if any). Basically it means that we inherit the context’s executor (aka execution context).

Structured task inherits the same as regular task except actor isolation:

⚠️ : Some articles claim that child structured tasks created with async let inherit actor isolation from the context in which they are created. This can be misleading. Structured tasks do not inherit actor isolation from their surrounding context. It wouldn’t make sense because structured tasks are designed to parallelize the work, and inheriting actor isolation would force them to run everything on the same actor (if present), sequentially.

By default, child structured tasks run on the global concurrent executor. However, keep in mind that any async functions you call within these tasks can have their own actor isolation. For async let, once it is assigned with an async function call, it may look like as though it inherits the actor isolation of that function. But again, structured tasks never inherit actor isolation from the context where they are created.

nonisolated func fetchFirst() async -> Int { //... }
@MainActor func fetchSecond() async -> Int async { //... }

async let first = fetchFirst()
async let second = fetchSecond()

// is converted under the hood into something like this:

let first = ChildTask { // global concurrent executor
    await fetchFirst() // global concurrent executor
}
let second = ChildTask { // global concurrent executor
    await fetchSecond() // main executor
}

Detached task inherits nothing. On practice it means that it always runs on the global concurrent executor, so it will run on any thread from cooperative thread pool. But not main thread for sure.

When to use structured and unstructured concurrency?

When to use structured concurrency?

When you need to run multiple concurrent operations at once. But keep in mind it’s “implicit awaiting” behavior: when execution exits this scope — either normally or due to an error — all child tasks will be implicitly awaited.

When to use async let vs task group?

Several factors to consider:

• Amount of tasks: static count for async let, dynamic count for task groups.

• If you have error propagation logic, a task group may be a better choice than async let. The task group’s "first thrown, first caught" logic is more predictable and won’t be affected by the order of awaiting, unlike async let, where error propagation can be influenced by the awaiting order. Task groups are more suitable for cases where you want to "fail fast" compared to async let.

• async let can be easier to use with heterogeneous results and step-by-step initialization patterns.

When to use unstructured concurrency?

• Obviously, use it when you need to switch gears from sync to async context.

• Regular unstructured task might also be used if you want to perform a piece of work independently of the function you’re in, without awaiting. Some “fire-and-forget” style operation that will allow the function to not wait for this task completion.

    func someWorkThatDontWantToWait() async {
        Task {
            await work()
        }
    }
  

• Detached Tasks use case is kind of tricky, because hard to say exactly when you need it:

  • That’s why it’s often referenced as a last resort, when nothing else would suit.

  • Anyway, make sure you really understand why usually it is not needed.

    💡: Usually regular task is enough. Even though it inherits actor isolation, even if you want to avoid it and run some function on global concurrent executor, remember that this function also has it’s own actor isolation context which will define where it will be executed, not the task from where we call it. For example:

    class ViewController: UIViewController { // Main actor isolated
        func someWorkOnMainThread() async {
            Task.detached {
                 await self.asyncMethod()
                 await self.syncMethod()
            }
        }
    
        func asyncMethod() async {
            // called on the main thread
        }
    
        func syncMethod() {
            // called on the main thread
        }
    }
    

    Although we called methods from detached task, it didn’t make them to be called on global concurrent executor. Both method are main actor isolated as methods of ViewController which is main actor isolated.

Finally, for quick reference, keep this the helper table from Apple WWDC session:

For structured tasks lifecycle when local scope is left, this scheme should be useful as well (you can find more info on that matter here):

If you spot any inaccuracies or misleading points in this post, please share them in the comments - your feedback helps everyone!

Good luck on your Swift Concurrency journey! See you in the next article!

You can find video version of this article here.

Hey iOS Folks!

Swift Concurrency (SC) is becoming an integral part of every iOS app project, making a strong understanding of it essential. While WWDC sessions offer valuable insights, they often leave some questions unanswered. If your mental model of SC still feels incomplete, I hope this article helps.

In short, I want you to feel like Buzz Lightyear when working with SC — not like Woody, lost in confusion. We'll take a step-by-step approach to see how each SC concept connects, helping you build a solid understanding of how it all works together.

⚠️ : I assume you are familiar with the basic concepts of Swift Concurrency. If not, you can start here. I will not explain every Swift Concurrency concept in detail. My goal is to show how everything works together and try to provide a full picture.

Let’s start with async functions, as they are the part of Swift Concurrency we most often work with directly.

Async functions

What is an async function? Well, it’s a function with async keyword, obviously. But what does that actually mean? The simplest way to understand an async function is to think of it as a special kind of function that can be suspended during it’s execution (specifics of when and how this suspension occurs aren't as important right now as the fact that it can be suspended).

func asyncWork() async {
    //...
}

It may seem counterintuitive, but ordinary synchronous functions can work as asynchronous functions, but not the other way around. Asynchronous functions can be suspended, but they might not always be. Therefore, the compiler can treat a sync function as an async function that simply never suspends.

The reverse, however, is not allowed. Sync functions are expected to never be suspended, so an async function does not meet these requirements.

For example:

• async method protocol requirement can be implemented ✅ with a sync method.

    protocol SomeProtocol {
        func work() async
    }
  
    struct SomeStruct: SomeProtocol {
        func work() {
            //...
        }
    }
  

• sync method protocol requirement can’t be implemented ❌ with an async method.

    protocol SomeProtocol {
        func work()
    }
  
    // Compiler Error: Type 'SomeStruct' does not conform to protocol 'SomeProtocol'
    struct SomeStruct: SomeProtocol { 
        func work() async {
            //...
        }
    }
  

That gives us the idea that conforming to a "sync function" is a "stronger" (stricter) requirement than conforming to an “async function”. Sync function can work as async function, but not the other way around.

Async functions can be called only from async context.

💡: Basically, being in async context means that we are inside async function (or closure).

When the app starts running, it is in a synchronous(sync) context by default. Most of the code related to the app or UI lifecycle is also executed in a sync context.

⁉️: How we can switch from sync context to async context? Indeed, if we can call async function only from async function or closure, how we can call async function or closure in the first time? We can do it using unstructured concurrency tasks (Task {}), but we will discuss that a bit later.

To call an asynchronous function, we always need to await (asynchronously wait) it. That fact gives us another example of how sync functions are “stronger” than async functions. You can’t call async function without await. But you can call sync function with await (with warning from compiler, of course, once nothing async is happening there) or without await:

await syncFunc() // Warning: No 'async' operations occur within 'await'
asyncFunc()  // Error: Expression is 'async' but is not marked with 'await'

Async → await

Async/await feature allows to write asynchronous functions and call them asynchronously by awaiting them. In result, we can write asynchronous code in a more sequential and readable manner, like we did with sync functions.

func asyncWork() async -> Int {
    //...
}

let result = await asyncWork() // doesn't block the thread execution

But what does it mean to “asynchronously wait” the function call and how this waiting doesn’t block the thread execution?

Do you remember that an async function can be suspended? Well, this happens only when you use the await keyword to await for another async function. When a function encounters await, its execution can be paused until the awaited function call is complete. In other words, await creates a potential suspension point 😴 in your code.

💡: await is only a potential suspension point. It only will be an actual suspension point if execution contexts of caller and callee functions are different. We will come back to it to discuss how it works more deeply a bit later.

Ok, but how it doesn’t block the thread then?

💡: Simply put, a suspended async function gives up its thread to perform other work while it waits for the awaited function to complete.

When an async function reaches an await point that causes suspension, a continuation is created - a snapshot of the current execution state that can resumed later. This frees up the thread for other tasks. Instead of blocking threads, continuations allow execution to switch between tasks efficiently, incurring only the cost of a function call rather than a full thread context switch.

What is continuation?

The continuation is a snapshot of async function execution state (return address, params, local vars, etc.). In other words, continuation remembers the point in the caller function where execution should resume after the awaited operation is completed. When a suspended function is ready to resume, the runtime can pick up the continuation and continue execution, potentially on a different thread. At runtime, continuation is represented by the list of async frames stored on the heap.

💡: We're not diving too deep here, but I recommend to watch WWDC2021 - Swift concurrency: Behind the scenes (since 14:26) session to understand how the async frames work.

⁉️: Why the heap is needed? Because continuation can potentially be picked up by a thread different from the original thread where the async function was awaited, there is a necessity for the continuation state to be shared across different threads. Therefore, it cannot be bound to the call stack of a single thread.

Tasks

We already mentioned that to switch from sync to async context, we need to create an unstructured concurrency Task:

Task {
    await callAsyncFunc()
}

However, that is not the only use case for tasks. Tasks are, in fact, a much broader concept in Swift Concurrency.

💡: Tasks are units of asynchronous work you can run from your code.

• Every async function is executing in a task. In other words, a task is to asynchronous functions, what a thread is to synchronous functions.

• A task runs one function at a time; a single task has no concurrency.

• Synchronous functions do not necessarily run as part of a task, but they can.

💡: Here you can find more insights.

⁉️: How tasks can be created?

• Explicitly with Task {} and Task.detached {}.

• Implicitly by async let and task group (they are gonna be child tasks).

⁉️: Is the task created when an await with suspension point 😴 occurs? No, even if it is an actual suspension point.

• When a function makes an async call, the called function is still running as part of the same task.

• Similarly, when a function returns from an async call, the caller resumes running on the same task.

A task can be in one of three states:

• 🔴 A suspended task has more work to do but is not currently running (initial state).

  • It may be schedulable, meaning that it’s ready to run and is just waiting for the system to instruct a thread to begin executing it.

  • or it may be waiting on some external event before it can become schedulable.

• 🟡 A running task is currently running on a thread.

  • It will run until it either completes or reaches an actual suspension point 😴 (and becomes suspended again). A task's state can change between running and suspended multiple times during its lifecycle.

• 🟢 A completed task has no more work to do and will never enter any other state.

  • Code can wait for a task to become completed by awaiting on it.

💡: Do you remember that async functions can be suspended at potential suspension points with await? Well, what actually gets suspended is the task in which the async function is executing. Of course, the async function itself is also suspended since it's part of the task, but it's important to highlight that the task is what's truly being “paused”.

⁉️ : Are we already inside some task when app starts? No, you can check it from any viewDidLoad or AppDelegate :

func checkIfInsideTask() -> Bool {
    withUnsafeCurrentTask { $0 != nil }
}

Again, by default, app runs in synchronous world, so you need to create a task to switch the gears from sync to async.

Jobs

Task are units of async work but not the most basic ones. Tasks consists of the jobs, even more smaller units of asynchronous work. Jobs are the basic units of schedulable synchronous work that occurs between suspension points within a Task. When a Task suspends (for instance, while waiting for an async function to complete), the next job will be scheduled for later execution.

Let’s consider an example:

Task {
    beforeWork()
    await asyncWork()
    afterWork()
}

Every async call with await can be thought of as splitting the code into three different parts:

• job before the suspension point;

• job that resumes after the suspension point;

• job (or jobs) that will be created based on asyncWork structure (asyncWork can have more awaits inside of it).

⚠️ : This isn't documented, so I could be wrong in some details, but this is how I understood it from this Swift forum thread. Let me know in the comments if you have more details.

💡: Simply put, you can think of it as breaking up an async function into synchronous chunks, each of which is a job.

Developers usually don’t work with the jobs directly. Jobs are created by runtime. But their structure is defined at compiling the awaits structure. The compiler generates code for async functions, including how they suspend, resume, and manage continuations. This precompiled structure tells the runtime how to create jobs when needed, but actual job instances are created at runtime when suspension occur.

💡: Single task has no concurrency, meaning the jobs within a single task also have no concurrency with each other. They wait for the previous job to complete before starting. Jobs are designed to be executed sequentially, one after another, with the possibility of the task being suspended if the next job needs to be executed on a thread that is currently busy.

💡: Jobs defined as synchronous which means there are no await’s inside of a job.

Actors

Tasks and jobs can perform work concurrently, which is great. However, when multiple tasks need to access or modify the same shared data, there’s a risk of data races, which can lead to unpredictable behavior. This is where actors come into play. Actors allow you to isolate async function calls to safely share their (actor’s) state with other concurrent tasks or threads. This ensures that the mutable state within the actor is accessed in a thread-safe manner, preventing race conditions and data corruption.

💡: Metaphorically, if a task were a car, an actor would be a garage — only one car can park in the garage at a time. A car can park in a garage, but car doesn’t own it.

You probably already familiar with actors from other articles, but we will consider one simple example to refresh it quickly:

actor SomeActor {
    let immutableState = 1

    var mutableState = 2

    func updateState(_ newValue: Int) {
        mutableState = newValue
    }
}

let actor = SomeActor()

print(actor.immutableState) // accessed without await in sync context

Task.detached {
    await print(actor.mutableState) // accessed mutable state from async context

    actor.mutableState = 3 // Compilation Error: Actor-isolated property 
    // 'mutableState' can not be mutated from a nonisolated context

    await actor.updateState(3) // can be mutated with actor method
}

Main takeaways from example:

• Actors allow only one async func (~task) to access their mutable state at a time (it will happen asynchronously), which makes it safe for code in multiple tasks to interact with.

• Immutable state can be accessed synchronously. Yes, you can I access actor’s immutable state from sync context without using await.

• Mutable state can be accessed only from async context with await.

• You can change the mutable state only with actor own methods.

Executors

Executor is a special service which accepts the enqueued jobs and arranges some thread to run them. Once job is enqueued to some executor, it will be fully completed there. Executors manage job priorities, ensuring that high-priority tasks are executed before lower-priority ones. For the most part, ios engineers will not have to work directly with executors or jobs unless they are implementing a custom executor, which is probably not very common.

Jobs were defined as schedulable but what does it actually mean?

Swift doesn’t expose an explicit "scheduler" object, meaning the runtime implicitly acts as one. Scheduling involves the runtime enqueueing jobs to the appropriate executor based on the "context" — essentially, the code itself. From the code, we can determine which executor should handle a job. The code also defines the job structure, so each job has a designated target executor. This will become clearer when we discuss different types of executors later.

💡: Later, when we use execution context, we will mean the executor and vice versa.

Executor is also the key concept to understand when potential suspension point becomes actual suspension point 😴.

When async function calls another async function with the same target executor, it continues running without suspension, there is no actual suspension point. It becomes an actual suspension point if the caller and callee should run on different executors, and the runtime switches the execution contexts (hops to another executor) to execute the async function.

When awaited async function call completes, caller function always continues it’s execution on the same executor as it was before the async call:

func exampleFunc() async {
  // hop to executor of firstFunc
  await firstFunc()
  // hop to executor of exampleFunc

  syncWork()

  // hop to executor of secondFunc
  await secondFunc()
  // hop to executor of exampleFunc

  syncWork2()
}

Executors run jobs using threads, but they don’t create or own threads. Instead, they borrow threads from the Cooperative Thread Pool (CTP).

Cooperative Thread Pool

Before Swift Concurrency, we mostly built the concurrency in our apps with Dispatch queues (Grand Central Dispatch aka GCD aka libdispatch) and OperationQueue (which is basically object oriented wrapper around GCD).

Dispatch queues can be either serial or concurrent. Like Executors in Swift Concurrency, they execute submitted work on a system-managed thread pool.

We also had a special queue - Main Queue - that executes code only on the Main Thread.

GCD with queues is a powerful approach, but it can cause issues at scale. GCD schedules tasks onto its threads using a preemptive model. (Keep in mind that a GCD task differs from a Swift Concurrency Task. A GCD task is essentially a closure — a block of code that can be queued and executed later). If too many tasks are queued concurrently, GCD may create new threads as needed. This can overload CPU resources because GCD doesn’t strictly limit the number of active threads to the available CPU cores. This situation, known as a thread explosion, occurs when an app spawns too many threads, often leading to performance degradation, resource exhaustion, or even crashes.

Swift Concurrency introduced the Cooperative Thread Pool (CTP) - a shared pool of threads. While thread pools are not new to GCD, CTP was a new feature added specifically for Swift Concurrency (so SC relies on GCD under the hood). Unlike previous dynamic thread pool, CTP uses a fixed number of threads, limited to the number of CPU cores (e.g., six threads for a six-core iPhone 16 Pro).

You can recognize CTP threads by “cooperative (concurrent)" label there. As you can see, there are also other threads outside CTP doing something there at the same time.

💡: Limiting CTP thread count to CPU cores count allows to avoid thread explosion and scheduling threads overhead of context switching (switching CPU core between threads is expensive operation).

⁉️: Why does it match the thread count to the CPU core count? Isn’t the main thread always there? Why not make it N-1 once the main thread is handling UI updates? The main thread doesn’t necessarily always have work to do. As I mentioned in my article on UI under the hood, the run loop on the main thread puts it into sleep after each iteration if there’s no work to do. When there’s no work for the main thread, it’s better to use the CPU core it was using. That why in SC, I guess, it matches the thread count to the core count - for better performance. It doesn't completely disable thread context switching, but aims to minimize it and keep performance optimal.

In Swift Concurrency, we also continue to use Main thread (and main queue) which is not the part of CTP.

💡: All tasks managed by SC are executed either on the CTP or Main Thread.

💡: SC removes our ability to create or manage threads directly and encourages us to focus on executors and actor isolation instead. When running code with SC, we no longer think about which thread it should run on. Instead, we focus on how it should be executed in terms of actor isolation, which basically means - which type of executor will handle the task.

Types of executors

Before combining all the concepts we've covered so far, we need to understand the different types of executors that exist. Once we already know the roles of actors, the Cooperative Thread Pool (CTP), and the main thread in Swift Concurrency, we can explain how they all connect to executors.

There are 3 types of executors that we need to know about:

• Default concurrent executor

• Serial executor

• Main executor

Default concurrent executor

It’s a default executor and it’s concurrent, obviously.

“Default” means that all non-actor-isolated jobs are executed on this executor by default. Jobs executions happens using threads from Cooperative Thread Pool.

“Concurrent” means that it can execute jobs from different tasks concurrently, using multiple threads from CTP (if needed and if they are available).

Serial executor

Special executor type for actor isolated jobs. Every actor you write in your code in Swift Concurrency has its own serial executor. Serial executor runs jobs on the Cooperative Thread Pool too, but it reserves a single thread from the pool to do it. (This thread can vary at different moments for the same actor, but during any particular job, it remains the same). "Serial" means executing jobs one after another, sequentially, one at a time.

⚠️ : But don’t be misled by the “serial” part of the name of serial executor. Actors are not like serial queues because of reentrancy.

💡: When we say actor context (aka actor executor or actor isolation) it basically means that execution context aka executor of that actor.

Main executor

Special executor that handles main actor isolated jobs and represents the main thread.

Executes jobs on Main thread (technically they simply go to Main Dispatch Queue).

We can visualize how a job is mapped to its executor:

Executors and Threads

Worth to mention that even though execution context after await always remains same as before await, it doesn’t mean that thread will remain the same in this case. At least in most cases.

• For tasks that are not actor-isolated, the continuation will run on the global concurrent executor (i.e., the cooperative thread pool). However, the thread may differ before and after the continuation, although it will certainly not be the main thread.

    Task.detached {
        // global concurrent executor, some thread from CTP
        someSyncFunction()
  
        await someAsyncFunction() // executor of someAsyncFunction
  
        // still global concurrent executor, maybe different thread from CTP
        someSyncFunction()
    }
  

• For some actor (not main one) - continuation will run on the same serial actor executor but thread can be different from original one that was executing the task before suspension point.

    actor SomeActor {
        @MainActor
        func someAsyncFunction() async {}
  
        func someSyncFunction() {}
  
        func someMethod() async {
            // same actor executor, some thread from CTP
            someSyncFunction()
  
            await someAsyncFunction() // executor of someAsyncFunction (main executor)
  
            // same actor executor, maybe different thread from CTP
            someSyncFunction()
        }
    }
  

• But main actor is special - continuation will run on the main actor and main thread as well for both before and after suspension point.

    Task { @MainActor in
        // main actor executor, main thread
        someSyncFunction()
  
        await someAsyncFunction() // executor of someAsyncFunction
  
        // main actor executor, main thread
        someSyncFunction()
    }
  

Recap for Full Picture

Let’s go bottom-up and summarise everything once again.

Cores and Threads

In Swift Concurrency, to avoid thread explosion and for optimal parallel performance, threads live in Cooperative Thread Pool and threads count is limited to CPU cores number.

Main thread is not the part of Cooperative Thread Pool.

Executors

Executor is a service that executes jobs. All executors except main executor borrow threads from CTP.

Main executor uses main queue for main actor isolated jobs/tasks.

Serial executor is a special executor type for actors to do actor isolated jobs/tasks (except main actor of course).

All other jobs goes to default concurrent executor.

Tasks

Tasks are units of asynchronous work you can run from your code. Tasks serve as a bridge between sync and async contexts. Tasks consist of the jobs.

Jobs

Jobs are the basic units of schedulable synchronous work that occurs between suspension points within a Task. Every job has it’s target executor based on it’s actor isolation. Actors allow us to isolate jobs in the tasks to safely share their state with other tasks. Code inside task is separated into jobs based on the structure of awaits for async function inside of it (which are potential suspension points). Jobs are created by runtime. But their structure is defined at compiling the awaits structure of async functions calls.

Async/await

Async function is special function that can be suspended while awaiting another async function to complete. Suspension point is the point in an async function where execution can be paused while another async function call is awaited and resumed later with continuation. The continuation is a snapshot of async function execution state that can be resumed later.

Full scheme:

Final thoughts

Swift concurrency is a powerful tool that eliminates callback hell, offers a cleaner syntax, and reduces concerns like forgotten completion handlers. Its focus on readability, error handling and data-race safety makes it a significant step forward. However, it comes with a steep learning curve. Compared to GCD, which was simpler to grasp initially but exposed its limitations as complexity grew, Swift concurrency demands more effort upfront.

If you interested to know more about Swift Concurrency internals, I recommend this article for reading as well.

Swift concurrency requires time and practice to fully understand. Be patient and prepared, as reading articles alone probably won’t be enough - you’ll need hands-on experience, trial and error, and, yes, a few “grabbles” along the way.

If you spot any inaccuracies or misleading points in this article, please share them in the comments - your feedback helps everyone!

See you in the next article!

In Swift, Structured Concurrency tasks are represented by async let and task groups. While both serve the same purpose, their lifecycles work slightly differently. Today, we'll explore these differences with examples.

⚠️ : I assume you are familiar with the basic concepts of Swift Concurrency. If not, you can start here.

async let

With async let, you can start multiple tasks that run concurrently.

func fetchData() async {
    async let first = fetchPart1()
    async let second = fetchPart2()
    async let third = fetchPart3()

    let result = await (first, second, third)

    print(result)
}

Although it is not explicitly stated in code, three new child tasks were created here, one for each async let.

async let can work with both sync and async functions:

func fetchPart1() -> Int { ... }
func fetchPart2() async -> Int { ... }

Moreover, it actually works with any expression:

async let number = 123
async let str = "Hello World!"

⁉️ : How it works? Under the hood, it wraps the initializer expression in a separate, concurrently executing child task. The child task starts running as soon as the async let is encountered, using the default concurrent executor.

async let first = fetchPart1()
async let second = fetchPart2()
async let number = 123
async let str = "Hello World!"

// is converted into something like this:

let first = ChildTask {
    fetchPart1()
}
let second = ChildTask {
    await fetchPart2()
}
let number = ChildTask {
    123
}
let str = ChildTask {
    "Hello World!"
}

The lifecycle of async let is bound to the local scope where it is created, such as a function, closure, or do/catch block. When execution exits this scope — either normally or due to an error — all tasks created with async let will be implicitly cancelled and awaited.

⚠️ : Even if you don’t explicitly await an async let, it will be awaited at the end of the local scope. This means an async let group always runs as long as its longest-running child task.

⚠️ : Keep in mind that cancelling the task does not stop the task, it only marks that results are not gonna be needed. Swift concurrency uses a cooperative cancellation model. Each task checks whether it has been canceled at the appropriate points in its execution (with Task.isCancelled or Task.checkCancellation()), and responds to cancellation appropriately. Depending on what work the task is doing, responding to cancellation usually means one of the following:

• Throwing an error like CancellationError

• Returning nil or an empty collection

• Returning the partially completed work

Another important point to highlight can be observed here:

async let result1 = task1()
async let result2 = task2()

let results = await (result1, result2)

Pay close attention - it may not be immediately obvious, but while child tasks created with async let run concurrently, awaiting them in a tuple is sequential. Swift evaluates tuple elements from left to right, following its expression evaluation rules.

To clarify, all the expressions below are equivalent in terms of the order of sequential awaiting each result:

await (result1, result2)
// or
(await result1, await result2)
// or
await result1
await result2
// awaiting order will be the same

This can lead to a tricky behavior when child tasks throw errors, but we will discuss that later in the error propagation edge cases section.

💡: I would like to encourage you to read async let proposal for more insights, such as why async var is not allowed or why passing an async let to an escaping closure is prohibited.

TaskGroup

If you need to create a dynamic number of concurrent tasks, a task group is the better choice:

func fetchData(count: Int) async {
    var results = [String]()

    await withTaskGroup(of: String.self) { group in
        for index in 0..<count {
            group.addTask {
                await self.fetchPart(index)
            }
        }
        for await result in group {
            results.append(result)
        }
    }

    print(results)
}

Keep in mind that group: TaskGroup param inside task group closure is actually AsyncSequence. So instead of for await we can use another iterator approach with .next() method that produces the same result:

while let result = await group.next() {
    results.append(result)
}

Lifecycle of task group is bound to the closure inside withTaskGroup function. But logic is a bit more complex than with async let:

• If execution leaves the closure normally without awaiting child tasks, they will be implicitly awaited (but not cancelled).

• If execution leaves the closure due to an error, child tasks will be both implicitly cancelled and awaited.

For example, if we remove the for await part from the task group code above, it won’t just go to printing the results (which would be empty, obviously). Instead, it will await all child tasks first until the each of them is fully completed.

💡 : An important difference from async let is the order in which results are awaited. Unlike async let, where the order is code-driven, a task group follows a "first finished → first handled" approach, based on how an AsyncSequence works.

Lifecycle edge cases

We briefly covered the lifecycle logic for implicit cancellation and awaiting of structured tasks.

The lifecycle of async let is bound to the local scope where it is created, such as a function, closure, or do/catch block. When execution exits this scope — either normally or due to an error — all tasks created with async let will be implicitly cancelled and awaited.

Lifecycle of task group is bound to the closure inside withTaskGroup function. But logic is a bit more complex than with async let:

• If execution leaves the closure normally without awaiting child tasks, they will be implicitly awaited (but not cancelled).

• If execution leaves the closure due to an error, child tasks will be both implicitly cancelled and awaited.

It may seem a bit complicated already, so let’s try to clarify that with examples.

⚠️ Disclaimer: Not awaiting structured tasks may not be a good idea in some cases. Even if you want to create parallel "fire and forget" operations without caring about the results, structured tasks might not work as you expected. Remember that both async let and task groups have implicit awaiting, meaning you'll always wait for the longest child task to complete before proceeding. This makes true "fire and forget" behavior impossible unless you wrap the tasks in an unstructured root task or simply use an unstructured tasks instead.

What if we don’t await child tasks and leave the local scope normally?

async let

When we we leave local scope normally without awaiting child tasks, async let’s child tasks will be implicitly cancelled and implicitly awaited:

func fast() async {
    print("fast started")
    do {
        /// If current task is canceled before the time ends,
        /// Task.sleep function throws `CancellationError`.
        try await Task.sleep(nanoseconds: 5_000_000_000)
    } catch {
        print("fast cancelled", error)
    }
    print("fast ended")
}

func slow() async {
    print("slow started")
    do {
        try await Task.sleep(nanoseconds: 10_000_000_000)
    } catch {
        print("slow cancelled", error)
    }
    print("slow ended")
}

func go() async {
    async let f = fast()
    async let s = slow()

    print("leaving local scope")
}

//    Prints:
//    leaving local scope
//    fast started
//    slow started
//    slow cancelled CancellationError()
//    slow ended
//    fast cancelled CancellationError()
//    fast ended

Keep in mind that it will implicitly cancel and await tasks in reverse order, starting from the last defined async let child task. In this example, it implicitly cancels and awaits the slow task first, and then the fast task will also be implicitly cancelled and awaited.

If your last defined async let task will take long time to finish and will not handle cancellation properly, previous ones will not be cancelled until first one is completed, which will affect total group completion time. For example, if we make slow one “more slower” and ignore cancellation for it:

func slow() async {
    print("slow started")
    do {
        try await Task.sleep(nanoseconds: 10_000_000_000)
    } catch {
        print("slow cancelled", error)
    }
    sleep(10) // this sleep will ignore cancellation
    print("slow ended")
}

// fast and go funcs are the same

//    Prints:
//    leaving local scope
//    fast started
//    slow started
//    slow cancelled CancellationError()
//    fast ended // after 5 secs
//    slow ended // after 10 sec

As you can see, this time fast wasn’t even cancelled this time, because it managed to complete before slow is completed (slow was implicitly cancelled and implicitly awaited).

Task group

When we leave Task group closure normally without awaiting child tasks, task group’s child tasks will be implicitly awaited but not cancelled:

await withTaskGroup(of: Void.self) { group in
    group.addTask {
        await fast()
    }
    group.addTask {
        await slow()
    }

    print("leaving task group closure")
}

// fast and slow funcs are the same

//    Prints:
//    leaving task group closure
//    fast started
//    slow started
//    fast ended // after 5 sec
//    slow ended // after 20 sec

What if we do not await and leave the local scope due to error?

💡: Remember, that if child task is not awaited explicitly, throwing an error inside child task will not be propagated and caught outside (Rule: not awaited explicitly → not propagated). Task group will only implicitly await it’s child tasks in this case (no implicit cancellation) as it did in previous case without error.

If we don’t await child tasks but error is somehow thrown inside async let’s local scope or Task group’s closure and it leaves the scope/closure uncaught, child tasks will be implicitly cancelled and implicitly awaited, and after that error will be propagated outside:

try await withThrowingTaskGroup(of: Void.self) { group in
    group.addTask {
        try await fast()
    }
    group.addTask {
        try await slow()
    }

    print("leaving task group closure")
    throw TestError()
}

//    Prints:
//    leaving task group closure
//    fast started
//    fast cancelled CancellationError()
//    fast ended
//    slow started
//    slow cancelled CancellationError()
//    slow ended
//    external catch TestError() // error caught outside task group closure

Opposite to async let where the implicit cancellation + awaiting happens in order opposite to async let’s declaration, for task group:

• there is not defined order for cancellation and awaiting (random order)

• it implicitly cancels all child tasks first, then implicitly awaits all of them.

We can check that in this example:

func fast() async throws {
    print("fast started")
    do {
        try await Task.sleep(nanoseconds: 5_000_000_000)
    } catch {
        print("fast cancelled", error)
    }
    sleep(5) // this sleep will ignore cancellation
    print("fast ended")
}

func slow() async throws {
    print("slow started")
    do {
        try await Task.sleep(nanoseconds: 10_000_000_000)
    } catch {
        print("slow cancelled", error)
    }
    sleep(10) // this sleep will ignore cancellation
    print("slow ended")
}

// code of withThrowingTaskGroup is the same as previous

//    Prints:
//    leaving task group closure
//    slow started
//    fast started
//    fast cancelled CancellationError()
//    slow cancelled CancellationError()
//    fast ended // after 5 seconds
//    slow ended // after 10 seconds
//    external catch TestError() // error caught outside task group closure

As you can see, it implicitly cancels both fast and slow first, then awaits fast and slow after that.

What if we await child tasks and error is handled locally?

async let

async let’s child tasks will be implicitly cancelled and implicitly awaited.

Let’s say we throw an error in fast and slow now:

func fast() async throws {
    print("fast started")
    do {
        try await Task.sleep(nanoseconds: 5_000_000_000)
    } catch {
        print("fast cancelled", error)
    }
    print("fast ended")
    throw TestError1() // <- HERE
}
func slow() async throws {
    print("slow started")
    do {
        try await Task.sleep(nanoseconds: 10_000_000_000)
    } catch {
        print("slow cancelled", error)
    }
    print("slow ended")
    throw TestError2() // <- HERE
}

async let f = fast()
async let s = slow()
do {
    try await (f, s)
} catch {
    print("caught error locally", error)
}
print("leaving local scope")

//    Prints:
//    fast started
//    slow started
//    fast ended // after 5 seconds
//    caught error locally TestError1()
//    leaving local scope
//    slow cancelled CancellationError()
//    slow ended

See how TestError2 from slow wasn’t even caught because of await order for async let’s (we await fast first and slow second). We caught TestError1 and left do block, leaving slow unawaited, so it was implicitly cancelled and awaited after we left the local scope.

Order of implicit cancellation + awaiting is the same as before for async let - reversed to async let declaration order.

Keep in mind that the order of awaiting can directly affect the order of error propagation. If we await the slow task first, TestError2 will be propagated, even though the fast task ended first and threw an error first — it was never caught because fast was never awaited on practice:

try await (s, f) // changed the order of awaits

//    Prints:
//    fast started
//    slow started
//    fast ended // after 5 seconds
//    slow ended // after 10 seconds
//    caught error locally TestError2()
//    leaving local scope

Task group

Task group’s child tasks will be implicitly awaited but not cancelled.

Let’s say again that we throw an error in fast and slow :

try await withThrowingTaskGroup(of: Void.self) { group in
    group.addTask {
        try await fast()
    }
    group.addTask {
        try await slow()
    }
    do {
        for try await result in group {
            print("Received: \(result)")
        }
    } catch {
        print("caught error locally", error)
    }
    print("leaving task group closure")
}

// fast and slow are the same as in previous example

//    Prints:
//    fast started
//    slow started
//    fast ended // after 5 secs
//    caught error locally TestError1()
//    leaving task group closure
//    slow ended // after 10 secs

When fast throws TestError1, we catch it locally and after we leave the task group closure, slow is implicitly awaited. Even though slow throws TestError2 error eventually, we didn’t catch it (because it is not awaited anymore → not propagated).

What if we await child tasks and error is propagated outside local scope?

async let

async let’s child tasks are implicitly cancelled and implicitly awaited.

Let’s remove local do/catch block to test that case:

async let f = fast()
async let s = slow()
try await (f, s)
print("leaving local scope")

// fast and slow are the same as in previous example

//    Prints:
//    slow started
//    fast started
//    fast ended // after 5 secs
//    slow cancelled CancellationError()
//    slow ended
//    extenral catch TestError1()

After fast throws TestError1 , execution jumps to external catch block and leaves slow unawaited. slow is implicitly cancelled and implicitly awaited. TestError1 is propagated and caught outside of the local scope.

Task group

task group’s child tasks are implicitly cancelled and implicitly awaited.

Let’s remove local do/catch block to test that case as well:

try await withThrowingTaskGroup(of: Void.self) { group in
    group.addTask {
        try await fast()
    }
    group.addTask {
        try await slow()
    }
    for try await result in group { // Removed do/catch here
        print("Received: \\(result)")
    }
    print("leaving task group closure")
}

// fast and slow are the same as in previous example

//    Prints:
//    slow started
//    fast started
//    fast ended // after 5 secs
//    slow cancelled CancellationError()
//    slow ended
//    external catch TestError1()

After fast throws TestError1 , execution jumps to external catch block and leaves slow unawaited. slow is implicitly cancelled and awaited. TestError1 is propagated and caught outside of task group closure.

Conclusion

⚠️ : If you have error propagation logic, a task group may be a better choice than async let. The task group’s "first thrown, first caught" logic is more predictable and won’t be affected by the order of awaiting, unlike async let, where error propagation can be influenced by the awaiting order. Task groups are more suitable for cases where you want to "fail fast" compared to async let.

As you could notice, there were quite a few cases to consider. Hopefully, your brain isn’t boiling just yet. Luckily, the logic behind these cases is simpler than it may seem. To make it more visual and easier to understand, we can build a diagram:

If you spot any inaccuracies or misleading points in this post, please share them in the comments - your feedback helps everyone!

Good luck on your Swift Concurrency journey! See you in the next articles!

Hey iOS folks,

With the release of iOS 18, many teams are likely moving towards adopting iOS 16 as the new minimum, bringing newer SwiftUI features, such as NavigationStack, into focus. Opinions on SwiftUI navigation in general are quite mixed. Some developers have embraced it and advocate for it, while others argue that even with NavigationStack, SwiftUI’s navigation system isn't fully ready for large-scale apps.

Many teams, including mine, use SwiftUI for building UI but still rely on UIKit’s navigation by wrapping SwiftUI views into UIHostingController .

In this article, I aim to explore whether SwiftUI, particularly NavigationStack, can be used with the Coordinator approach, how it can be adapted to SwiftUI, and how to build a SwiftUI-based Coordinator with minimal code - without relying on complex third-party libraries.

We will revisit what the Coordinator pattern is, explore how it can be implemented with both UIKit and SwiftUI, and compare the two implementations while discussing their limitations.

What is coordinator?

Like many great concepts in software design, the Coordinator pattern is quite straightforward.

Simply put, a Coordinator is an object that manages the navigation flow.

What is the navigation flow?

In simple terms, it's the sequence of screens in an app, connected by transitions.

These transitions can vary - it can be pushing, presenting, or even custom transitions, depending on your needs.

What does it mean to manage the navigation flow?

It means having full control over navigation flow through the app. Not only can we push new screens when buttons are tapped by user, but we can also change the flow state programmatically based on events happening outside the current screen.

What are the benefits of using a Coordinator?

Instead of letting views (and view controllers) handle navigation directly, the Coordinator takes over.

By decoupling navigation logic from views, we reduce dependencies between views, making it easier to maintain, control, test and reuse. Since we control the state of the navigation flow, handling complex scenarios - even programmatically - becomes straightforward.

Coordinators scale exceptionally well. You can nest them, allowing sub-coordinators to create hierarchies within the navigation flow, organizing it into a tree structure that simplifies scaling. This approach fits neatly into modular design. If you're following a modular architecture with feature modules, you can easily integrate a feature-specific Coordinator from the composition root.

Router vs. Coordinator

You might be wondering: "We already use the Router pattern in our project - so what's the difference?"

Both the Router and Coordinator handle navigation, obviously.

A Router’s scope can vary depending on how a team defines it. In my experience, a Router typically manages the navigation routes for a single screen, as seen in patterns like MVVM-R (Model-View-ViewModel-Router) or VIPER. In some cases, a Router might handle the flow of multiple screens or even manage the entire app’s navigation - though this is more common in smaller projects and not a widely adopted approach.

A Coordinator, on the other hand, typically controls the flow of the screens, not just individual screen routes. While it’s possible for a Coordinator to manage just one screen in certain cases, its main strength lies in controlling the navigation for a set of related screens like an some feature flow.

Another difference is that coordinators usually have a hierarchical structure: Coordinators can be nested, with parent Coordinators managing child Coordinators, allowing for complex tree-like flows across the app.

Hopefully, this gives you a clearer understanding of Coordinators. Next, we can explore examples of how to implement them in UIKit and SwiftUI.

Plain Old UIKit Coordinator

First, let’s define the coordinator type:

protocol Coordinator: CoordinatorFinishDelegate {
    func start() // 1
    func finish() // 2
    var finishDelegate: CoordinatorFinishDelegate? { get set } // 3
}

1. start() : This method starts the coordinator flow. It provides the flexibility to create a coordinator and activate it only when we’re ready if we need so.

2. finish() : This method is called to end the flow, such as dismissing the screen flow.

3. When a coordinator finishes, there needs to be a mechanism to notify the parent coordinator so that it can remove the child coordinator from its list or perform additional tasks. Typically, the finishDelegate is the parent coordinator. To follow the principle of least privilege, we avoid giving the child direct access to control the parent. Instead, we hide the parent behind a CoordinatorFinishDelegate protocol.

protocol CoordinatorFinishDelegate: AnyObject {
    func didFinish(childCoordinator: Coordinator)
}

NOTE: By using a start() method, we separate coordinator initialization from activation. There are several reasons for this:

1. Separation of Concerns: Instantiation and execution are conceptually different -initialization creates the object, while start() triggers the flow. This separation makes the code easier to understand and maintain, as the responsibilities of creation and execution are clearly decoupled.

2. Deferred Execution: This approach allows for deferred execution of the navigation flow, which can be useful in certain scenarios where immediate navigation isn't desired.

3. Dependency Injection: Coordinators often need dependencies like services, data, or other coordinator before starting their flow. An explicit start() method provides the flexibility to inject these dependencies before navigation begins.

4. Multiple Entry Points: In some cases, a coordinator might have multiple entry points depending on the context. Instead of complicating the initialization logic, having different start() methods allows for more straightforward handling of different use cases.

Next we need to define how coordinators will work with child coordinators:

protocol FlowCoordinator: Coordinator {
    var childCoordinator: Coordinator? { get set }
}

protocol CompositionCoordinator: Coordinator {
    var childCoordinators: [Coordinator] { get set }
}

FlowCoordinator is designed for typical navigation processes involving push and present actions. It follows a linear flow and therefore has only one childCoordinator.

CompositionCoordinator, on the other hand, manages multiple child coordinators. An example would be a TabBarCoordinator, which acts as a CompositionCoordinator for each tab's coordinator.

But why don’t we include a childCoordinators array in the base coordinator protocol? It's a reasonable question. While we could add a childCoordinators array to the base Coordinator protocol - something many implementations do - it's better to adhere to the YAGNI (You Aren't Gonna Need It) and Interface Segregation principles here. As you'll see shortly, this approach simplifies the implementation.

NOTE: In some Coordinator implementations, you may find a UINavigationController defined in the coordinator protocol. Adding it allows you to create default methods in a protocol extension for common navigation tasks, such as push, present, popToRoot, or dismissToRoot, which can then be reused throughout your project. While this approach adds some complexity, it also makes the solution more ready for universal flows. However, including UINavigationController in the protocol is optional, and there are several reasons why avoiding it can be beneficial:

1. Framework Independence: The Coordinator concept is independent of UIKit, so keeping the coordinator protocol free from framework-specific details helps maintain a cleaner architecture.

2. Flexibility: Without restricting the coordinator to UINavigationController, you have the freedom to use other containers for views, such as UIViewController, UITabBarController, or even UIWindow, depending on the specific requirements of the flow.

NOTE: We can also add default implementations to protocol extensions for finish, child coordinators manipulation and etc.

extension Coordinator {
    func finish() {
        finishDelegate?.didFinish(childCoordinator: self)
    }
}

extension FlowCoordinator {

    func addChild(_ coordinator: Coordinator) {
        childCoordinator = coordinator
        coordinator.finishDelegate = self
    }

    func removeChild() {
        childCoordinator = nil
    }

    func didFinish(childCoordinator: Coordinator) {
        removeChild()
    }
}

For specific screen flow like a feature flow, coordinator will look like this:

final class FeatureCoordinator: FlowCoordinator {

    weak var finishDelegate: (any CoordinatorFinishDelegate)?

    var childCoordinator: Coordinator?

    private let navigationController: UINavigationController

    init(navigationController: UINavigationController) {
        navigationController = navigationController
    }

    func start() {
        let rootScreen = FirstTabScreen(coordinator: self)
        let vc = UIHostingController(rootView: rootScreen)
        navigationController.setViewControllers([vc], animated: false)
    }

    func pushNextScreen(animated: Bool = true) {
        let nextScreen = NextScreen(coordinator: self)
        let vc = UIHostingController(rootView: nextScreen)
        navigationController.pushViewController(vc, animated: animated)
    }

    func presentAnotherScreen(animated: Bool = true) {
        let anotherScreen = AnotherScreen(coordinator: self)
        let vc = UIHostingController(rootView: anotherScreen)
        navigationController.present(vc, animated: animated)
    }

    func startChildFeature() {
        let child = ChildFeatureCoordinator(
            navigationController: navigationController
        )
        addChild(child)
        child.start()
    }
}

We have a lot of freedom with this approach:

1. We can decide and customize how the coordinator starts itself using the injected navigation controller.

2. We can use both UIKit and SwiftUI views (wrapped with UIHostingController) if needed.

    struct SomeFeatureScreen: View {
   
        weak var coordinator: FeatureCoordinator?
   
        var body: some View {
            // some body that calls 'pushNext' and 'presentAnother'
        }
   
        private func pushNext() {
            coordinator?.pushNextScreen()
        }
   
        private func presentAnother() {
            coordinator?.presentAnotherScreen()
        }
    }
   

   NOTE: In this example, each view is tied to a specific coordinator type. While this is a limitation, it's generally not a significant issue. If needed, you can use closures and wrapper views to handle multiple screens with different coordinators.

3. We have complete control over the navigation flow, allowing us to modify it programmatically - for example, when handling a deep link.

    final class FeatureDeeplinkHandler: DeeplinkHandlerProtocol {
   
        // ...
   
        func canOpenURL(_ url: URL) -> Bool {
            url.absoluteString.hasPrefix("deeplink://feature")
        }
   
        func openURL(_ url: URL) {
            guard canOpenURL(url) else {
                return
            }
            featureCoordinator?.dismissAll { [weak self] in
                self?.featureCoordinator?.startChildFeature()
            }
        }
    }
   

This approach is simple, scalable, and powerful - proven effective in large, mature modular apps. That's great, but what does SwiftUI offer for navigation?

What does SwiftUI offer?

NavigationStack vs. NavigationView

Before the introduction of NavigationStack, SwiftUI's NavigationView had many limitations. Many common navigation tasks were either difficult or impossible to achieve, such as pushing multiple screens or popping back to the root through several views or recreating navigation flows to open a specific screen sequence.

NavigationView struggled with managing state and handling programmatic navigation. Developers often resorted to workarounds or even reinvent the navigation stack, which was far from ideal.

NOTE: Since iOS 18, NavigationView is officially deprecated due to these limitations. Apple has made it clear that NavigationStack is the path forward for managing navigation in SwiftUI.

With iOS 16, Apple addressed these issues by introducing state-based navigation via NavigationStack, allowing developers to control navigation state programmatically in a convenient way. This resolved many challenges related to managing navigation state.

Let’s consider a simple example of NavigationStack:

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
                .navigationDestination(for: HashableRoute.self) { route in
                    switch route {
                    case .firstScreen:
                        FirstScreen()
                    case .secondScreen:
                        SecondScreen()
                    }
                }
        }
    }
}

enum HashableRoute: Hashable {
    case firstScreen
    case secondScreen
}

In essence, we can now control the navigation stack by modifying the navigation path, which can contain any Hashable elements. All it takes is wrapping the view in a NavigationStack and providing a path along with all the navigation destinations.

Now let’s explore how we can implement the Coordinator pattern in SwiftUI using NavigationStack. We'll aim to keep the implementation simple, but this will introduce some limitations as a result.

SwiftUI Coordinator

Let’s start by defining the coordinator protocols again:

protocol Coordinator: ObservableObject, CoordinatorFinishDelegate {

    associatedtype Content: View

    @MainActor @ViewBuilder var rootView: Content { get }

    var finishDelegate: CoordinatorFinishDelegate? { get set }

    func finish()
}

protocol CompositionCoordinator: Coordinator {
    var childCoordinators: [any Coordinator] { get set }
}

protocol FlowCoordinator: Coordinator {

    associatedtype Route: Routable
    associatedtype Destination: View

    @MainActor @ViewBuilder func destination(for route: Route) -> Destination

    var childCoordinator: (any Coordinator)? { get set }

    var navigationControllers: [NavigationController<Route>] { get set }
}

It looks quite similar to the UIKit version, but there are a few new elements:

• The Coordinator is now an ObservableObject, allowing us to observe navigation state changes.

• We have a rootView now. But why? In the UIKit example, we wanted to decouple navigation logic from views, avoiding UI framework details in the coordinator protocol. This remains a good goal, but in SwiftUI, the rootView is necessary for the setup to work. We’ll revisit this point later when discussing limitations.

• The start method is gone. As you’ll see, it’s no longer needed due to limitations in presenting child coordinators.

We also have some changes in FlowCoordinator:

• Route and Destination are new types defining the routes and screens handled by the coordinator. These will be used to provide destination views for the NavigationStack.

• NavigationController is our custom analog of UINavigationController, storing the navigationPath and presentedRoute state. We need it to build the state of our coordinator navigation flow.

    final class NavigationController<Route: Routable>: ObservableObject {
  
        @Published var navigationPath = NavigationPath()
  
        @Published var presentedRoute: Route?
  
        //...
    }
  

  

  We can think of our coordinator navigation flow as a chain of navigation controllers, each managing its navigation path and presenting the next one in the chain.

  

  They are all combined together and stored in the navigationControllers array, which we can see in the FlowCoordinator protocol.

  

For specific screen flow like a feature flow, SwiftUI coordinator will look like this:

final class FeatureCoordinator: FlowCoordinator {

    weak var finishDelegate: CoordinatorFinishDelegate?

    @Published var childCoordinator: (any Coordinator)?

    @Published var navigationControllers = [NavigationController<FeatureRoute>]()

    func destination(for route: FeatureRoute) -> some View {
        switch route {
            case .next:
                NextScreen()
            case .another:
                AnotherScreen()
        }
    }

    var rootView: some View {
        NavigatingView(
            nc: self.rootNavigationController,
            coordinator: self
        ) {
            FeatureScreen()
        }
        .environmentObject(self)
    }

    func pushNextScreen() {
        push(route: .next)
    }

    func presentAnotherScreen() {
        present(route: .another)
    }

    func presentChild() {
        present(child: ChildCoordinator())
    }
}

enum FeatureRoute: Routable {
    case next
    case another

    var navigationType: NavigationType {
        switch self {
            case .next:
                return .push
            case .another:
                return .present(.sheet([.medium, .large]))
        }
    }
}

As shown, FeatureRoute is an enum that contains all routes managed by FeatureCoordinator.

You probably noticed that rootView is a NavigatingView. NavigatingView is central to our SwiftUI navigation. In SwiftUI, everything is a View, and this wrapper view serves as the link between the Coordinator and SwiftUI views.

struct NavigatingView<SomeCoordinator: FlowCoordinator>: View {

    @StateObject var nc: NavigationController<SomeCoordinator.Route>
    @StateObject var coordinator: SomeCoordinator

    var content: () -> any View

    var body: some View {
        NavigationStack(path: $nc.navigationPath) {
            AnyView(content())
                .navigationDestination(for: SomeCoordinator.Route.self) {
                    coordinator.destination(for: $0)
                }
        }
        .sheet(isPresented: nc.isPresenting(with: .sheet())) {
            let detents = nc.presentedRoute?.navigationType.presentationType?.detents
            viewToPresent
                .presentationDetents(detents ?? .init())
        }
        .fullScreenCover(isPresented: nc.isPresenting(with: .fullScreenCover)) {
            viewToPresent
        }
        .sheet(isPresented: coordinator.shouldPresentChild(from: nc)) {
            if let childCoordinator = coordinator.childCoordinator {
                AnyView(childCoordinator.rootView)
            }
        }
    }

    @ViewBuilder
    private var viewToPresent: some View {
        if let route = nc.presentedRoute {
            NavigatingView(
                nc: coordinator.topNavigationController,
                coordinator: coordinator
            ) {
                coordinator.destination(for: route)
            }
        }
    }
}

As you can see, our NavigationStack is located inside NavigatingView. We also have our routes presentation implementation here with .sheet and .fullScreenCover modifiers.

If we need a new navigation type, we should add it to NavigationType - even custom navigation types if we want. Then it should be implemented in NavigatingView .

enum NavigationType {
    /// A push transition style, commonly used in navigation controllers.
    case push
    /// A presentation style, often used for modal or overlay views.
    case present(PresentationType)
}

enum PresentationType {
    /// A sheet presentation style
    case sheet(Set<PresentationDetent>? = nil)
    /// A full-screen cover presentation style.
    case fullScreenCover
}

The last thing to highlight in NavigatingView is how we present the child coordinator. To simplify the implementation, we intentionally limited the presentation options to the .sheet modifier. This is why the start method doesn’t add much value in this case - there’s no customization available for the child coordinator to initiate itself.

Finally, we can take a look on FeatureScreen:

struct FeatureScreen: View {

    @EnvironmentObject var coordinator: FeatureCoordinator

    var body: some View {
        // some body that calls 'pushNext' and 'presentAnother'
    }

    private func pushNext() {
        coordinator.pushNextScreen()
    }

    private func presentAnother() {
        coordinator.presentAnotherScreen()
    }

    //...
}

The FeatureScreen is quite similar to the one we used in the UIKit navigation example, with the main difference being the use of the EnvironmentObject property wrapper here. EnvironmentObject is used to demonstrate the options available, but it could also be an ObservedObject if you prefer using plain old constructor dependency injection.

For deeplink handling, we can use the same approach as we did with UIKit with FeatureDeeplinkHandler.

In the end, we had to write more code in comparison to UIKit, but now we can apply the Coordinator pattern using SwiftUI navigation. However, is this solution truly smooth and effective, or are there still limitations?

Limitations

Let's explore the limitations of our SwiftUI Coordinator implementation, especially when compared to UIKit approach. Many of them are simply differences between SwiftUI and UIKit navigation systems, but some comes from the attempt to not overcomplicate the SwiftUI solution.

View-Bound Nature

In SwiftUI approach, you might have noticed we needed to add more view-related properties to our Coordinator protocols, such as rootView and destination. This makes SwiftUI's NavigationStack based approach more tightly coupled to the views, which contrasts with UIKit’s approach where coordinator protocol was abstracted away from the views. This "view-bound" characteristic comes from SwiftUI's view-centric nature, where everything is a wrapper around a view. This makes it difficult to keep Coordinator protocol agnostic to the framework details. But this is not a significant limitation unless you intend to reuse your Coordinator solution across different platforms or frameworks.

Complexity

Navigating in SwiftUI tends to feel more complex when it goes a bit from simple examples. You might have noticed the increased amount of code required for the SwiftUI coordinator compared to UIKit one. In UIKit, injecting a UINavigationController into specific coordinator implementation was usually enough for most navigation tasks, since navigation controller also acts as a UIViewController that can present other view controllers.

In contrast, NavigationStack in SwiftUI is limited. It only handles pushing and popping views. Presentation is out of it’s control. For more advanced scenarios, you need to create custom solutions. We had to create a custom NavigationController and wrap views within NavigatingView to achieve similar capabilities, adding to the overall complexity.

Starting Child Coordinators

UIKit Coordinator approach offers a great deal of freedom in how you navigate to child coordinators - be it pushing, presenting, or using custom transitions. It also allows child coordinators to handle their own starting process through a start method.

In our SwiftUI implementation, starting child coordinators is restricted to using the sheet modifier. While other modifiers like fullScreenCover could theoretically be supported, this would further complicate the solution. This limitation is the reason why the start method doesn’t make sense in SwiftUI approach - it makes sense only when a child can determine and initiate its own presentation, which isn’t possible under this approach where presentation is fully controlled by parent.

Another limitation is that attempting to push a new coordinator onto an existing NavigationStack is particularly challenging there because each FlowCoordinator is bound to a specific Route type and making two coordinators to share the same Route type doesn’t make much sense.

Changing the Navigation Path

SwiftUI's NavigationStack also has limitations regarding modifying navigation path. The NavigationPath can only pop elements from the end of the stack with removeLast(_ k: Int = 1) method. Unlike UIKit, it can't remove elements from the middle of the stack, which limits its flexibility.

Even if you use an array of routes instead of NavigationPath, removing elements from the middle causes strange behavior with unexpected pop animations. You can see it on example above.

Moreover, the initial root view in NavigationStack isn’t included in the navigationPath array, making any modification of the root view impossible.

Custom Navigation Transitions

SwiftUI lacks support for custom navigation transitions when using NavigationStack. A third-party package called NavigationTransitions supports custom transitions for iOS 16, but depending on external SDKs has its own downsides. iOS 18 introduces a new API, NavigationTransition, that allows custom transitions like zoom. However, this isn’t helpful if you need to support iOS 16 or earlier versions.

UIKit remains more robust and reliable for custom navigation transitions. If you’re okay with using only standard transitions, SwiftUI will suffice, but for more sophisticated effects, UIKit still stands out.

Navigation Bar Customization

SwiftUI allows navigation bar customization with modifiers like navigationTitle, and toolbar. However, deeper customizations - like adjusting the height, adding a background image, or modifying the back button - are more limited compared to UIKit. You can access global UINavigationBarAppearance to achieve some customizations in SwiftUI, but UIKit remains far superior in this regard.

Working with Environment

Finally, an advantage for SwiftUI approach. If you rely on the @EnvironmentObject property wrapper, SwiftUI offers direct integration, which doesn't work properly in UIKit's hosting controller approach. While @Environment still works in UIHostingController approach, @EnvironmentObject does not.

Personally, I am not a big fan of environment objects. I prefer constructor injection, much like how I prefer using Factory over Swinject, or why I avoid force-unwrapped optionals. I respect Murphy's law and believe that if it can crash, it will crash. (Depending on environment objects can lead to unpredictable crashes—check out my DI in SwiftUI article for more details.)

Final Thoughts

Given these limitations, I find myself leaning towards continuing using UIKit Coordinator approach for navigation, at least for now.

UIKit's navigation model is powerful, predictable, and well-proven. When needed, I can combine UIKit with SwiftUI to leverage the best of both worlds and avoid potential headaches related to navigation.

Migrating to SwiftUI for navigation currently brings limited benefits, particularly given the edge cases I could miss and added complexity.

NOTE: It’s worth mentioning that everything discussed in this article reflects the current state of SwiftUI Navigation. SwiftUI continues to improve each year, and I believe that in the coming years, it will reach a point where it meets our needs. For now, though, it is what it is.

Can we use a Third-Party Library for SwiftUI Navigation? There are several quite popular libraries available that can simplify navigation in SwiftUI, such as Stinsen or PointFree's SwiftUINavigation. However, I prefer avoiding third-party dependencies for something as fundamental as navigation. Third-party libraries may stop receiving updates or break with new versions of iOS, leaving you at the mercy of someone else's timelines or requiring you to maintain your own fork with solutions that are quite complex.

Many large-scale applications has complex navigation engines which uses a path-based approach where everything is a deep link and are unlikely to migrate away from their powerful solutions to a more constrained SwiftUI-based navigation system anytime soon.

If you have insights or experiences with SwiftUI navigation, feel free to share them in the comments. You can also check out the code examples for this discussion.

You can find the example project code here if needed.

If your application has grown in complexity over time, modularization can be a good strategy to improve development efficiency, build time, scalability, maintainability, and etc. Today, we will precisely examine the path from monolith to modular app, step by step, and provide insights about each step along the way.

From monolith to modularization

Before transitioning to modularity, your app likely adhered to some monolithic architecture that followed some form of layered architecture, one of the most common and widely used software architecture patterns. Layered architecture organizes the components of an application into separate horizontal layers, with each layer serving a specific function or responsibility.

As a typical example for possible layers:

• Data/Persistence layer: responsible for data storage and retrieval.

• Business Logic layer: contains the application's core functionality and logic.

• Presentation layer (UI): handles user interface and communication.

NOTE: For example, CLEAN, Onion, Service Oriented (SOA) architectures are examples of layered architecture.

In addition to layer separation, we also need to keep in mind the dependency direction rule:

Layers can depend UPWARD but NOT DOWNWARD.

The dependency direction rule heavily relies on the Dependency Inversion principle, enabling us to maintain loose coupling between our layers, providing encapsulation and scalability.

Layered Modular Architecture

The concept of layered architecture is straightforward and can actually be applied to our modular architecture as well.

In essence, modularization involves dividing your app into separate modules. Thus, you can apply layered approach to modularization by integrating your modules into specific layers.

We'll structure our modularized app into three layers: Core, Features, and Composition Root.

Core Layer:

• Contains code that is used across various features of the app.

• Offers shared functionality that is agnostic to the specific app, encompassing UI components, networking, analytics, utilities, metrics, authentication, logging, and more.

• Core modules operate independently of each other; they do not depend on other core modules.

Feature Layer:

• Feature modules encapsulate distinct features or functionalities of the app, such as specific screens, sets of related screens, or views - examples include payment processing, customer profiles, restaurant list, search, support chat and etc.

• They contain all code relevant to specific feature, covering UI, logic, and data handling.

• While feature modules may depend on core modules if necessary, they should not depend on other feature modules.

• Feature modules promote separation of concerns, facilitating independent development, testing, and reusability across projects.

Composition Root:

• The composition root serves as a central place within the application where the object graph is assembled/composed. Its primary responsibility lies in creating and injecting all the dependencies throughout the application.

• Composition Root pattern enables the modules (and layers) to maintain loose coupling, facilitating seamless transitions between implementations if needed.

• It's important to note that the composition root itself is not a module; rather, it resides within your app's main target.

• Each feature will have its own designated composition folder within the composition root, referred to as the Feature[X]Support folder (or Feature[X]Composition if you like).

• For those unfamiliar with Dependency Injection (DI) and the concept of Composition root, further details can be found here, here and here.

NOTE 1: The same dependency direction rule applies to modular layers, but we also need to enforce the restriction that modules within one layer should not depend on each other. Together with dependency direction rule this allows to avoid circular dependencies. We achieve this by applying Dependency Inversion principle and abstracting dependencies from other modules using public protocols. (This rule is applicable to both core and feature layers.)

NOTE 2: We haven't forbidden feature modules from depending on core modules. This allowance is important, particularly in scenarios involving shared UI components, where direct dependencies can sometimes be preferable to avoid the added complexity of abstraction through dependency inversion. However, it's important to note that not all core packages need to be direct dependencies of features; in fact, the fewer direct dependencies your feature module has, the more flexibility it gets. Inverting the dependency on core modules fosters loose coupling between core and feature layers, making it easier to substitute/reuse modules in the future. It's beneficial to abstract core module dependencies and inject them via the composition root, but abstraction goes with related cost (will discuss it a bit later with example).

NOTE 3: We haven't specified the method of implementing modularity—whether it's through SPM, CocoaPods, or any other means—because, in reality, it doesn't matter for the modularization strategy we're discussing here. You're free to choose whichever method you prefer.

Getting started

So, now you're ready to begin migrating from a monolithic to a modular structure.

Logically, the first step is to migrate the core modules. How do you determine which code should be moved to the core layer? Look for functionality that is shared and required by multiple feature modules in your application. This may include UI components, networking, authentication, analytics, logging, utility functions, and so on.

Once all core modules are modularized, let's consider a scenario where you have a feature within your monolith that you want to modularize next. You need to create a new module and move the related code there.

Now, it's important to ensure that the dependency direction rule is not violated.

You may find yourself in one of the three situations listed below:

1) Your module depends on another feature (SAME LAYER)

It’s not allowed by our dependency direction rule.

We need to do Dependency Inversion to comply with it.

This means that our module should depend on abstractions/interfaces/protocols, rather than concrete implementations that lies in another feature module.

Let's clarify how we can do it with a typical example. Imagine that we have a navigation scenario where one feature presents another.

// somewhere inside your feature module...
import AnotherFeature // Can't depend on AnotherFeature module here
import UIKit

final class YourFeatureViewController: UIViewController {
    private func showAnotherFeature() {
        let vc = AnotherFeatureViewController()
        present(vc, animated: true)
    }    
}

To get rid of dependency on AnotherFeature, we want to invert this dependency. We create the public routing protocol inside of our new feature module:

public protocol YourFeatureRouting {
    func showAnotherFeature()
}

Now we can use this protocol for navigation:

import UIKit

final class YourFeatureViewController: UIViewController {
    private let featureRouter: YourFeatureRouting

    init(featureRouter: YourFeatureRouting) {
        self.featureRouter = featureRouter
    }

    private func showAnotherFeature() {
        featureRouter.showAnotherFeature()
    }    
}

For example, in this case, your feature interface is a factory that creates view controller for specific screen. We need to add routing protocol as a required dependency of our feature by putting it into factory params list.

import UIKit

public enum YourFeatureFactory {
    static func make(
        featureRouter: YourFeatureRouting
    ) -> UIViewController {
        YourFeatureViewController(featureRouter: featureRouter)
    }
}

Now, our module explicitly declares that it requires the user of the module (the caller side, in our case, the composition root) to provide an implementation for the YourFeatureRouting protocol, which our feature is intended to use.

Next, inside our composition root in YourFeatureSupport folder we will implement the router and conform to this routing protocol:

import AnotherFeature
import UIKit
import YourFeature

struct YourFeatureRouter: YourFeatureRouting {
    var source: UIViewController?

    func showAnotherFeature() {
        let vc = AnotherFeatureViewController()
        source?.present(vc, animated: true)
    }
}

Now we need to compose everything together with our router using composition factory:

import UIKit
import YourFeature

enum YourFeatureCompositionFactory {
    static func make() -> UIViewController {
        let featureRouter = YourFeatureRouter()
        let featureService = YourServiceFactory.make()
        let vc = YourFeatureFactory.make(
            featureRouter: featureRouter,
            homeService: homeService
        )
        featureRouter.source = vc
        return vc
    }
}

And that’s it! We inverted the dependency on AnotherFeature.

2) Your module depends DOWNWARDS

It’s not allowed by our dependency direction rule.

Decide the optimal location for the code you depend on:

• If it’s your new feature module:

  • Move or copy the dependent code to your new feature module.

or

• if it’s another module (whether feature or core):

  • Transfer it to another module (you can create a new module if required).

  • Invert the dependency using the same approach. Create a public protocol and specify what your new feature module expects to receive from the composition root. Inject the dependency through the feature interface.

3) Your module depends UPWARDS

This aligns with our dependency direction rule.

As previously mentioned, depending on the core module from feature module can be essential like for the UI components core module (CompanyUIKit). For some core modules you need to consider whether to proceed with this direct dependency or to invert the dependency by injecting it from the composition root, as we have done previously.

Dependency inversion fosters loose coupling between core and feature layers, provides more flexibility and reusability.

For example, imagine that you depend on Networking core module from your feature module:

• (Flexibility) Imagine that you wish to replace the obsolete Networking module with the brand new NetworkingGPT module.

  • If you directly depend on the networking module, you'll need to modify all networking-related code within the feature module and update imports in every file where you use code from networking module.

  • Conversely, if you've inverted the dependency and injected it via the composition root, it becomes easier to make the switch. By defining a public feature service protocol to be implemented within the composition root, you conceal the networking implementation details from the feature module. All that's required is to provide a new implementation for the feature service protocol within the composition root.

• (Reusability) If you aim to reuse your feature module in another project, it becomes simpler to move it.

• (Cost of benefits) However, this approach introduces a bit more complexity and necessitates writing additional code.

Consider these pros and cons in the context of your specific scenario.

Final thoughts

The idea I wanted to convey here is that modularization isn't rocket science. It's not quick either, especially for larger projects. However, the positive aspect is that you can undertake it gradually. Rome wasn't built in a day, and with patience, you can succeed as well.

You can find a simple modular project example here. See you in the next post!

While the concept may seem straightforward for experienced UIKit developers, it's easy to fall into a trap and end up with a solution like this:

import SnapKit
import SwiftUI

extension UIView {
    func addSwiftUIView<T: View>(view: T) {
        let hostingController = UIHostingController(rootView: view)
        addSubview(hostingController.view)
        hostingController.view.snp.makeConstraints {
            $0.edges.equalToSuperview()
        }
    }
}

It can even appear to work fine until it doesn't. The issue here is that we don't retain UIHostingController after the hosting setup, and it is deallocated instantly. However, UIHostingController is intended to play an important role in UIKit/SwiftUI communication.

For example, the hosting controller can track changes to the size of its SwiftUI content using sizingOptions:

@MainActor
var sizingOptions: UIHostingControllerSizingOptions { get set }

From WWDC2022, we know that since iOS 16, you can use the .preferredContentSize and .intrinsicContentSize options on UIHostingController to automatically update the ViewController’s preferredContentSize and the view’s intrinsicContentSize. This can be enabled using the sizingOptions property on the UIHostingController. The default sizing options value is empty.

NOTE 1: The intrinsicContentSize of a UIView refers to the ideal size that a view would like to occupy based on its content. This property allows a custom view to tell its content size to the layout system without explicitly setting it. It simplifies working with Auto Layout by reducing the need for explicit constraints, making layouts more flexible and dynamic.

NOTE 2: The ViewController's preferredContentSize refers to the desired size for the content of the view controller. It allows the view controller to tell its preferred dimensions to the layout system when the view controller should be presented, especially in scenarios like popovers where specifying an ideal size is crucial for proper display. By setting the preferred content size, developers can control the presentation of view controllers and ensure that they are displayed optimally based on their content.

Let’s return to our example now. Once UIHostingController is deallocated, it can't perform its job on sizing updates if the SwiftUI view's content is changed.

So, as a first step, we can try to at least retain UIHostingController:

func addSwiftUIView<T: View>(view: T) -> UIHostingController<T> {
    let hostingController = UIHostingController(rootView: view)
    addSubview(hostingController.view)
    hostingController.view.snp.makeConstraints {
        $0.edges.equalToSuperview()
    }
    return hostingController
}

let hostingController = addSwiftUIView(SwiftUIView())
// retain UIHostingController somewhere
self.hostingController = hostingController

If we activate sizing options with .intrinsicContentSize, it will even start to work, and the hosting view will update its intrinsicContentSize when the SwiftUI view's size is changed. However, this is still not how UIHostingController is intended to be used.

NOTE: Use the hosting controller like you would any other view controller, by presenting it or embedding it as a child view controller in your interface.

So, we need to set it up like any other UIViewController by adding it as a child view controller:

import SnapKit
import SwiftUI

extension UIViewController {
        @discardableResult
    func hostSwiftUIView<T: View>(
        view: T,
        insideView hostView: UIView? = nil
    ) -> UIHostingController<T> {
        let hostingController = UIHostingController(rootView: view)
        addChild(hostingController)
        hostingController.didMove(toParent: self)
        if let hostView {
            hostView.addSubview(hostingController.view)
        } else {
            self.view.addSubview(hostingController.view)
        }
        hostingController.view.snp.makeConstraints {
            $0.edges.equalToSuperview()
        }
        return hostingController
    }
}

NOTE: We passed hostView for cases when we want to add the hosting view as a subview to a view in the hierarchy that is not the view controller’s view.

That’s it! And don’t forget to setup sizing options of the hosting controller:

let hosting = hostSwiftUIView(view: SwiftUIView())
if #available(iOS 16.0, *) {
    hostingController.sizingOptions = [.intrinsicContentSize]
}

NOTE: We set up the sizing options outside of the hostSwiftUIView method because sizing options come with a performance cost, as the hosting controller asks for the ideal size of the content on every view update. You can move sizing options setup inside of the hostSwiftUIView if you are ready for that cost.

The happy path is complete. Let’s discuss a few edge cases next.

Before iOS 16

Sizing options are cool, but what if I need to support iOS 15 or even earlier versions?

In this case, you can still update the hosting controller’s view size explicitly by calling setNeedsUpdateConstraints() (or invalidateIntrinsicContentSize() that will eventually call setNeedsUpdateConstraints()).

func hostSwiftUIViewIfYouStillSupportOS15() {
    let swiftUIView = SwiftUIView { [weak self] in
        self?.hostingController?.view.setNeedsUpdateConstraints()
    }
    hostingController = hostSwiftUIView(
        view: swiftUIView, 
        insideView: view2
    )
}

We need to call setNeedsUpdateConstraints at the right time when view state is changed and intrinsic content size should be recalculated:

struct SwiftUIView: View {

    @State var state: ...

    var onUpdateContent: (() -> Void)?

    var body: some View {
        // some View...
        .onChange(of: state) { _ in
            onUpdateContent?()
        }
        .onAppear {
            onUpdateContent?()
        }
    }
}

In this example I had to do it also on view appear to make it work correctly. For some reason initial intrinsic size is calculated incorrectly so need to update it when view content appears.

NOTE: This solution will work for iOS 16/17 as well, but using sizingOptions is obviously much simpler and convenient option.

If you have only UIView

If you have some UIKit legacy code and you need to add SwiftUI view inside UIView and have no reference to UIViewController, you have some options as well.

extension UIView {
    func hostSwiftUIView<T: View>(view: T) -> UIHostingController<T>? {
        guard let vc = findViewController() else { return nil }
        return vc.hostSwiftUIView(
            view: view,
            insideView: self
        )
    }

    func findViewController() -> UIViewController? {
        if let nextResponder = self.next as? UIViewController {
            return nextResponder
        } else if let nextResponder = self.next as? UIView {
            return nextResponder.findViewController()
        } else {
            return nil
        }
    }
}

You can use the responder chain to get the next UIViewController in the hierarchy, but once finding the view controller is not guaranteed, that solution is not ideal. If you can avoid using it, prefer to handle this using the UIViewController.

Popovers and preferredContentSize

Now we’ve managed to get .intrinsicContentSize sizing option to work properly, but let’s see how we can use .preferredContentSize option now. If you try to present UIHostingController as a popover you will face some issues.

extension UIViewController: UIPopoverPresentationControllerDelegate {
    @discardableResult
    func presentPopover<T: View>(
        withSwiftUIView view: T,
        sourceView: UIView,
        permittedArrowDirections: UIPopoverArrowDirection = .any
    ) -> UIHostingController<T> {
        let hostingController = UIHostingController(rootView: view)
        if #available(iOS 16.0, *) {
            hostingController.sizingOptions = [.preferredContentSize]
        }
        hostingController.modalPresentationStyle = .popover
        if let popoverPC = hostingController.popoverPresentationController {
            popoverPC.permittedArrowDirections = permittedArrowDirections
            popoverPC.sourceView = sourceView
            popoverPC.delegate = self
        }
        present(hostingController, animated: true)
        return hostingController
    }
}

Let’s try a simple example again:

The first thing you can notice here is that the hosting controller doesn’t care about the minimal popover size. As you can see, it goes with the height that the hosted SwiftUI view returns to it.

You can help hosting controller by providing minimal height using frame modifier.

SwiftUIView().frame(minHeight: 40)

It looks better now:

But you can see another two issues here:

• Animation doesn’t work properly with the popover mask. I'm not sure if we can do anything about it. Let me know if you have any ideas on how to fix it.

• Content size updates don't work properly either. If the hosting controller returns a preferredContentSize that is bigger than the popover’s maximum size (aka screen size minus paddings), the popover will truncate the view’s size using this allowed maximum. In our case, it uses the returned preferred content height and truncates the preferred content width. To address this issue, we can provide some anchor width as the ideal width in the frame modifier. This ideal width will be used to calculate the preferredContentSize that will satisfy our expectations.

SwiftUIView().frame(idealWidth: 250, minHeight: 40)

That’s it. Now popover updates the size when content size is changed as expected.

You can find example project here.

Thanks for reading and see you in the next posts!

You can say that UIKit is great, but SwiftUI is a future. But don’t hurry up to burry UIKit, as you will understand soon, it is still very useful to understand how SwiftUI works under the hood.

SwiftUI is a declarative data-driven UI framework.

• Declarative means that you describe the desired UI and its behavior by providing the view’s body, and SwiftUI handles the internal implementation details.

• Data-driven (or state-driven) means that the UI is closely tied to the underlying data or state, and any changes in the state will be automatically reflected in the UI.

SwiftUI conceals its entire render loop process behind the body of the view provided to us for constructing the View.

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

Structure of the body defines both layout and content of the view. Let’s try to figure out what stands behind the body.

DISCLAIMER: Things we will discuss next are not documented and we have no access to the actual SwiftUI code/implementation. So I will try to give a guess how it can possibly work to help you build your own mental model about it.

View and Render tree

Similarly to UIKit, SwiftUI has its view tree. However, in contrast to UIKit, where UIView is an object, views in SwiftUI are structs, making the view tree ephemeral. This implies that view values in SwiftUI are transient and can be recreated whenever the state changes. Direct manipulation of the view tree isn't possible in SwiftUI. Instead of mutating the view tree directly as in UIKit, we modify the state, prompting SwiftUI to calculate a new view graph from this state. Views are recreated upon state changes, and the body is re-evaluated. SwiftUI optimizes this process by avoiding re-execution of a subview's body when it remains unchanged. To determine when to re-evaluate the body, SwiftUI utilizes the Attribute Graph. This is an internal component that builds a dependency graph for your data and its associated view tree. Unlike the view tree, the Attribute Graph is persistent and remains even when the body re-executes. And it has to, because it stores the state that must remain after view tree recreation. With each new generation of the view tree, SwiftUI performs a diff against the current state of the render tree, efficiently applying the necessary changes by adding and removing nodes from the render tree.

Chris Eidhof refers to the Attribute Graph as the Render Tree to simplify the understanding of the concept. This makes sense to me because it serves as a sort of source of truth for rendering. Additionally, it's a fitting analogy with the render tree in UIKit.

View Render Loop

We can split render loop into several phases:

• Evaluation Phase

• Layout Phase

• Rendering Phase

Evaluation Phase

Let’s highlight again: the view tree is ephemeral, while the render tree is persistent. Initially, the root node of the render tree should be created first, and it is probably something like node for ContentView to start with. Next, the view tree should be constructed. To initiate this process, ContentView's body should be evaluated. Step by step, from superviews to subviews in the hierarchy, SwiftUI prepares the view tree, composing it into a complex generic structure hidden beneath some View. View tree is used to construct the render tree. Once render tree construction is complete, SwiftUI can discard and throw away the entire view tree.

When the state is changed for a render tree node, the affected render sub-tree is invalidated. SwiftUI then rebuilds the corresponding view subtree and re-evaluates the bodies if necessary to update the render tree structure. As a result of this phase, SwiftUI should have the render tree rebuilt and ready for the subsequent phases.

Layout phase

After Attributed Graph is (re)constructed and ready, SwiftUI performs layout calculations to determine the position, size, and arrangement of each view within the parent view or container.

Layout phase is very well explained in articles from Alex Grebenyuk and Paul Hudson:

Layouts proceed top down: parent views offer their available space to their children, which decide their size based on that.

There are three steps in SwiftUI layout process:

1. Parent Proposes Size for Child

First, the root view offers the text a proposed size – in this case, the entire safe area of the screen, represented by an orange rectangle.

2. Child Chooses its Size

Text only requires that much size to draw its content. The parent has to respect the child's choice. It doesn't stretch or compress the child.

3. Parent Places Child in Parent’s Coordinate Space

And now the root view has to put the child somewhere, so it puts in right in the middle. That means views set the position of child’s, but not by SwiftUI externally.

NOTE: Layout in SwiftUI is easy until it's not.

Steps sound pretty easy but what sometimes makes layouts in SwiftUI complex (especially after years of UIKit development) is that each view (or view modifier) behaves differently when it comes to determining the actual size from the proposed size. For example, a shape always fits itself into the proposed size; a horizontal stack takes on the size that’s needed for its children (up to the proposed size); and a text view takes on the size needed to render its text, unless its size exceeds the proposed size, in which case the text gets clipped. You need to keep all of that in mind.

Rendering phase

Once layout is completed views are supposed to be rendered on the screen. The exact process SwiftUI uses for rendering remains uncertain. Yet, it's reasonable to assume that SwiftUI relies on underlying UIKit, Core Animation, Core Graphics and Metal to do that. And keeping that in mind there should be some kind of mapping from SwiftUI view/render tree into UIKit view tree. In this case Rendering phase is probably can be better called Mapping to UIKit phase. We'll try to confirm this assumption in the next part of this post.

Behind the render loop

That was a bunch of theory in the previous post. How about exploring some real details we can uncover from the debugger?

Let’s create a new SwiftUI project in the Xcode and try to see what happens before body is called by placing a breakpoint inside the view body.

We can make a few observations here:

• AG::Graph represents the Attribute Graph we previously mentioned. Occasionally, there might be a lengthy stack trace related to AG.

• __lldb_unnamed_symbol123456 denotes parts of the SwiftUI code, which remain hidden from us.

However, our primary interest lies in the lower part of the stack trace. There, we might observe something very interesting:

The bottom of the stack should actually provide you with a strong hint of how SwiftUI works internally:

• UIApplicationMain

  • → __CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__

    • → CATransaction.commit()

      • → UIView(CALayerDelegate).layoutSublayersOfLayers

Looks pretty familiar, doesn't it? It's just like the UIKit render loop we discussed in the previous post. This occurs in a pure SwiftUI application without a single UIView added by us. It actually proves that SwiftUI incorporates UIKit and CoreAnimation under the hood, inheriting plain old UIKit’s render loop we previously discussed.

During each runloop iteration, when the CALayer/UIView hierarchy traversal takes place as a part of the implicit CATransaction’s layout phase, SwiftUI conducts its render loop starting from the layoutSublayers(of:) call of the UIView that hosts the SwiftUI view hierarchy (to be precise, _UIHostingView).

Now let’s try to understand connection of SwiftUI and CATransaction better.

Connection with CATransaction

The same way as UIKit, in SwiftUI views will be rendered on screen when the implicit CATransaction is committed. You can observe connection of SwiftUI and CATransaction with simple example. We can add CATransaction.begin() into onTapGesture.

DISCLAIMER: I am strongly recommend you not to use CATransaction with SwiftUI in your codebase. It is just a demonstration example just for fun.

struct SwiftUIView: View {

    @State var color: UIColor = .red

    var body: some View {
        Circle()
            .fill(Color(color))
            .onTapGesture {
                color = .yellow
                CATransaction.begin()
                color = .green
            }
    }
}

As you probably remember from the post about UIKit, when you call CATransaction.begin(), a new transaction object is created and pushed into the shared transaction stack. So if you don’t do CATransaction.commit() after that, you simply break the transaction stack because of the way how transactions work. No layer tree changes will be committed from your app to the render server after that. So in our example we will not see nether yellow or green color update on the screen after tap. That shows us the connection between SwiftUI and CATransaction. SwiftUI relies on transactions the same way as UIKit does.

If we try to build similar example with explicit transaction as we did for UIKit we will discover another important aspect of SwiftUI.

struct SwiftUIView: View {

    @State var color: UIColor = .red

    var body: some View {
        Circle()
            .fill(Color(color))
            .onTapGesture {
                CATransaction.begin()
                color = .yellow
                CATransaction.commit()
                sleep(3) // blocks the main thread for 3 seconds
                color = .green
            }
    }
}

In similar UIKit example we would see yellow color in the middle once explicit transaction is commited before main thread had beed blocked by sleep().

@objc func buttonTapped() {
    CATransaction.begin()
    button.backgroundColor = .yellow
    CATransaction.commit()
    sleep(3) // blocks the main thread for 3 seconds
    button.backgroundColor = .green
}

But in SwiftUI, it seems to not working the same way, but why? 🤔

Let’s remember how CATransaction works. It commits the new changes of layer tree to the render server. But in our SwiftUI example we didn’t do any changes to any CALayer inside our explicit transaction (between begin and commit).

CATransaction.begin()
color = .yellow // changes only color state property, no CALayer changed
CATransaction.commit()

We only changed the state of SwiftUIView. And it needs to do another SwiftUI render loop to actually rebuild view tree and render tree to apply changes to underlying layers.

This is actually why none of the changes after the body evaluation or onAppear call aren’t rendered instantly. At the moment of body evaluation/onAppear/onChange underneath CALayer properties are not yet changed so at that moment nothing to commit yet. We need to do a full SwiftUI render loop first to change underlying layers that will be committed with implicit transaction and eventually rendered.

We can extend this example a bit. We already know that in the root of Swift hierarchy lies _UIHostingView. It is UIKit UIView and it has it’s CALayer under the hood. There is no way to access _UIHostingView from SwiftUI code but If we set _UIHostingView to a global variable from UIKit side, we will be able to access it inside onTapGesture. (Never do anything like that in your production code 🙈)

If we change the backgroundColor of hostingView inside the explicit transaction on tap gesture:

var hostingView: UIView? // Set it globally

struct SwiftUIView: View {

    @State var color: UIColor = .red

    var body: some View {
        Circle()
            .fill(Color(color))
            .onTapGesture {
                CATransaction.begin()
                hostingView?.backgroundColor = .yellow
                color = .yellow
                CATransaction.commit()
                sleep(3) // blocks the main thread for 3 seconds
                color = .green
            }
    }
}

Flow will be like that:

It shows us that CATransaction works with layer tree changes as expected even inside SwiftUI code. But it also shows that it makes no sense to use explicit CATransaction in SwiftUI views once you usually don’t access CoreAnimation layer tree directly from SwiftUI (and you should not).

We used hosting view in the last example, but didn’t talk about it much so far. Let’s discuss it next.

HostingView as a host

If we look in Xcode structure while debugging a new UIKit project we will see:

And in the root of a new SwiftUI application you will see exactly the same structure but with HostingViewController with _UIHostingView that hosts SwiftUI ContentView:

All of SwiftUI's view tree is hosted by _UIHostingView, controlled in turn by the UIHostingController. Any changes to the view structure applied to _UIHostingView and its subviews by SwiftUI internally are rendered by the usual CoreAnimation render loop we discussed earlier.

When you add new SwiftUI views to your ContentView body, SwiftUI will add UIKit subviews to _UIHostingView if needed. I mentioned "if needed" because not every SwiftUI view corresponds directly to a UIKit UIView under the hood. There are multiple ways graphics can be rendered in SwiftUI. SwiftUI can internally create a UIView to display them, or it might not. For instance, while some views like VStack participate in layout, they don't have their own UIView under the hood.

Let’s consider simple SwiftUI view as example:

struct ContentView: View {    
        var body: some View {
            VStack {
                Image(uiImage: .strokedCheckmark)
                Text("Text")
                TextField("Title", text: .constant("TextField"))
            }
      }
}

View body generic type hidden behind some View will be following:

VStack<
    TupleView<
        (Image, Text, TextField<Text>)
    > 
>

Looking at the above code sample, it’s easy to jump to the conclusion that the resulting UI will consist of:

• Vertically aligned UIStackView which contains:

  • UIImage

  • UILabel

  • UITextField

However, only part of those assumptions is actually true. Unlike CALayer within each UIView, not every SwiftUI view has a UIView behind it. Some SwiftUI views do utilize UIKit under the hood, although not all of them.

In our example we will see the following structure of subviews added to hosting view:

• _UIGraphicsView for Image

• CGDrawingView for Text

• ViewHost (It’s actually just UIViewRepresentable ) with hosted UITextField for TextField

I'll attempt to group all views based on the way they are backed up by UIKit:

• No UIView behind

  • Layout/structure based views - Spacer, V(H/Z)Stack, LazyH(V)Stack

• Backed by _UIGraphicsView

  • Graphics based views - Color, Image, Divider

• Backed by CGDrawingView class (subclass of _UIGraphicsView)

  • Text based views - Text, Button, TextEditor

  • CG prefix gives us a hint that SwiftUI uses CoreGraphics for text rendering the same way as UIKit does it.

• Specific UIKit.UIView hosted by UIViewRepresentable

  • TextField (with UITextField), ProgressView, Slider, List

• Composition of views listed above

IMPORTANT NOTE: You need to keep in mind that underlying implementation of SwiftUI views can change with time. I guess it is the reason why Apple keeps SwiftUI implementation private, they can change it with time but SwiftUI API will remain he same. For now, SwiftUI mostly wraps existing UI frameworks like UIKit, CoreAnimation, Core Graphics. In the future if Apple decides to, they can deprecate UIKit without changing the SwiftUI APIs and rewrite the foundation of it. I see that as a very long way though, so UIKit probably will be there for some time.

Recap

• SwiftUI is a declarative and data-driven UI framework.

• The Role of thebody:

  • The body of a view defines both its layout and content.

  • Behind the body, SwiftUI operates through a complex system involving view tree and attribute graph also known as render tree.

• View Tree and Render Tree:

  • SwiftUI has a view tree, but unlike UIKit, views in SwiftUI are transient structs.

  • Views are recreated when state changes, and SwiftUI optimizes this process by leveraging the attribute graph to track state changes.

• View Render Loop:

  • The view render loop involves three phases:

    • evaluation phase

    • layout phase

    • rendering phase (or mapping to UIKit phase)

  • Evaluation phase includes rebuilding view tree, diffing and body evaluation.

  • Layout phase proceed goes top down: parent views offer their available space to their children, which decide their size based on that.

  • We don’t know much about SwiftUI rendering phase. But we know it relies on underlying UIKit, Core Animation and Core Graphics for that. Rendering phase is probably can be better called Mapping to UIKit phase.

• CATransaction and SwiftUI:

  • By relying on UIKit/CoreAnimation SwiftUI internally utilizes implicit CATransaction for managing changes to the layer tree. Although you don't use CATransactions directly in SwiftUI apps, the framework internally still uses Core Animation and CATransactions for drawing and animations. Together with the render server, Core Animation is very foundational to iOS and SwiftUI.

• HostingView and UIKit Integration:

  • SwiftUI view tree is hosted by _UIHostingView, controlled by UIHostingController.

  • Some views internally use UIKit views (like i.e UITextField used and hosted by TextField). Even though not all SwiftUI views are mapped to UIKit views internally.

  • SwiftUI currently wraps existing UI frameworks like UIKit, CoreAnimation, and Core Graphics. SwiftUI abstracts away complexities and could potentially allow Apple to evolve underlying implementations in the future without changing the SwiftUI API.

Thank you for reading and see you in the next posts!

Intro

As iOS developers, we engage extensively with user interfaces. Understanding of various aspects of UI like lifecycle or layout is crucial for working with UIKit and SwiftUI. Do developers truly need to comprehend the underlying mechanics of UI, or they can solely rely on the provided APIs? I believe that understanding of framework's internal workings can offer significant benefits like avoiding poor performance, sporadic glitches, unexpected animations or layout bugs. Moreover, it is a lot of fun!

The primary objective of this series of posts is to provide you with a comprehensive overview of how UIKit and SwiftUI works under the hood. We will discuss UIKit first and save SwiftUI for the next post.

UIKit

Let's consider an example that often can be seen in UIKit applications. At a certain point in your app, you want to add a subview within your view controller's view.

// Not really long time ago in a far galaxy view controller...
override func viewDidLoad() {
     super.viewDidLoad()
     let subview = QuestionView()
     view.addSubview(subview)
     setupConstraints(for: subview)
}

Example looks trivial, right? But how it actually works?

Let’s split the bigger how into smaller questions:

• What happens in the app before we update the UI in viewDidLoad?

• How the change of UI is applied? How new subview appears on the screen?

We will go step by step and first of all, let’s start with understanding what happens after we launch the app. Xcode Debugger will be our best friend today. Let’s create empty UIKit Swift project in Xcode and put a break point into viewDidLoad. By default you will see something like this but you can expand the call stack it by tapping on button in the bottom-right side of Debug navigator.

Tap on this button and you will see much more details in the call stack.

NOTE: Probably obvious and well known fact but we could see here that our UI related code is happening on the main thread. UIKit is not thread-safe, you should work with it on main thread only.

UIApplicationMain

Let’s look on the bottom of the stack on previous screenshot:

What we see here is the main function. It is called by the operating system's runtime environment when your app launches. The process involves the system initializing your app's environment, setting up the app's main thread, and then calling the main function, which can be considered as an entry point for your app's execution .

For example, if you create an Objective-C (yep you still can) project in Xcode you will see something like this:

int main(int argc, char * argv[]) {
    NSString * appDelegateClassName;
    @autoreleasepool {
        // Setup code that might create autoreleased objects goes here.
        appDelegateClassName = NSStringFromClass([AppDelegate class]);
    }
    return UIApplicationMain(argc, argv, nil, appDelegateClassName);
}

Just imagine, all that happens inside your app, happens inside main function. It’s funny but your entire app is nothing but a single giant call of main function.

But main function itself doesn’t do much. It’s main purpose is to call UIApplicationMain() function.

NOTE: You can read more about UIApplicationMainhere and here

UIApplicationMain in it’s turn does a lot to setup our iOS app:

• creates the UIApplication shared instance and application delegate;

• runs the UIApplication that triggers creation of scene, scene delegate and etc;

• [MOST IMPORTANT FOR US NOW] It runs the main event loop by calling Runloop.run().

If you haven’t heard about Runloop so far, next chapter is for you.

Runloop

Simply speaking, Runloop is the infinite cycle of events happening in the app.

Runloop is the reason why main() and UIApplicationMain() calls will actually never return.

Every iteration Runloop has three main jobs to do:

• Handle the events;

• Notify observers about runloop’s state changes;

• Put the thread to a sleep when it have nothing to do.

NOTE 1: Similar to many other things in high-level frameworks like UIKit or Foundation, Runloop (aka NSRunloop) is like a Foundation side proxy for CFRunloop (CF stands for Core Foundation), created to hide some interface CFRunloop have like adding event sources, observers or a new runloop mode.

NOTE 2: You can read about the runloop iteration steps more here and here. If needed, you can find the detailed iteration steps directly in code here once Core Foundation is open-source.

NOTE 3: The Runloop is associated with a thread, with only one runloop linked to each thread. It automatically runs on the main thread from the app's start, but for other threads, you must explicitly run it.

NOTE 4: CFRunloop is thread-safe, but Runloop (NSRunloop) is not.

NOTE 5: You might be wondering how many runloop iterations occur per second. However, this question isn't correct to ask. The run loop frequency isn't fixed and isn't bound to the screen refresh rate either. The run loop frequency and the screen refresh rate operate independently. (Usually, run loop frequency surpasses potential screen refresh rates unless the main thread is blocked)

Runloop events

Runloop handles several different event types:

• Blocks of GCD main queue

• Timers

• Sources (0 and 1)

• Observers

If you place a breakpoint at nearly any line of code in your app, you'll likely encounter one of the functions listed below in the bottom of the call stack. These functions serve no purpose other than helping in debugging within the stack trace. RunLoop ensures that all main thread code is executed through one of these functions. They also allow you to understand the exact type of event processed by the runloop that triggered the execution of the code where you've set a breakpoint.

static void __CFRUNLOOP_IS_SERVICING_THE_MAIN_DISPATCH_QUEUE__();
static void __CFRUNLOOP_IS_CALLING_OUT_TO_A_BLOCK__();
static void __CFRUNLOOP_IS_CALLING_OUT_TO_A_TIMER_CALLBACK_FUNCTION__();
static void __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION__();
static void __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE1_PERFORM_FUNCTION__();
static void __CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__();

Main queue block or timer events are usually clear to developers who have ever created timer or used GCD main queue. Conversely, sources and observers hold more mystery regarding their usage and purpose. Let’s shed a light on them next.

Runloop Sources

Simply speaking, runloop source is just a way to say to runloop that some event happened at some other point of the app or even in the different process and runloop should handle this event by calling related callback. Sources allow the run loop to be aware of external events and handle them appropriately.

As you probably noticed there are 2 type of sources - source0 and source1. Not really a clear naming in terms of purpose, right? They named so because the version field of their context is 0 or 1.

But they serve different goals:

• Version 0 sources are for inner-app communication;

• Version 1 sources are for inter-process communication (IPC).

Version 0 sources (inner-app communication)

They managed by the application (kind of inner-app messaging mechanism). When a source is ready to fire, some other part of the application, perhaps code on a separate thread, must call CFRunLoopSourceSignal function to tell the run loop that the source is ready to fire so the related callback must be called. RunLoop must be awaken (with CFRunLoopWakeUp()) for the source to be handled.

Examples of version 0 sources are:

• performSelector(onMainThread:with:waitUntilDone:) of NSObject

• SFSocket.

• UIKit’s touch events fetching. If you put a break point into UIButton tap selector you will notice that UIEvent that triggered this action was fetched using version 0 source.

Version 1 sources (inter-process communication - IPC)

Version 1 sources managed by the kernel. These sources are automatically signaled by the kernel when a message arrives on the source’s Mach port. Mach ports are primarily a mechanism for inter-process communication (IPC) within the macOS and iOS operating systems. They allow processes (and our app is one of them) to send messages and data between each other.

CADisplayLink which can be used to synchronize your code to the display refresh rate, uses a type 1 source under the hood.

let displayLink = CADisplayLink(target: self, selector: #selector(update))
displayLink.add(to: .current, forMode: .common)

@objc func update() {
    print("Updating!")
}

• CFMachPort is another example of version 1 source.

• Even though mach ports are not used directly for network communication, they may be used internally by the operating system or by networking components to facilitate communication between processes, which can indirectly impact network-related functionality.

NOTE: You can also create custom sources for both versions 0 and 1 if needed.

Run Loop Observers

We already know from runloop iteration discussion that runloop has observers it needs to notify when runloop’s state has changed.

The CFRunLoopObserver API lets you observe the behavior of CFRunLoop and be notified of its activity: when it processes events, when it goes to sleep, etc.

You can associate run loop observers with the following CFRunLoopActivity events in your run loop:

• The entrance to the run loop. (kCFRunLoopEntry)

• When the run loop is about to process a timer. (kCFRunLoopBeforeTimers)

• When the run loop is about to process an input source.(kCFRunLoopBeforeSources)

• When the run loop is about to go to sleep. (kCFRunLoopBeforeWaiting)

• When the run loop has woken up, but before it has processed the event that woke it up. (kCFRunLoopAfterWaiting)

• The exit from the run loop. (kCFRunLoopExit)

You probably won’t ever need to create runloop observers in your app, but being aware of the existence and purpose of runloop observers can be useful for understanding how UIKit operates. But before we will try to understand connection between runloop observers and UIKit, we need to understand what is hidden behind the UIKit.

Under the hood of UIKit lies a lower-level framework called Core Animation, responsible for numerous aspects of UI, animations and rendering. Let’s look on CoreAnimation more closely now.

CoreAnimation

UIKit is a well known framework from Apple. We use it every day to create UI in our apps. UIKit contains all kinds of components. But surprisingly, UIKit delegates a significant portion of UI-related tasks such as animations, layout, and rendering to Core Animation under the hood.

Behind every UIView hides CALayer. When UIView is created it creates CALayer under the hood and sets itself as a CALayerDelegate which is responsible for several things such as providing the layer's content, subviews layout and animating property changes. For example, UIView is actually the reason why UIView properties are not animatable by default (opposite to CALayer), UIView disabled default animations as a CALayerDelegate to it’s layer. Properties and methods of UIView that somehow change the view appearance are actually just proxied properties of CALayer. For example, frame, bounds, backgroundColor or isHidden are actually proxied properties of CALayer.

NOTE: The several things that truly handled by UIKit are user interaction (like touches and gestures) and accessibility.

Views on the screen together create the view hierarchy or view tree.

Similarly, CALayers form the layer hierarchy in parallel with views, so behind the view tree, there exists a layer tree. In fact, Core Animation handles not only one layer tree but three of them:

• Model layer tree;

• Presentation layer tree;

• Render layer tree (not accessible from the app).

You can access model tree and presentation nodes by using model() and presentation() methods of CALayer.

Each layer tree has a different role in making the content of your app appear onscreen:

• Model layer tree (or simply “layer tree”) is the one your app interacts with the most. The objects in this tree are the model objects that store the target (final state) values for any animations. Whenever you change the property of a layer, you use one of these objects.

• Presentation tree contains the in-flight values for any running animations. Whereas the layer tree objects contain the target values for an animation, the objects in the presentation tree reflect the current values as they appear onscreen. You should never modify the objects in this tree. Instead, you use these objects to read current animation values, perhaps to create a new animation based at those values. You should access objects in the presentation tree only while an animation is in flight. While an animation is in progress, the presentation tree contains the layer values as they appear onscreen at that instant. This behavior differs from the model layer tree, which always reflects the last value set by your code and is equivalent to the final state of the animation.

• Render tree perform the actual animations and are private to Core Animation (not accessible from the app). It is the closest layer tree to the actual screen state.

REMEMBER: The presentation layer is not the original layer, just a temporary ‘ghost‘ layer. It is approximated state of render tree layer. Can be useful to use its current values to create new animations or to interact with layers while an animation is taking place.

NOTE: The initial structure of each tree matches the structure of the view hierarchy exactly. However, the app can add additional layer objects (layers not associated with a view) into the layer hierarchy if needed.

Ok, now we know that view we have 3 layer trees behind view tree but once the render tree is the closest tree to the screen state how changes of the model layer tree are actually applied to the render tree?

Important to understand that UI changes are not applied to be updated on screen every time something is changed. CoreAnimation groups changes to the layer tree into CATransaction - a mechanism for grouping multiple layer-tree operations into atomic updates to the render tree.

CATransaction

When we want to modify a layer and there are several properties that require changes, applying these changes one by one wouldn't be efficient due to optimization reasons. Even if we modify a property multiple times consecutively, Core Animation consolidates these updates into a single transaction update sent to the render tree.

But when and where exactly is this CATransaction happening? Do you remember I mentioned the connection between UIKit and Runloop observers? Well, it’s actually a connection between CoreAnimation and Runloop observers. The thing is that Core Animation observes the CFRunLoopActivity.kCFRunLoopBeforeWaiting event; when this event fires at the end of every runloop iteration, if any changes happened to model layer tree (like bounds changed or animations added), CoreAnimation groups a bunch of changes into single transaction (called implicitCATransaction ) and commits it to be applied to the render tree altogether at once. Implicit transaction is created only if there were changes to model layer tree.

If you put a breakpoint into layoutSubviews() method of your view, you will see that it is called from runloop observer callback function by discovering corresponding function on the call stack: __CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__();

Let’s update our scheme with several new steps:

CATransaction by examples

To understand CATransaction better lets consider few examples inspired by this cool post. Lets imagine we have a button with background color initially set to .red:

button.backgroundColor = .red
...
@objc func buttonTapped() {
    button.backgroundColor = .yellow // implicit transaction begins here
    sleep(3) // blocks the main thread for 3 seconds
    button.backgroundColor = .green
}

When we tap on button we:

• change the backgroundColor to .yellow

• blocks the main thread for 3 seconds with sleep() function

• change the backgroundColor to .green

How do you think this code will work?

It's not immediately clear why the yellow color wasn't visible, right? This occurred because after setting the yellow color and changing the model layer tree, we blocked the main thread, suspending the runloop iteration. So, the implicit CATransaction wasn't committed until a 3-second interval had elapsed. However, immediately after these 3 seconds, we changed the color to .green. This "green" change is committed with the implicit CATransaction at the runloop cycle's end. So the yellow color has never become visible.

Explicit transactions

We mentioned earlier that CoreAnimation sends implicit transaction on every runloop iteration but transaction can be also explicit if you create it in your code like this:

CATransaction.begin()
button.backgroundColor = .yellow
// change anything else here if you want
CATransaction.commit()

Any changes made to layer properties between CATransaction.begin() and CATransaction.commit() are grouped together and committed atomically.

NOTE 1: Explicit and implicit transactions are the same CATransaction. The only difference is that whether we begin and commit it manually or it is done automatically by CoreAnimation on any layer change.

NOTE 2: Now you know about begin and commit methods of CATransaction we can address implicit transaction logic with more details. An implicit transaction is begun by CoreAnimation when you change the layer tree for the first time during the current runloop iteration. It then groups any subsequent changes during the runloop iteration inside of this transaction. Finally, at the end of the current runloop iteration when kCFRunLoopBeforeWaiting fires, the implicit transaction is committed.

Let’s see how our previous example result will change with explicit transaction:

button.backgroundColor = .red
...
@objc func buttonTapped() {
    CATransaction.begin()
    button.backgroundColor = .yellow
    CATransaction.commit()
    sleep(3) // blocks the main thread for 3 seconds
    button.backgroundColor = .green // implicit transaction begins here
}

Now we see yellow color state. Cool, but why?

We committed the “yellow state” change with explicit transaction right before blocking the main thread so it was changed instantly after the tap. Then after 3 seconds we do “green state” change that goes with implicit transaction at the end of runloop cycle.

NOTE 3: You are probably wondering now what is the case for using explicit transaction. I guess it was more useful long time ago when UIKit animation API was not as developed as it is today. For example, animate(withDuration:) became available only since iOS 4. Before that, explicit transaction was a good way to commit animation and easily change the duration, timing function, or other parameters of animation. But actually, explicit transactions still can be useful today in some rare cases of animating layer and view properties together.

Nested transactions

Let’s update our example once again. Let’s put our explicit transaction inside another explicit transaction.

button.backgroundColor = .red
...
@objc func buttonTapped() {
    CATransaction.begin()
    CATransaction.begin()
    button.backgroundColor = .yellow
    CATransaction.commit()
    sleep(3) // blocks the main thread for 3 seconds
    button.backgroundColor = .green
    CATransaction.commit()
}

As you can see it produces the same result as the first example. No yellow state appeared.

That occurred because transactions can be nested. When one transaction is nested within another, the commit of the "internal" (child) transaction only takes effect when the parent commits. To better understand why nested transactions function this way, consider that transactions are managed by a transaction stack (LIFO - last in, first out). When you begin a transaction, it's added to the transaction stack, and upon committing, it's removed. If you insert several transactions inside transaction stack they become nested and those transaction(s) will really be committed when the stack becomes empty.

NOTE: Implicit transaction can’t be nested inside explicit one once implicit transaction begins when you change layer tree outside of explicit transaction. So it also means that implicit transaction can be added to the transaction stack only when the stack is empty.

Implicit transaction

Last example shows us how implicit transaction works.

button.backgroundColor = .red
...
@objc func buttonTapped() {
    button.backgroundColor = .white // implicit transaction begins here
    CATransaction.begin()
    button.backgroundColor = .yellow
    CATransaction.commit()
    sleep(3) // blocks the main thread for 3 seconds
    button.backgroundColor = .green
}

Looks very similar to the example with explicit transaction when yellow state was visible. Except one detail - we changed the model layer tree by assigning button.backgroundColor = .white first which triggered implicit transaction to begin so our explicit transaction was nested into implicit one and was not sent to the render tree until the implicit one was committed later. So that’s why we saw only green state after 3 seconds in this case.

NOTE 1: How many transactions created per runloop cycle?
0 - if nothing changed;
1 - if layer tree changed outside of explicit transaction OR 1 explicit transaction was created;
N+1 - if layer tree changed outside of explicit transaction AND N explicit transactions were created.

NOTE 2: You could notice that transaction has also a flush method. It commits any extant implicit transaction. Flush is typically called automatically at the end of the current runloop iteration, regardless of the runloop mode. You should attempt to avoid calling flush explicitly. By allowing flush to execute during the runloop your application will achieve better performance, atomic screen updates will be preserved, and transactions and animations that work from transaction to transaction will continue to function.

Next thing we need to understand is the phases of transaction.

Phases of transaction

The CATransaction commit method is separated in four phases:

1. Layout phase

2. Display phase

3. Prepare phase

4. Commit phase

All of them are actually happening inside CA::Transaction::commit() method. We can see this method inside the callstack if we put a breakpoint inside layoutSubviews() method of your view.

Lets go quickly over every phase.

Layout and display phases

In the screenshot above, you can observe the method CA::Layer::layout_and_display_if_needed(CA::Transaction*), responsible for executing two phases: Layout and Display. It's intuitive that the layout phase handles the layout update of the layer tree before the transaction is committed. Similarly, the display phase is responsible for updating the displayed contents within the layers. Core Animation initiates these phases before committing the transaction to ensure the layer tree's state is up-to-date and can be applied accurately to the render tree.

Both phases function in a similar manner. Core Animation traverses the layer tree using Depth-First Search (DFS), starting from the top superview (UIWindow) down to the bottom leaf layers. If the layer's corresponding flag (returned by needsLayout() / needsDisplay()) is activated, the layoutSublayers() / display() methods are called accordingly. These flags can be activated implicitly by modifying the layer's properties (such as bounds, for instance) or explicitly by invoking setNeedsLayout() / setNeedsDisplay().

NOTE: You don’t ever need to call layoutSublayers / display directly.

Layout phase

The layout methods in UIView, frequently used in UIKit - such as layoutIfNeeded, setNeedsLayout, and layoutSubviews essentially serve as proxies for the corresponding methods in CALayer. While UIKit incorporates additional logic to ensure the proper functioning of autolayout constraints, it consistently depends on CoreAnimation's fundamental layout process.

During the layout phase, Core Animation calls the layoutSublayers() method of CALayer from top to bottom on each layer within the current layer tree if they were invalidated by implicit or explicit changes to the needsLayout flag. Ultimately, at the completion of this chain execution, each layer acquires its final position and size.

If the entire layer tree is invalidated using setNeedsLayout(), during the traversal in the layout phase, layoutSublayers() will be invoked for every layer.

Most of the time tree is invalidated only partially. In that case layer tree will be fully traversed too but layoutSublayers() will be called only for invalidated layers (with needsLayout flag enabled).

As we mentioned above UIView sets itself as a CALayerDelegate of it’s backing layer.

Default implementation of layoutSublayers calls the layoutSublayers(of:) method of the layer’s delegate object if it is implemented.

UIView implements layoutSublayers(of:) method and calls UIView’s layoutSubviews() method, that you probably already familiar with and often use to customise layout of views.

extension UIView: CALayerDelegate {
    func layoutSublayers(of layer: CALayer) {
        layoutSubviews()
    }
}

layoutSubviews() is meant to help UIKit to support AutoLayout and it adds one addition step to layout phase - Constraints pass. This is the step UIKit does to solve constraints. It goes over the view tree bottom-up from leaf subviews to the root view and calls updateConstraints() method of the view if needsUpdateConstraints() returns true. It usually becomes true automatically when constraints where changed or if you call setNeedsUpdateConstraints() explicitly.

NOTE 1: layoutSubviews() do the constraints pass if needed every time it is called.

NOTE 2: One important difference of Constraints pass from layoutSublayers traversal logic is that it’s traversal is happening in opposite direction - bottom-up, from leafs to superview.

Display phase

During the display phase, Core Animation invokes the display() method of each layer within the current layer tree, proceeding from top to bottom (from super to sublayers). This method is responsible for updating the layer's content. By the end of this phase, every layer has its content refreshed. Subclasses have the option to override the display() method, utilizing it to directly set the layer's contents property.

The mechanism involving setNeedsDisplay and needsDisplay is the same as for the layout phase.

Let’s dive deeper into layer’s display logic:

• Default implementation of layer’s display calls the display(_ layer:) method of the layer’s delegate object if it is implemented.

• Otherwise this method creates a backing store (pixel bitmap, like an image) and calls CALayer's draw(in ctx: CGContext).

• draw(in ctx: CGContext) by default does nothing except calling CALayerDelegate's draw(layer: CALayer, in ctx: CGContext) if it is implemented to fill the backing store with content using Core Graphics for drawing via CGContext.

• UIView as a CALayerDelegate of it’s backing layer doesn’t implement display(_ layer:). But it implements draw(layer, in ctx: CGContext) where it calls UIView’s draw(rect:) method.

• Default implementation if UIView’s draw(rect:) does nothing. But can be overridden by subclasses to implement custom drawing with Core Graphics.

Understanding it all at once can be challenging. But the most important aspect here is that, in essence, UIKit empowers us to perform custom drawing using Core Graphics by overriding the draw(rect:) method. Let's build a diagram to create a clearer understanding:

Even if you have never known about display phase you probably used draw(rect:) for drawing custom graphics in custom components in your apps. You can draw lines and shapes in the Core Graphics context. For example you can draw 100 ellipses to see a torus like this:

override func draw(_ rect: CGRect) {
    guard let context = UIGraphicsGetCurrentContext() else { return }

    context.setLineWidth(1.0)
    context.setStrokeColor(UIColor.orange.cgColor)

    context.translateBy(x: frame.size.width / 2.0,
                        y: frame.size.height / 2.0)

    let numberOfEllipses = 100
    let amount = Double.pi * 2 / Double(numberOfEllipses)

    for _ in 1...numberOfEllipses {
        context.rotate(by: CGFloat(amount))
        let rect = CGRect(x: -(frame.size.width * 0.25),
                          y: -(frame.size.height / 2.0),
                          width: frame.size.width * 0.5,
                          height: frame.size.height)
        context.addEllipse(in: rect)
    }
    context.strokePath()
}

But custom graphics drawing is not the only case. For example, UILabel use display phase and draw(rect:) to draw text (calls drawText(in rect: CGRect) there). You can override draw(*rect:) method for label and you see no text drawn.

class CustomLabel: UILabel {
    override func draw(_ rect: CGRect) {
        // super.draw(rect)
    }
}

NOTE: Keep in mind that Core Graphics drawing is performed by the CPU. CoreGraphics draws in CALayer backing store - it is a bitmap data, that later will be pushed to the GPU.

Now we know that committing transaction triggers Layout and Display phases to happen. Layout an display are phases where updates to UI usually happen.

CATransactions actually has 2 more phases. Usually developers don’t interact with them but they are important because of what they do.

Prepare phase - does additional Core Animation work like image decoding (JPGs, PNGs) and image conversion (if in format not supported by GPU, e.g. index bitmap).

Commit phase - packages up layer tree and sends the transaction to the Render server to be applied to the render tree.

You probably noticed a new keyword here - Render server. Until this moment we didn’t discuss where exactly render tree is located. Surprisingly, not inside the application. Render tree is managed by separate process called Render server that issues drawing calls for the GPU using Metal. This process performs most of the magic of the Core Animation framework.

Render server

After transaction is committed it will be sent over IPC (Inter-Process Communication) to the Render server process.

NOTE: Render server for simplicity can be considered as Core Animation back end.

Maybe you were wondering when you debug your application why progress indicator is continuing to spin even though your application is paused. Now you can guess why - it is spinning in another process - Render Server. It will happen with any other animation as well. If you commit the transaction with animation added before you block your main thread, you will see how it continues to work.

Once render server receives the transaction, it decodes it to apply updates to render tree.

For every display update iteration render server need to provide next frame for the GPU so it does the following:

• Calculates the intermediate values for the render tree’s layers properties if related animation is in progress.

• Uses the Metal commands to perform the layer tree rendering.

  • NOTE: How Metal works is a great topic for the next post, but for now to explain it simply Metal has a commands queue and it puts commands there to be rendered by GPU.

• The output of rendering on GPU is a pixel bitmap to be shown on the screen.

So we can update our scheme of questions into the final state:

Recap

• UIApplicationMain:

  • main() is the app “entry point” called by the operating system's runtime environment during app launch. main function itself doesn’t do much. It’s main purpose is to call UIApplicationMain() function.

  • UIApplicationMain() manages app setup and runs the main event loop - Runloop.

• Runloop:

  • Infinite cycle managing app events.

  • Manages events handling - runloop Events:

    • GCD main queue blocks

    • timers

    • sources (version 0 and 1)

    • observers.

• CoreAnimation:

  • UIKit internally delegates UI-related work to Core Animation.

  • UIViews are backed by CALayers, handling rendering, layout, and animations.

  • CoreAnimation holds in parallel three layer trees: model tree, presentation tree, and render tree.

  • CoreAnimation renders our app view hierarchy at each run loop pass and not at each view hierarchy modification. To do so, it observes CFRunLoopActivity.kCFRunLoopBeforeWaiting event and begins an implicit CATransaction if layer tree was changed. In the end of every runloop iteration, CoreAnimation finally commits this transaction just before the thread is put to sleep.

• CATransaction:

  • CATransaction is Core Animation's tool for combining multiple layer-tree operations into atomic updates to the render tree.

  • Explicit Transactions can be created manually with begin and commit methods.

  • Transactions can be nested, but when nested within an ongoing transaction, changes within the nested one only commit when the parent transaction does.

  • Transactions consist of four phases: Layout, Display, Prepare, and Commit.

  • At the end of every runloop iteration CoreAnimation commits implicit CATransaction through IPC (Inter Process Communication) to another process - Render Server.

• Render Server:

  • The Render server manages the render tree and is responsible for animations and rendering.

  • The Render server uses Metal commands to perform the render tree rendering. The output of rendering on GPU is a pixel bitmap to be shown on the screen.

BONUS: if you like to have the full picture, here is a complete scheme:

ONE MORE BONUS: Best book about UIKit is… actually the book about Core Animation 🤣

• iOS Core Animation: Advanced Techniques by Nick Lockwood

It was published back in 2013 but it is still relevant if you want to master UIKit.

Thank you for reading and see you in the next post about SwiftUI.

NOTE: In this post, I assume you are already familiar with the concept of DI (but you can learn more about it from this post).

In SwiftUI, Apple introduces a slightly different approach to DI compared to traditional UIKit development. In this article, we will explore the fundamentals of how DI works in the context of SwiftUI.

SwiftUI - two chairs for DI

We will cover two different approaches for DI we have in SwiftUI:

• Constructor injection

• Environment injection

Let’s consider both options more carefully.

Constructor injection

This approach should already be familiar to you from previous posts. It is a reliable and widely-used method for implementing DI, which you likely have utilized extensively in iOS development prior to the introduction of SwiftUI.

class LoginViewModel {
    let authService: AuthenticationService

    init(authService: AuthenticationService) {
        self.authService = authService
    }
}

// Somewhere in your code later
LoginViewModel(authService: authservice)

This is a classic example of constructor injection, where the dependency is injected through the constructor (also known as the initializer).

Even though we may feel confident with this pattern, when we begin using views in SwiftUI, we realize that it becomes slightly more complex due to the various property wrappers available. However, the good news is that the main principle remains the same for views.

struct LoginView: View {

    @ObservedObject var viewModel: LoginViewModel

    var body: some View {
        <...>
    }
}

// Somewhere in your code later
LoginView(viewModel: vm)

Even though we didn't explicitly create the initializer to pass the viewModel into LoginView, Swift automatically generates the default initializer for view structs. However, you can still write your own initializer if needed. The same approach can be applied to any view dependency, regardless of its type or the property wrapper used.

Environment Injection

Environment injection allows us to inject dependencies into a view within the view hierarchy and access them from any lower-level view if necessary.

In fact, there are two property wrappers available for this purpose: @EnvironmentObject and @Environment.

• @EnvironmentObject enables the injection of an object of a specific type into the environment.

• @Environment allows the injection of dependencies using a key/value approach.

If this is still unclear, don't worry. We will provide examples to further explain these concepts.

EnvironmentObject

The @EnvironmentObject property wrapper allows you to inject an object instance, identified by its type, into the environment.

To inject a dependency using environment objects, follow these steps:

1. Create an instance of your dependency that conforms to the ObservableObject protocol (meaning it should be a class).

2. Inject the dependency into the environment by using the .environmentObject() modifier on the root view or an intermediate container view.

3. Access the injected dependency in any child view that requires it by using the @EnvironmentObject property wrapper.

class MyDependency: ObservableObject {
    <...>
}

@main
struct MyApp: App {
    let dependency = MyDependency() // 1: Create an instance

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(dependency) // 2: Inject the instance
        }
    }
}

struct ContentView: View {
    var body: some View {
        SubView()
    }
}

struct SubView: View {
    @EnvironmentObject private var myDependency: MyDependency // injected

    var body: some View {
        <...>
        // 3: Access the injected dependency in your view
    }
}

The @EnvironmentObject property wrapper proves to be extremely useful when dealing with complex views where you need to inject dependencies into the lowest view within the hierarchy. Unlike the constructor injection approach, which requires passing the dependency through multiple views in the chain, @EnvironmentObject simplifies the process significantly.

Important notes

NOTE 1: If you need to inject a value type, @EnvironmentObject is not suitable. It only works with ObservableObject. However, you can use @Environment for injecting value types.

NOTE 2: It's crucial to be cautious when using environment objects as their usage can be unsafe. If an object is not available in the environment because you forget to inject it, the app will crash. This scenario is similar to using reflection-based libraries like Swinject, where forgetting to register a dependency before resolving it leads to a crash in runtime. Therefore, make sure you use @EnvironmentObject carefully.

NOTE 3: The environment can hold only one type of environmentObject instance at a time. If you inject an object of the same type lower in the hierarchy, it will replace the old one.

Environment

The @Environment property wrapper allows you to inject key/value pairs into the environment.

Here's a summary of how you can use it:

1. Create an EnvironmentKey with a default value.

2. Add the value property to an extension of EnvironmentValues.

3. Inject the dependency into the environment by using the .environment(\.{key}, value) modifier on the root view or an intermediate container view.

4. Access the injected dependency in any child view that requires it by using the @Environment property wrapper with the corresponding key.

struct ValueKey: EnvironmentKey { // 1: Created EnvironmentKey
    static var defaultValue = 1
}

extension EnvironmentValues { // 2: Add EnvironmentValues property
    var value: Int {
        get { self[ValueKey.self] }
        set { self[ValueKey.self] = newValue }
    }
}

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.value, 123) // 3: Inject the dependency
        }
    }
}

struct ContentView: View {
    var body: some View {
        SubView()
    }
}

struct SubView: View {
    @Environment(\.value) var value // injected

    var body: some View {
        <...>
        // 4: Access the injected dependency in your view
    }
}

Important notes

NOTE 1: The @Environment property wrapper is particularly useful for accessing existing system-related values such as the app's appearance mode (light or dark), Core Data's managed object context, size classes, and more. Refer to the documentation for EnvironmentValues to see the full list of available properties. In this article, we focus more on injecting our own dependencies.

NOTE 2: With the @Environment property wrapper, you can add both value and reference types to the environment. This makes it more versatile compared to @EnvironmentObject.

NOTE 3: An @Environment dependency always has a default value, so if you forget to inject it at the root level, your app will not crash. This makes it more safe compared to @EnvironmentObject.

NOTE 4: @Environment injection can hold multiple instances of the same type but with different keys.

Recap

• Two approaches for dependency injection in SwiftUI were discussed: Constructor injection and Environment injection.

• Constructor injection involves injecting dependencies via the initializer, following a similar pattern as in traditional UIKit development.

• Environment injection allows for injecting dependencies into the view hierarchy and accessing them from any view lower in the hierarchy.

• The @EnvironmentObject property wrapper is used to inject an object of a specific type into the environment.

• The @Environment property wrapper is used to inject dependencies using key/value pairs.

Conclusion

Dependency Injection is a simple concept that can greatly benefit SwiftUI code, just like any other codebase. While there may be other approaches to DI in SwiftUI, mastering the two options described above is sufficient for effective DI implementation.

NOTE: In this post, I assume you are already familiar with the concept of DI (but you can learn more about it from my previous post referenced above).

Factory pattern

The Factory pattern is a design pattern commonly used in software development for object creation. It encapsulates the logic for creating objects within a separate class or method, based on specific parameters or conditions.

enum ViewFactory {
    static func createView() -> UIView {
        UIView()
    }
}
let view = ViewFactory.createView()

It allows to extract the object creation logic from the calling point and abides by Single Responsibility Principle. This helps to keep the object creation logic organized and centralized, making it easier to maintain, update, and test.

The Factory pattern promotes loose coupling between the client code and the objects being created. Clients only depend on the factory, not on concrete classes, which allows for easier maintenance and reduces the dependencies between different parts of the codebase.

Factory pattern for DI

Factories can be very useful for implementing DI in your application. For example, you can create a login screen with the factory and inject all required dependencies there:

protocol AuthService {}
enum AuthServiceFactory {
    static func create() -> AuthService {
        AuthServiceImpl()
    }
}
enum LoginScreenFactory {
    static func createLoginScreen() -> UIViewController {
        let authService = AuthServiceFactory.create()
        let loginVM = LoginViewModel(authService: authService)
        return LoginViewController(viewModel: viewModel)
    }
}
let loginVC = LoginScreenFactory.create()
// presenting your screen

As you can see, the factory creates all dependencies for this MVVM module and inject them so we have the view controller ready to present as a result.

You can use factories to create screens, services or anything you need in your application.

In smaller iOS applications, using factories can be a viable solution for DI. Factories can provide a simple and lightweight way to handle DI without the need for external third-party libraries or frameworks.

When it’s not enough?

While factories can be a suitable approach for managing dependencies in smaller iOS applications, they may not be sufficient for larger, more complex projects.

In large iOS projects with numerous dependencies and complex dependency graphs, managing dependencies through factories can become more challenging. You need to control the lifecycle of your dependencies to manage them properly and it’s not what we have out of the box with the factory pattern. On top of that, it would be useful to detect dependency cycles and mock dependencies easily for unit testing. Although it is possible to implement these features, it can be tricky, especially for those not familiar with how DI containers work under the hood.

Let’s summarize what we expect from a proper DI solution and what factories actually capable of:

• Compile-time safety

  When you do DI we expect it should be compile-time safe. This means that the code will not compile if there are any errors related to dependency injection, such as missing or mismatched dependencies, or if dependencies are not registered with the container. We want to avoid runtime crashes, and this can be accomplished by avoiding runtime resolvers like Swinject. As the application grows larger, it becomes increasingly difficult to ensure that all modules use only registered dependencies.

• Laziness

  We want our dependencies to be lazy. It means that objects are created and initialized when they are actually needed, rather than creating and initializing all objects at once on application start. This can help improve the performance of an application, as it reduces the amount of memory and processing power required at startup. This is especially important in larger applications, where there may be a large number of objects and dependencies to manage.

• Control the scope/lifecycle (+ easily reset the scope when needed)

  DI container should be responsible for creating and initializing objects, managing their state during runtime, and destroying them when they are no longer needed. It can help reduce memory usage by avoiding to let unused dependencies exist in memory and releasing other system resources when they are no longer needed.

• Easily mock/replace implementations for testing

  We expect that we will be able to easily substitute the real dependencies of an object with test-specific dependencies, known as mocks or test doubles. This can help isolate the behavior of an object or function during testing and ensure that it is functioning correctly.

• Detect dependency cycles

  We expect that it can identify situations where two or more objects have circular dependencies, where each object depends on another object in the cycle. This can be a problem because it can lead to infinite loops or other errors that can cause the application to crash. The larger an application grows, the more crucial it becomes.

Using the Factory pattern gives us only 2 out of 5 required features:

• ✅ Compile-time safety

• ✅ Laziness

• ❌ Control the scope/lifecycle

• ❌ Easily mock/replace implementations for testing

• ❌ Detect dependency cycles

How can we achieve all of them?

One option is to implement a custom solution, but a more straightforward approach is to use a ready-to-go solution. What if I tell you that the solution is a Factory again, but not the pattern but the library? - Factory library. Created in 2022, this library takes the factory pattern to the next level which I would call Factory pattern on steroids.

How to use Factory library

A simple example of using Factory:

extension Container {
    var service1: Factory<Service1> { 
        self { ServiceImpl1() }
            .singleton
    }
    var service2: Factory<Service2> { 
        self { ServiceImpl2(service1: self.service1()) }
    }
}
// you can use it like that later for DI 
let vm = ScreenViewModel(service1: Container.shared.service1(),
                         service2: Container.shared.service2())

Looks pretty and simple, right? You declare your dependencies as properties of the Container. You wrap your actual dependency into Factory type and simply address this property with () later to resolve the instance. It works due to the callAsFunction feature introduced in Swift 5.2.

Features

Let’s check our requirements list again for the Factory library:

• ✅ Compile-time safety

  • If you declare a Factory property, you can be certain that you will be able to resolve the instance.

• ✅ Laziness

  • As you can see, we used calculated properties there, that gives as laziness.

• ✅ Control the lifecycle/scope

  • Factory provides us with 5 scopes: Singleton, Cached, Shared, Graph, Unique.

  • You can create your own custom scopes.

  • You can reset individual scope caches.

• ✅ Using mocks for testing is so easy

  • Just register the mock to update the original instance

    struct ContentView_Previews: PreviewProvider {
        static var previews: some View {
            let _ = Container.myService.register { MockService2() }
            ContentView()
        }
    }

• ✅ Detect dependency cycles

  • Factory provides the ability to catch dependency graph cycles but only in runtime. When your dependency will be resolved more than dependencyChainTestMax = 8 times during one resolution cycle, the library will trigger the fatal error. Max value can be changed if needed.

On top of that, Factory is lightweight and easy to understand. It also provides cool InjectedObject property wrapper for SwiftUI views if you use it in your project.

What is under the hood?

As you noticed we have a Factory wrapper for the closure that creates the dependency instance as a result. It provides us with some syntactic sugar. We simply ask the enclosing container to make a properly bound Factory for us using self.callAsFunction { ... }.

extension Container {
    var sugared: Factory<MyServiceType> { 
        self { MyService() }
    }
    var formal: Factory<MyServiceType> { 
        Factory(self) { MyService() }
    }
    // result is the same for both properties
}

The Container is basically a namespace for the factory properties you can create in the extension.

Container owns the ContainerManager instance that manages the registration and scope caching storage mechanisms for a given container.

Factory is just a wrapper for FactoryRegistration instance inside it.

FactoryRegistration is used internally to manage the registration and resolution process.

public struct Factory<T>: FactoryModifying {
    public init(_ container: ManagedContainer, 
                key: String = #function, 
                _ factory: @escaping () -> T) {
        self.registration = FactoryRegistration<Void,T>(id: "\(key)<\(T.self)>",
                                                        container: container, 
                                                        factory: factory)
    }
}

As you can see in code, registration key is a concatenation of function name (property name in this case) and dependency type.

FactoryRegistration uses the corresponding scope to resolve the dependency. Scopes are basically different types of caches (Each scope has its own level of caching).

public struct FactoryRegistration<P,T> {
    internal func resolve(with parameters: P) -> T {
        ...
        return scope?.resolve(
            using: manager.cache, 
            id: id, 
            factory: { factory(parameters) }
        ) ?? factory(parameters)
    }
}

Scope stores factory closures in dictionaries by registration keys:

public class Scope {
    internal func resolve<T>(using cache: Cache, id: String, factory: () -> T) -> T {
        if let cached: T = unboxed(box: cache.value(forKey: id)) {
            return cached
        }
        let instance = factory()
        if let box = box(instance) {
            cache.set(value: box, forKey: id)
        }
        return instance
    }
}
extension Scope {
    final class Cache {
        typealias CacheMap = [String: AnyBox] // Dictionary for reflection
        func value(forKey key: String) -> AnyBox? {
            cache[key]
        }
        func set(value: AnyBox, forKey key: String)  {
            cache[key] = value
        }
    }
}

Factory implementation idea is quite similar to reflection based libraries like Swinject. Reflection means mapping a set of keys to a set of objects. So, for example, Factory and Swinject both use a Dictionary to map the keys (instance types) to values of instances.

Factory vs. Swinject

Factory library is similar to Swinject in terms of how it works under the hood. It is a reflection-based library.

But why then Factory is more preferable than Swinject?

The main reason to prefer Factory over Swinject is compile-time safety.

Swinject fully provides all other features that we expect from DI solution except compile-time safety and it is crucial. Swinject resolves instances on demand at runtime with no safety to avoid crashes.

On the contrary, Factory is compile-time safe.

There is a big difference in the approach of how they register and resolve instances.

When Swinject resolves the instance there is no guarantee that this instance was registered before that.

With Factory when you call the property as a function to resolve the instance, property declaration is already a guarantee that the instance was registered. This is why it is compile-time safe.

Recap

To summarize, using the Factory pattern can be a suitable solution for Dependency Injection in smaller iOS applications, as it provides a simple and lightweight way to handle DI without external third-party libraries or frameworks. However, for larger and more complex projects, managing dependencies through factories can become challenging, and it may not be enough to fulfill all the requirements of proper DI. While factories can ensure compile-time safety and laziness, they cannot control the scope or lifecycle of dependencies, nor easily mock or replace implementations for testing, nor detect dependency cycles. To address these issues, one can use a ready-to-go solution such as the Factory library, which can provide all the required features.

Factory pattern

• ✅ Compile-time safety

• ✅ Laziness

• ❌ Control the lifecycle (Control the scope/ easily reset scope when needed - scopes which allow for better memory management)

• ❌ Easily mock/replace implementations for testing

• ❌ Detect dependency cycles

Swinject

• ❌ Compile-time safety

• ✅ Laziness

• ✅ Control the lifecycle

• ✅ Easily mock/replace implementations for testing

• ✅ Detect dependency cycles (but only at runtime)

Factory library - nice new approach to DI for Swift and SwiftUI

• ✅ Compile-time safety

• ✅ Laziness

• ✅ Control the lifecycle

• ✅ Easily mock/replace implementations for testing

• ✅ Detect dependency cycles (but only at runtime)

Thank you for reading this post, hope it was useful.

The Swift documentation provides a comprehensive introduction to Closures. However, in this session, we will cover some interesting aspects of Swift closures that are not fully covered in the documentation.

DEFINITION: Closures are self-contained blocks of functionality that can be passed around and used in your code.

Closures take one of three forms:

• Global functions and class/struct/enum methods are closures that have a name and don’t capture any values.

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

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

NOTE: Function is a special case of closure.

NOTE: In the first two forms of closures listed above, the name actually refers to a function signature, which includes the function name and argument names.

The closure is a typed value and the type of closure is written like this:

(parameter-tuple) -> return-value

We can consider function declaration as a variable of closure type once the following are equivalent in Swift:

func isPositive(x: Int) -> Bool { return x > 0 }
let isPositive: (Int) -> Bool = { x in return x > 0 }

{ param in ... } - is called a closure expression.

Closure expressions can be considered as anonymous literals of closure type.

In the same way that 1234 and "hello" are integer and string literals. They’re also anonymous - they aren’t named. The only way they can be used is to assign them to a variable when they’re created, or to pass them to another function or method.

In the nutshell, closures provide a way to encapsulate a piece of functionality or behavior as a first-class object that can be passed around and used in different parts of your code.

How to create a reference cycle with closure?

The most dangerous thing about the closures is that you can create a reference cycle using them. Reference cycle (also known as a retain cycle) occurs when two or more objects hold strong references to each other, preventing them from being deallocated even when they're no longer needed. This can lead to memory leaks and negatively impact the performance of your app.

Let’s consider an example:

class TestObject {
    var counter = 0
    var closure: () -> Void = {}

    deinit {
        print("No reference cycles!") // will never be called
    }
}

var object = TestObject()

object.closure = {
    object.counter += 1 // reference cycle is created
}

In this example, object holds the reference to the closure and closure captures the reference to the object. Object will never be deallocated and deinit will never be called.

Now that we have identified the problem, let's explore some solutions to fix it.

class TestObject {
    var counter = 0
    var closure: () -> Void = {}

    deinit {
        print("No reference cycles!") // will be called at the end of the scope
    }
}

var object = TestObject()

object.closure = { [weak object] in // or [unowned object]
    object?.counter += 1
}

Expression [weak object] in the begining of the closure is called a capture list.

Using a capture list with a weak modifier tells the closure that the object will be captured by weak reference to avoid retain cycle creation. Let’s take a look on the capture list more closely.

What is a capture list?

When you define a closure, you can also specify a capture list, which tells the closure which variables and constants it should capture from the surrounding context.

DEFINITION: A capture list is simply a comma-separated list (or just an array) of variable or constant names, enclosed in square brackets, like this:

{ [variable1, variable2, variable3] in
    // class object variables will be captured by strong reference
    // closure code goes here
}

You can use weak or unowned modifiers to capture variables by weak or unowned reference correspondingly to prevent the retain cycle:

{ [weak variable1, unowned variable2] in
    // variable1 will be captured by weak reference
    // variable2 will be captured by unowned reference
    // closure code goes here
}

But what is the difference between weak and unowned?

Weak vs unowned

To prevent a retain cycle, you can use either the weak or unowned modifier. However, weak is generally considered safer because if the referenced object is deallocated, the weak reference becomes nil. On the other hand, an unowned reference would result in a runtime error.

Typically, unowned is used when there is a one-to-one relationship between two objects, and both are expected to be deallocated at the same time. However, using unowned is similar to using implicitly unwrapped optional. If the object is nil, a crash will occur. In general, it is recommended not to use the ! operator and this advice can be considered for unowned as well.

Even though unowned is faster and allows for immutability and non-optionality, weak is safer, and the performance gain from using unowned may not be as valuable, especially considering the risk of crashes. This is just my perspective, and ultimately, the choice of which modifier to use depends on the specific context and needs of the code.

Understanding capture lists

The concept of a capture list may appear straightforward, but there are nuances to consider.

One example is when capturing a value type in a capture list. In this case, the value type will be copied into the closure.

func returnClosureWithCapturedInteger() -> () -> Void {
    var counter = 0

    let closure = { [counter] in // capture list
        print("counter =", counter)
    }

    counter = 1
    closure() // counter = 0
    counter = 2
    closure() // counter = 0
    counter = 3

    return closure
}

let closure = returnClosureWithCapturedInteger()
closure() // counter = 0

As demonstrated, even though we captured the value of the counter and later changed it, the captured value remained equal to 0 when the closure was called. You can say that this is expected because value types are copied every time they are passed to a new location. However, what happens if we do not include the value type in the capture list?

In this case, the behavior is not as straightforward as in the previous example:

func returnClosureWithoutCapturedInteger() -> () -> Void {
    var counter = 0

    let closure = { // nothing in capture list
        print("counter =", counter)
    }

    counter = 1
    closure() // counter = 1
    counter = 2
    closure() // counter = 2
    counter = 3

    return closure
}

let closure = returnClosureWithoutCapturedInteger()
closure() // counter = 3

What happened in this case? Even though we did not capture counter in the capture list, we still used it within the closure.

In this scenario, the closure captures a reference to enclosing function context and counter inside it as well so closure can use it within its own body. By capturing context by reference, the closure ensures that the counter does not disappear after the call to returnClosureWithoutCapturedInteger ends and counter remains available the next time the returned closure() is called. This means that when we change counter later and call the closure, the updated version of counter is printed, even though it should not exist anymore as a local variable.

What about capturing reference type?

When it comes to reference types, the outcome will be the same regardless of whether you include them in the capture list or not. However, it's recommended to capture reference types in the capture list as it's the only way to resolve any reference cycles that may be created when capturing reference values. As mentioned earlier, it's advisable to always use a capture list with a weak or unowned modifier to prevent reference cycles and ensure safe memory management.

Understanding escaping/non-escaping

When closures are passed as arguments to a function, they need to be marked as @escaping to indicate the possibility of reference cycles. This annotation serves as a warning to the developer using the function. If closure is stored to be called later, it is considered escaping, while closures that don't leave the function's local scope are non-escaping. When using escaping closures, the compiler requires explicit usage of self in closure expressions to prevent unintentional strong capturing of self, which can cause reference cycles. Non-escaping closures cannot create permanent reference cycles since they are automatically destroyed when the function they're defined in returns.

By default, closures passed as function arguments are non-escaping. Remember that this default only applies to function parameters, and functions used as parameters in tuples or optionals are automatically marked as escaping. Therefore, a function that takes a function argument where the parameter is both optional and non-escaping cannot be written.

NOTE: @escaping is explicit signal of potential creating of reference cycles

Nested functions

As was already mentioned, nested functions are closures as well. This means the nested function captures variables from the surrounding context as well.

func returnNestedFunction() -> () -> Void {
    var counter = 0

    func nestedFunc() -> Void {
        print("counter =", counter)
    }

    counter = 1
    nestedFunc() // counter = 1
    counter = 2
    nestedFunc() // counter = 2
    counter = 3

    return nestedFunc
}

var nestedFunc = returnNestedFunction()
nestedFunc() // counter = 3

As you can see nested function works in the same way as closures without capture list. Nested function captures a reference to enclosing function context so when we change counter later and call the closure, the updated version of counter is printed.

Unobvious cases of retain

Capturing the object in closure not the only way you can introduce reference cycle in your code.

class AlertView {
    var buttonTapped: (() -> Void)?
}

class ViewController {
    let alert: AlertView

    init() {
        alert = AlertView()
        alert.buttonTapped = buttonTapped // self will be captured!!!
    }

    func buttonTapped() {}

    deinit {
        print("No reference cycles!") // Will never be called
    }
}

let vc = ViewController()

The alert.buttonTapped = buttonTapped line looks like an innocent assignment, but beware: we’ve just created a reference cycle! Every reference to a method of an object (like buttonTapped in the example) implicitly captures the method's self object.

When the AlertView object calls the closure that’s stored in its buttonTapped property, the property must somehow know which object’s instance method it needs to call - it’s not enough to just store a reference to ViewController.buttonTapped method without referencing the instance. If ViewController object will be deallocated at some moment AlertView object will lose access to the method. This is why it captures the self in this case.

Under the hood, instance methods are modeled as closures that, given an instance, return another closure that then operates on the instance. Implicit type of the expression ViewController.buttonTapped is actually (ViewController) -> (Int) -> ().

And vc.buttonTapped is actually just another way of writing ViewController.buttonTapped(vc).

Both expressions return a closure of type (Int) -> (), and this closure strongly captures the vc instance.

In this scenario, to avoid a strong reference retaining, you need to wrap the method call in another closure that captures the object weakly:

alert.buttonTapped = { [weak self] index in
    self?.buttonTapped(atIndex: index)
}

Is closure reference or value type?

In Swift, reference types are not limited to classes only. Functions and closures are also considered reference types.

Unlike value types, which are stored in the stack, reference types are stored in the heap. Hence, closures are also stored in the heap. Additionally, any captured value type is moved to the heap so that the closure can access it for the duration of its lifetime.

func makeIncrementer(forIncrement amount: Int) -> () -> Int {
    var runningTotal = 0
    func incrementer() -> Int {
        runningTotal += amount
        return runningTotal
    }
    return incrementer
}

This is an example from the Swift book and as you can already guess:

• incrementer as a closure and it will be stored in the heap.

• runningTotal is a value type but it will be moved to the heap as well.

Recap

• Closures are blocks of functionality that can be passed around and used in your code;

• Function is a special case of closure;

• You can create a retain cycle using closures;

• You can use capture list and weak/unowned modifiers to prevent a retain cycle.

• Closure can catch value type by reference or copy it;

• @escaping is an explicit signal of potential creating of reference cycles;

• Nested functions are closures as well;

• You should be careful with assigning a class method to closure because it retains the class object as well;

• Closure is a reference type.

Conclusion

Overall, closures are powerful and essential tool for Swift developers, and understanding how to use them effectively can significantly reduce problems that can be introduced in your app in process of development.

Even though we discussed a lot about closures in this post, there are still a lot of things we didn’t cover that you can read about like for example multiple trailing closures(Swift 5.3) and autoclosures.

Links

https://docs.swift.org/swift-book/documentation/the-swift-programming-language/closures/

FRP is a combination of functional and reactive programming that manages time-varying values, such as user inputs and server responses, in a clear and straightforward way. In FRP, values and events are represented as streams of values that change over time, and reactive functions are used to show how changes in input streams affect output streams. The aim of FRP is to provide a straightforward method for describing the behavior of a system over time.

Observer pattern

A good way to start comprehending Combine is by familiarizing oneself with the Observer design pattern.

The Observer pattern allows an object, called the Subject (aka Observable aka Publisher), to notify a set of dependent objects, called Observers (aka Subscribers), about changes in its state.

An example should help clarify the concept:

protocol Observer: AnyObject {
    func update(value: Int)
}

protocol Subject {
    func addObserver(_ observer: Observer)
    func removeObserver(_ observer: Observer)

    func notifyObservers()
}

class ConcreteObserver: Observer {

    let id: String // printed in console to identify observers 

    init(id: String) {
        self.id = id
    }

    func update(value: Int) {
        print("\(id): Value changed to \(value)")
    }
}

class ConcreteSubject: Subject {

    private var observers: [Observer] = []

    private var value: Int = 0 {
        didSet {
            notifyObservers()
        }
    }

    func addObserver(_ observer: Observer) {
        observers.append(observer)
    }

    func removeObserver(_ observer: Observer) {
        if let index = observers.firstIndex(where: { $0 === observer }) {
            observers.remove(at: index)
        }
    }

    func notifyObservers() {
        observers.forEach { $0.update(value: value) }
    }

    func setValue(value: Int) {
        self.value = value
    }
}

let subject = ConcreteSubject()
// Subject will add observers to notify them 
// later about it's value change

let firstObserver = ConcreteObserver(id: "First")
let secondObserver = ConcreteObserver(id: "Second")

subject.addObserver(firstObserver)

subject.setValue(value: 1)
// First: Value changed to 1

subject.addObserver(secondObserver)

subject.setValue(value: 2)
// First: Value changed to 2
// Second: Value changed to 2

// remove observer to stop notifing this observer about value changes
subject.removeObserver(firstObserver)

subject.setValue(value: 3)
// Second: Value changed to 3

The Observer pattern establishes a one-to-many relationship between the subject and its observers, such that any changes in the subject are automatically notified to all its observers.

The Observer provides a way to achieve loose coupling between objects in a system, allowing objects to interact without having direct references to each other. This makes it easier to add or remove observers, as well as to modify the subject or observer objects independently, without affecting the rest of the system.

The Observer allows you to follow the Open/Closed Principle. You can introduce new subscriber classes without having to change the publisher’s code and vice versa.

TIP: You can consider Combine as the advanced Observer (or Observer on steroids).

Let's take a look at a simple example of the Observer pattern implemented using Combine:

let subject = CurrentValueSubject<String, Never>("Hello World!")

subject.sink { // addObserver and get current value via the closure
    print("Value:", $0)
} 
// Value: Hello World!

subject.value = "Brand New World!"
// Value: Brand New World!

As you can see it is very similar and easy to use, maybe even easier than our Observer implementation above. Combine allows you not only to subscribe for data updates but also to use different operators to manipulate the stream of updates. In this example we will map the value from the subject to the new one:

let subject = CurrentValueSubject<String, Never>("Hello World!")

subject
    .map {
        $0 + " Here I am!"
    }
    .sink {
        print("Value:", $0)
    }
// Value: Hello World! Here I am!

Core concepts

There are three core Combine concepts: Publisher, Subscriber and Operator. You already know about publishers and subscribers from the Observer pattern example above but let’s look at them more deeply from the Combine perspective.

Publisher

protocol Publisher {
    associatedtype Output
    associatedtype Failure : Error

    func receive<S>(subscriber: S) where S : Subscriber, Self.Failure == S.Failure, Self.Output == S.Input
}

The Publisher is a protocol describing an object which can transmit values over time. It is generic over two types:

• Publisher.Output is the type of the output values of the publisher. If it’s an Int publisher, it can never emit a String or a Data value.

• Publisher.Failure is the type of error the publisher can throw if it fails. If the publisher can never fail, you specify that by using a Never failure type.

As you can see, every publisher must be able to receive new subscribers so you need to implement the receive method, in which you are given access to the Subscriber when it subscribes to the publisher.

Subscriber

protocol Subscriber {
    associatedtype Input
    associatedtype Failure: Error

    func receive(subscription: Subscription)
    func receive(_ input: Self.Input) -> Subscribers.Demand
    func receive(completion: Subscribers.Completion<Self.Failure>)
}

The subscriber’s Subscriber.Input and Subscriber.Failure associated types must match the Publisher.Output and Publisher.Failure types declared by the publisher.

Subscribers are usually created implicitly using 2 methods of Publisher protocol:

• sink (closure);

• assign (bind key path).

publisher
    .sink(
      receiveCompletion: {
        print("Received completion", $0)
      },
      receiveValue: {
        print("Received value", $0)
      }
    ) // closure based

publisher
     .assign(to: \.value, on: object) // assign to objects KeyPath

publisher
     .assign(to: &object.$value) // assign to publisher

Apple provides the classes Sink and Assign which implement the Subscriber protocol, but you'll likely never need to create them manually. These objects are created under the hood in the sink and assign methods and they are returned as type-erased AnyCancellable objects, allowing you to cancel the subscription without knowing the details about the subscription.

class Sink<Input, Failure>: Subscriber, Cancellable where Failure: Error {
    // Subscriber
    func receive(subscription: Subscription)
    func receive(_ value: Input) -> Subscribers.Demand
    func receive(completion: Subscribers.Completion<Failure>)

    // Cancellable
    func cancel()
}

You can read more about type erasures in Swift here if you want.

class AnyCancellable: Cancellable, Hashable { // type erasure
    func cancel()
}

Memory Management

With the help of the Cancellable protocol, you don’t need to specifically memory manage a subscription. You saw that your subscription code returns a Cancellable object. Whenever you release that object from memory, it cancels the whole subscription and releases its resources from memory. This means you can easily “bind” the lifespan of a subscription by storing it in a property on your view controller, for example. This way, any time the user dismisses the view controller from the view stack, that will deinitialize its properties and will also cancel your subscription.

let cancellable1 = publisher
    .sink {
        print("Received value", $0)
    }

let cancellable2 = publisher // assign to objects KeyPath
     .assign(to: \.value, on: object)

cancellable1.cancel() // cancel the subscriprion
// cancellable2 will be cancelled when local variable cancellable2 stops to exist

To automate this process, you can just have a Set<AnyCancellable> property and throw as many subscriptions inside it as you want. They’ll all be automatically canceled and released when the property is released from memory. (And this is why AnyCancellable conforms to Hashable - to store it in a Set).

var cancellables = Set<AnyCancellable>()

publisher
    .sink {
        print("Received value", $0)
    }
    .store(in: &cancellables)

publisher // assign to objects KeyPath
    .assign(to: \.value, on: object)
    .store(in: &cancellables)

NOTE: The assign(to:) (second one) method doesn’t return an AnyCancellable token, because it manages the lifecycle internally and cancels the subscription when the @Published property deinitializes (we will discuss @Published later in this post).

Subject

Subject is an extended publisher which knows how to send values into a stream, by calling its send(_:) method. Subject also has methods to send completion and subscription to the subscribers. Subject can be useful for adapting existing imperative code to the Combine model.

protocol Subject<Output, Failure>: AnyObject, Publisher {
    func send(_ value: Self.Output)
    func send(completion: Subscribers.Completion<Self.Failure>)
    func send(subscription: Subscription)
}

In your daily work instead of implementing the Publisher or Subject protocols yourself, you can create a publisher by using one of several types provided by the Combine framework:

1. Use a concrete subclass of Subject, such as PassthroughSubject, to publish values on-demand by calling its Subject.send(_:) method.

2. Use a CurrentValueSubject to publish whenever you update the subject’s underlying value.

3. Add the @Published property wrapper to a property. In doing so, the property gains a publisher that emits an event whenever the property’s value changes.

4. Use one of Apple’s Convenience Publishers like Empty, Just, Deferred or Future.

We will take a look at them in practice a little bit later.

Subscription

protocol Subscription: Cancellable {
    // Tells a publisher that it may send more values to the subscriber.
    func request(_ demand: Subscribers.Demand)
}

Subscription is the protocol representing the connection of a subscriber to a publisher.

Subscription.request method is needed to provide demand for new values. After publisher calls Subscriber.receive(subscription:) to give the subscription to the subscriber, the subscriber can use this subscription to tell a publisher that it may send more values.

Subscription is cancellable. The subscription is canceled after you call cancel() of the subscriber. Canceling a subscription frees up any resources previously allocated.

TIP: You can only cancel a Subscription once.

Lifecycle of subscription

1. The subscriber subscribes to the publisher.

2. The publisher creates a subscription and gives it to the subscriber.

3. The subscriber requests values via subscription.

4. The publisher sends values.

5. The publisher sends a completion.

TIP: Once a publisher emits a completion event (whether it’s a normal completion or an error), it’s finished and can no longer emit any more events.

Publishers in practice

Let’s take a look at publishers provided by Apple out of the box.

PassthroughSubject

PassthroughSubject allows you to publish new values on demand (when the subject asked to send them). Use send method to send the new values to the subscribers.

let subject = PassthroughSubject<Int, Never>()

let subscription = subject.sink {
    print("Received value:", $0)
}

subject.send(1) // Received value: 1
subject.send(2) // Received value: 2

CurrentValueSubject

CurrentValueSubject stores the current value. It broadcasts the current value to subscribers whenever they subscribe. Calling send(:) on a current value subject is one way to send a new value. Another way is to assign a new value to its value property. You still need to send completion events by using send(completion:).

let subject = CurrentValueSubject<Int, Never>(0)

let subscription1 = subject.sink {
    print("Subscriber 1 received value:", $0)
} 
// Subscriber 1 received value: 0

subject.send(1) 
// Subscriber 1 received value: 1

let subscription2 = subject.sink {
    print("Subscriber 2 received value:", $0)
} 
// Subscriber 2 received value: 1

subject.value = 2 // Same if call send(2) 
// Subscriber 1 received value: 2
// Subscriber 2 received value: 2

@Published

@Published is a property wrapper that allows you to easily turn a property into a publisher.

class MyClass {
    @Published var myValue: Int = 0
}

let myInstance = MyClass()

myInstance.$myValue.sink {
    print("new value:", $0)
}
// new value: 0

myInstance.myValue = 1
// new value: 1

Basically, @Published is very similar to CurrentValueSubject. It can be more simple in use sometimes and is intended to be used in SwiftUI. However, there are some differences:

• @Published fires on willSet of its wrapped property, while CurrentValueSubject fires on didSet;

• @Published is not supported in a protocol declaration;

• @Published is class-constrained, you can only use it in classes.

Hot and cold signals

In reactive programming, hot and cold signals are two types of signals that describe the behavior of data streams.

A hot signal is a signal that starts emitting events as soon as it is created, regardless of whether there are any subscribers. For example, a hot signal could be a continuous stream of data from a sensor, such as the accelerometer of a device, or a live feed from a stock market.

In contrast, a cold signal is a signal that only starts emitting events when there is a subscriber. When the subscriber cancels its subscription, the signal stops emitting events. For example, a cold signal could be a file download, where the download only starts when a subscriber subscribes to the signal and stops when the subscriber cancels its subscription.

The distinction between hot and cold signals is important because it affects the behavior of subscribers, and the way events are emitted and processed. It can be useful to know about a hot and cold signal when you try to understand or explain how a specific data stream works.

TIP: CurrentValueSubject and PassthroughSubject are hot signals.

Just

Just is a publisher that emits an output to each subscriber just once after the subscription and then it completes. Just can’t fail with an error.

let justPublisher = Just("Hello World")

justPublisher
    .sink {
         print("First subscriber", $0)
     }
// First subscriber Hello World

justPublisher
    .sink {
         print("Second subscriber", $0)
     }
// Second subscriber Hello World

TIP: Just is an example of a cold signal in Combine.

For example, it can be useful in writing stubs for your unit tests when you need to mock the method that returns a publisher.

Futures

Futures in Combine is another example of a cold publisher. A future is a publisher that emits a single value or an error on a new subscription and then completes.

It does this by invoking a closure when a value or error is available, and that closure is, in fact, the promise. If the promise will not be called, the subscriber never gets the value.

let future = Future<String, Never> { promise in
    print("First future started")
    promise(.success("First success"))
}
// First future started

future.sink { value in
    print(value)
}
// First success

let future2 = Future<String, Never> { promise in
    print("Second future started")
    // promise is not called
}
// Second future started

future2.sink { value in
    print(value) // will never be called
}

TIP: Future is greedy, meaning executes as soon as it’s created and doesn’t wait for a subscription. It does not require a subscriber like regular publishers that are lazy.

TIP: Future does not re-execute its promise; instead, it replays its output.

Futures are great to use for network requests because it’s a great abstraction to the asynchronous nature of network requests that can succeed with value or fail. By using futures, you can ensure that the network request is only made once, even if multiple parts of your application need the data.

enum NetworkError: Error {
    case invalidResponse
    case decodingError
}

struct User: Decodable {
    let name: String
    let email: String
}

func fetchUser() -> AnyPublisher<User, NetworkError> {
    Future { promise in
        guard let url = URL(string: "<https://api.example.com/user>") else { return }

        URLSession.shared.dataTask(with: url) { data, response, error in
            if let error = error {
                promise(.failure(error))
                return
            }
            if response.statusCode != 200 {
                promise(.failure(NetworkError.invalidResponse))
                return
            }
            do {
                let user = try JSONDecoder().decode(User.self, from: data)
                promise(.success(user))
            } catch {
                promise(.failure(NetworkError.decodingError))
            }
        }.resume()
    }
    .eraseToAnyPublisher()
}

You probably noticed something new in the code above - AnyPublisher.

AnyPublisher

AnyPublisher is a type-erased struct that conforms to the Publisher protocol. It allows you to hide details about the publisher that you may not want to expose to subscribers, which is good for encapsulation and user access control. It does the same job for Publisher as AnyCancellable for Subscriber.

TIP: AnyPublisher does not have a send(_:) operator or value property, so you cannot add new values to that publisher directly.

You can call eraseToAnyPublisher() operator to map your publisher to AnyPublisher and erase its type.

Operators

Combine operators are a set of functions provided by Apple that allow you to process and transform streams of values over time. These operators can be intuitive and already known to you from using Swift like filter, map, first and etc. But operators can be also quite complex and hard to understand. Will will take a look at some of them.

Each operator is the function in the Publisher extension:

extension Publisher {
    // map operator
    func map<T>(_ transform: @escaping (Self.Output) -> T) -> Publishers.Map<Self, T>
}

As you can see it returns Publishers.Map as a result.

Publishers is the enum and it is the namespace for publishers structs like Map.

struct Map<Upstream, Output>: Publisher where Upstream: Publisher {

    typealias Failure = Upstream.Failure

    // The publisher from which this publisher receives elements.
    let upstream: Upstream

    // The closure that transforms elements from the upstream publisher.
    let transform: (Upstream.Output) -> Output

    // Creates a publisher that transforms all elements from the upstream publisher with a provided closure.
    public init(upstream: Upstream, transform: @escaping (Upstream.Output) -> Output)

    // Attaches the specified subscriber to this publisher.
    public func receive<S>(subscriber: S) where Output == S.Input, S: Subscriber, Upstream.Failure == S.Failure
}

As you might guess already, under the hood, operators create a new publisher that transforms the elements from the upstream publisher and returns this new publisher as the result. This explains why you can chain many operators in a row.

To give you a quick introduction, we'll focus on some of the most useful examples of operators. I won't go into detail about all of them, as there are many, but I'll provide the best use cases that you're likely to encounter in your daily work.

flatMap

The flatMap is used to transform a stream of values into a new stream of values. It works by taking the values emitted by one publisher and transforming them into new publishers using a closure.

The most common use case for flatMap is network requests. For example, you might have a publisher that emits API request, and you want to make another API request when the initial one completes.

In the example below we call the getUserData request when authenticateUser request completes. So flatMap can be very useful to chain the API requests.

struct API {
    typealias Token = String

    func authenticateUser(userId: Int) -> AnyPublisher<Token, Error> {
        return Future<Token, Error> { promise in
            // Simulate a network request
            DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) {
                promise(.success("Token"))
            }
        }
        .eraseToAnyPublisher()
    }

    func getUserData(token: Token) -> AnyPublisher<Data, Error> {
        return Future<Data, Error> { promise in
            // Simulate a network request
            DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) {
                promise(.success(Data()))
            }
        }
        .eraseToAnyPublisher()
    }
}

var cancellable = Set<AnyCancellable>()
let api = API()

api.authenticateUser(userId: 1234)
    .flatMap { token in
        api.getUserData(token: token)
    }
    .sink(receiveCompletion: { completion in
        // handle error if needed
    }, receiveValue: { data in
        // handle user data
    })
    .store(in: &cancellable)

combineLatest

combineLatest is used to combine the latest values from multiple publishers into a single publisher. The resulting publisher emits a tuple of the latest values from each of the input publishers whenever any of the input publishers emits a new value.

A common use case for combineLatest is in user interface development, where you want to update the UI based on multiple values that are changing over time. For example, you might have two publishers, one that emits the user's current location and one that emits the user's current heading. You can use combineLatest to combine the latest values from these publishers and update the UI with the combined information.

Another use case for combineLatest is in data processing, where you want to process multiple streams of data in parallel. For example, you might have two publishers that emit data from different sensors, and you want to process the data in real time as it arrives. You can use combineLatest to combine the latest values from these publishers and process the data in a single stream.

Imagine that you have two text fields with first name and family name and you need to get a full name when the user changes one of them. It can be easily done with combineLatest :

let firstNamePublisher = CurrentValueSubject<String, Never>("John")
let familyNamePublisher = CurrentValueSubject<String, Never>("Snow")

firstNamePublisher
    .combineLatest(familyNamePublisher)
    .sink { firstName, familyName in
        print(firstName, familyName) // prints: John Snow
    }

TIP: combineLatest emits the tiple only when both of combined publishes emitted at least one value.

merge

The merge operator is used to merge the values from multiple publishers into a single publisher, but it doesn’t emit a tuple, values are merged in the single flow.

A common use case for merge is when you might want to get data from multiple sources (API, WebSocket, cache, UI events) in parallel, and you don’t care which one will happen first, all you need is the event. It will not wait for events from both sources as combineLatest does. First comes - first received as a new value.

let apiPublisher = PassthroughSubject<String, Error>()
let websocketPublisher = PassthroughSubject<String, Error>()

apiPublisher
    .merge(with: websocketPublisher)
    .sink { completion in
         // handle the error if needed
     } receiveValue: { value in
         print("Merged value recieved:", value)
     }

apiPublisher.send("New value")
// Merged value recieved: New value
websocketPublisher.send("Another value")
// Merged value recieved: Another value

share

share is a useful operator that enables you to share a single subscription to a publisher among multiple subscribers, which can help to reduce resource usage and improve the efficiency of your reactive programming system. For example, by using share, you can ensure that the network request is only decoded to the domain model once, even if multiple parts of your application need the data.

let request = api.makeRequest()
    .map { data in
        // called only once with share
        try? JSONDecoder().decode(MyDecodable.self, from: data) 
    }
    .share()

// one place
request
    .sink(...)

// another place
request
    .sink(...)

TIP: Also note that Publishers.Share is a class rather than a structure like most other publishers. This means you can use this operator to create a publisher instance that uses reference semantics.

Conclusion

In conclusion, Combine offers a robust collection of tools for implementing reactive programming in Swift and working with asynchronous events. However, a solid understanding of reactive programming is still necessary, and there is a steep learning curve to master Combine. It is important to use it responsibly and not blindly. Keep in mind the phrase, "With great power comes great responsibility.”

What's next? Although we have covered a lot of information about Combine in this article, if you want to take your understanding of it to the next level, I would recommend reading the Kodeco book for a deeper understanding.

Apple provided an easy-to-use solution since iOS 15 with UISheetPresentationController.

let vc = UIViewController()
// can also use .formSheet and result will be the same on the iPhone
vc.modalPresentationStyle = .pageSheet
if
    #available(iOS 15.0, *),
    let sheet = vc.sheetPresentationController
{
    sheet.detents = [.medium(), .large()]
}
present(vc, animated: true, completion: nil)

But on iOS 15 UISheetPresentationController was able to show the bottom sheet only with 2 sizes (detents):

• large (almost full-screen height);

• medium (approximately half of the screen height).

Check this post for more information.

Only since the iOS 16 it became possible to create custom detents with specific preferred heights.

let smallDetentId = UISheetPresentationController.Detent.Identifier("small")
let smallDetent = UISheetPresentationController.Detent.custom(identifier: smallDetentId) { context in
    return 100
}
sheetPresentationController?.detents = [smallDetent, .medium(), .large()]

Using custom detents has given developers more flexibility in implementing bottom sheets in their apps, but it is still not perfect. The pageSheet and formSheet styles on iPads look different than they do on iPhones (as modals), which can be an issue if you want your component to have the same appearance on all devices. Additionally, the size of the bottom sheet is not automatically determined by its content size, which would be more convenient. Today, let's explore how to implement a desired bottom sheet using UIKit.

(It would be interesting to implement it with SwiftUI as well, but most of the apps still use UIKit, so we will do it with SwiftUI in one of the next articles).

Quick Intro

If you want to implement Bottom Sheet using custom transition, you need:

1. Set its modalPresentationStyle property to custom;

2. Assign an object that conforms to UIViewControllerTransitioningDelegate protocol to transitioningDelegate property of UIViewController you want to present.

let vc = ExampleViewController()
vc.modalPresentationStyle = .custom
vc.transitioningDelegate = delegate // UIViewControllerTransitioningDelegate
present(vc, animated: true)

UIViewControllerTransitioningDelegate is a protocol in UIKit that defines methods for supporting custom transitions between view controllers.

TIP: The property transitioningDelegate of the controller is weak, so it is necessary to additionally retain the object with a strong reference.

To implement your transitioning delegate object, you will need to provide to UIKit with different objects related to the animation process, interaction and presentation, such as:

1. Transition animator object that conforms to the UIViewControllerAnimatedTransitioning protocol and is responsible for performing the actual animation for the transition.

   (TIP: You can even provide separate animator objects for presenting and dismissing the view controller).

2. Interactive animator object that conforms to the UIViewControllerInteractiveTransitioning protocol optionally if you want to use touch input or other user interactions to control the timing of the animation.

3. The UIPresentationController object is used to manage the presentation and dismissal process, including the position, size, and certain aspects of the presentation, such as displaying a shadow view during a custom transition. The presentation controller acts as a container for the presentation and its lifespan extends beyond the animator objects involved in the presentation, making it very useful in the transition process.

Let’s go to the code

Let’s see how we can implement all objects described above.

class BottomSheetTransitioningDelegate: NSObject, UIViewControllerTransitioningDelegate {

    let transition: BottomSheetTransition    

    func animationController(
        forPresented presented: UIViewController,
        presenting: UIViewController,
        source: UIViewController
    ) -> UIViewControllerAnimatedTransitioning? {
        transition.isPresenting = true
        transition.wantsInteractiveStart = false
        return transition
    }

    func animationController(forDismissed dismissed: UIViewController) -> UIViewControllerAnimatedTransitioning? {
        transition.isPresenting = false
        return transition
    }

    func interactionControllerForDismissal(using animator: UIViewControllerAnimatedTransitioning) -> UIViewControllerInteractiveTransitioning? {
        transition.isPresenting = false
        return transition
    }

    func presentationController(
        forPresented presented: UIViewController,
        presenting: UIViewController?,
        source: UIViewController
    ) -> UIPresentationController? {
        BottomSheetPresentationController(presentedViewController: presented,
                                          presenting: presenting,
                                          configuration: configuration)
    }
}

As you can see from the code we provide BottomSheetTransition object named transition as a:

1. Transition animator object for presentation transition (animationController(forPresented:) and for dismissal transition (animationController(forDismissed:)

2. Interactive animator object for interactive dismissal (with user’s swipe gesture). We implement only method interactionControllerForDismissal for providing interactive animator object for dismiss transition because we don’t need interactive presentation transition.

This is how we implement BottomSheetTransition:

class BottomSheetTransition: UIPercentDrivenInteractiveTransition {
    /// `true` if the transition is for the presentation.
    /// `false` if the transition is for the dismissal.
    var isPresenting = true

    /// Set this to `false` in order to start an interruptible transition non
    /// interactively (for example when tap on overlay view)
    var wantsInteractiveStart: Bool

    /// The interactive animator used for the dismiss transition.
    private var dismissAnimator: UIViewPropertyAnimator?

    /// The animator used for the presentation animation.
    private var presentationAnimator: UIViewPropertyAnimator?
}

UIPercentDrivenInteractiveTransition is a class from UIKit that conforms to UIViewControllerInteractiveTransitioning and provides all the necessary functionality for an interactive transition. It is percent-driven, meaning that the progress of the transition can be accessed and tracked through the percentComplete property, which is expressed as a percentage.

class UIPercentDrivenInteractiveTransition: UIViewControllerInteractiveTransitioning {
     var percentComplete: CGFloat { get }
}

On top of that BottomSheetTransition also implements UIViewControllerAnimatedTransitioning protocol:

extension BottomSheetTransition: UIViewControllerAnimatedTransitioning {

    func transitionDuration(using _: UIViewControllerContextTransitioning?) -> TimeInterval {
        animationDuration
    }

    /// Will get called when the transition is not interactive 
    /// to animate presenting or dismissing of the controller.
    func animateTransition(
        using transitionContext: UIViewControllerContextTransitioning
    ) {
        interruptibleAnimator(using: transitionContext).startAnimation()
    }

    /// Will get called when the transition is interactive.
    func interruptibleAnimator(
        using transitionContext: UIViewControllerContextTransitioning
    ) -> UIViewImplicitlyAnimating {
        if isPresenting {
            return presentationAnimator(using: transitionContext)
        } else {
            return dismissAnimator(using: transitionContext)
        }
    }
}

As you can see UIViewControllerAnimatedTransitioning methods provide animationDuration and implement actual transition animations in animateTransition(using transitionContext:)and interruptibleAnimator(using transitionContext:).

UIPresentationController

Another important object we need to provide in BottomSheetTransitioningDelegate is UIPresentationController. Our presentation controller will handle several tasks:

1. Provide the size of the presented view depending on its content size;

2. Decorate the appearance of the presented view controller (by adding the overlay, pull bar, etc.);

3. Add a swipe gesture recognizer and use it for interactive dismissal.

Next, let’s find out how to implement them.

Provide the size of the presented view

To provide the size of the bottom sheet, you need to override the frameOfPresentedViewInContainerView property.

class BottomSheetPresentationController: UIPresentationController {

    override var frameOfPresentedViewInContainerView: CGRect {
        // calculate presented view size here
    }

    // ...
}

The systemLayoutSizeFitting method of UIView can be used to determine the optimal size that best fits the constraints and closely aligns with the target size.

extension UIView {
    /// The size fitting most closely to targetSize in which the receiver's subtree
    /// can be laid out while optimally satisfying the constraints. 
    @available(iOS 8.0, *)
    open func systemLayoutSizeFitting(
                targetSize: CGSize, 
                horizontalFittingPriority: UILayoutPriority, 
                verticalFittingPriority: UILayoutPriority
        ) -> CGSize
}

This code we will use inside frameOfPresentedViewInContainerView property computation:

let fittingSize = CGSize(width: containerView.bounds.width,
                         height: UIView.layoutFittingCompressedSize.height)

let presentedViewHeight = presentedView.systemLayoutSizeFitting(
     fittingSize,
     withHorizontalFittingPriority: .required,
     verticalFittingPriority: .fittingSizeLevel
 ).height

We create fittingSize with layoutFittingCompressedSize.height and set verticalFittingPriority parameter to fittingSizeLevel to ensure that we will get the smallest possible size and aligns as closely as possible to satisfy the constraints.

Decorate presented view controller

To decorate our bottom sheet we will override the presentation controller’s methods:

presentationTransitionWillBegin - notifies the presentation controller that the presentation animations are about to start;

dismissalTransitionWillBegin - notifies the presentation controller that the dismissal animations are about to start;

containerViewDidLayoutSubviews - notifies the presentation controller that layout ended on the views of the container view. Here we will layout added subviews.

    override func presentationTransitionWillBegin() {
        super.presentationTransitionWillBegin()

        containerView?.addSubview(overlayView)
        presentedView?.addSubview(pullBarView)

        overlayView.alpha = 0

        presentedViewController.transitionCoordinator?.animate(alongsideTransition: { [weak self] _ in
            guard let self = self else { return }
            self.presentedView?.layer.cornerRadius = self.cornerRadius
            self.overlayView.alpha = 1
        })
    }

    override func dismissalTransitionWillBegin() {
        super.dismissalTransitionWillBegin()

        presentedViewController.transitionCoordinator?.animate(alongsideTransition: { [weak self] _ in
            guard let self = self else { return }
            self.presentedView?.layer.cornerRadius = .zero
            self.overlayView.alpha = 0
        })
    }

As previously mentioned, the UIPresentationController acts as a container for the transition and is the ideal candidate to decorate the presented controller with an overlay and pull bar. The containerView and presentedView properties of UIPresentationController were used to access the views involved in the transition that needed to be decorated.

Interactive dismiss with a pan gesture

The final task in the presentation controller is to handle user swipes to enable interactive dismissal. Let's examine the code for this:

    // The pan gesture used to drag and interactively dismiss the sheet.
    private lazy var panGesture = UIPanGestureRecognizer(target: self,
                                                         action: #selector(pannedPresentedView))

    @objc
    private func pannedPresentedView(_ recognizer: UIPanGestureRecognizer) {
        guard let presentedView = presentedView else {
            return
        }
        switch recognizer.state {
        case .began:
            // Start to dismiss interactively when user begins to swipe
            dismiss(interactively: true)

        case .changed:
            // Update the dismiss tansition progress
            let translation = recognizer.translation(in: presentedView)
            updateTransitionProgress(for: translation)

        case .ended, .cancelled, .failed:
            // Finish or cancel the dimissal depending on current progress of dismiss transition
            handleEndedInteraction()

        case .possible:
            break

        @unknown default:
            break
        }
    }

    private func handleEndedInteraction() {
        guard let transitioningDelegate = transitioningDelegate else {
            return
        }
        if transitioningDelegate.transition.dismissFractionComplete > dismissThreshold {
            transitioningDelegate.transition.finish()
        } else {
            transitioningDelegate.transition.cancel()
        }
    }

Conclusion

In conclusion, I would like to highlight that this is not a perfect solution as it does not support scrolling of content if the presented view controller is larger than the screen height. Additionally, navigation controllers inside the bottom sheet are not supported. However, it is still a simple and clean option if you need to add a bottom sheet to your project.

You can find all code here.