Effects that require background execution time

[lukeredpath]

I'm trying to write a generic helper function and effect that lets me perform an effect with extended background execution time (e.g. using UIApplication.beginBackgroundTask). In short, I want to be able to:

• Use a static helper on EffectTask that acts like .run { send in } except for it begins a background task before executing the task.
• If the task is successful it calls endBackgroundTask before completing the effect.
• If the task throws it calls endBackgroundTask before re-throwing.
• If the background task expiry handler is called, the task should be cancelled.
• There should be an opportunity to send one last action to the store when the task is cancelled (so I can update some state to indicate something was cancelled).

I've mostly got this working except for the last part and I'm not sure how to deal with this - by the time I've called task.cancel() in my expiry handler, it is no longer possible to use send(.someAction) as send acts as a no-op if the current task is cancelled.

This is my core implementation - backgroundExecutionClient is just a wrapper around the UIApplication APIs so I can test this:

public func withExtendedBackgroundExecution<Result: Sendable>(
    taskName: String,
    priority: TaskPriority? = nil,
    operation: @Sendable @escaping () async throws -> Result
) async throws -> Result {
    @Dependency(\.backgroundExecutionClient) var client
    var taskIdentifier: UIBackgroundTaskIdentifier = .invalid
    let task = Task(priority: priority, operation: operation)
    taskIdentifier = client.beginBackgroundTask(taskName) {
        // We don't need to call end background task here because cancelling the task will
        // cause a cancellation error to be thrown and caught by the catch block below.
        task.cancel()
    }
    do {
        let result = try await task.value
        client.endBackgroundTask(taskIdentifier)
        return result
    } catch {
        client.endBackgroundTask(taskIdentifier)
        throw error
    }
}

And the effect helper just builds on top of this:

extension EffectTask where Failure == Never {
    public static func backgroundExecutionTask(
        withName name: String,
        priority: TaskPriority? = nil,
        operation: @escaping @Sendable (Send) async throws -> Void,
        catch handler: (@Sendable (Error, Send) async -> Void)? = nil,
        file: StaticString = #file,
        fileID: StaticString = #fileID,
        line: UInt = #line
    ) -> Self {
        .run(
            priority: priority,
            operation: { send in
                try await withExtendedBackgroundExecution(taskName: name, priority: priority) {
                    try await operation(send)
                }
            },
            catch: handler,
            file: file,
            fileID: fileID,
            line: line
        )
    }
}

I'm not quite sure how to adapt this to allow me to send a final action on cancellation, I've tried doing this but it complains that I can't use send inside onCancel due to main actor isolation. I've also tried using do { } catch is CancellationError { } but even though I can call send here it doesn't do anything.

func run() -> EffectTask<Job.Action> {
    .backgroundExecutionTask(withName: "example task", priority: .high) { send in
        withTaskCancellationHandler {
            // do some stuff that takes a while
        } onCancel: {
            send(.jobCancelled) // I want to handle this in my reducer to update some state to indicate the job was cancelled.
        }
    } catch: { error, send in
        await send(.jobFailed(error as NSError))
    }
}

I'm open to suggestions.

[jshier]

IIRC, cancellation of background tasks gets one turn of the main run loop in which to complete any cancellation work. Anything more may be dropped because the app has transitioned to the background. I'm pretty sure background tasks and async / await are fundamentally incompatible, aside from the new SwiftUI APIs, maybe. Whether this also applies to cancellation while the app is foregrounded, I don't know.

[lukeredpath]

I certainly need to some real world testing to see what happens in practice.

[stephencelis]

@lukeredpath I've got to run, but I have a few small comments that may help in the meantime. Will check back in later and read things in more depth if there's still more to figure out.

One thing that stands out in skimming this is that in withExtendedBackgroundExecution you wait for task.value, but the cancellation of that task will not be propagated to the caller unless you thread the cancellation through using Swift's withTaskCancellationHandler. We have an internal helper in TCA called Task.cancellableValue that does this work, since we need to do this dance a few places throughout the repo:

https://github.com/pointfreeco/swift-composable-architecture/blob/main/Sources/ComposableArchitecture/Internal/TaskCancellableValue.swift#L4-L8

With that updated I think your Effect.run wrapper can simply wrap the work in do-catch that intercepts cancellation:

do {
  …
} catch is CancellationError {
  await send(.jobCancelled)
}

[lukeredpath]

Thank you - I think the problem was I trying to catch the cancellation error in the wrong place, doing it around the withExtendedBackgroundExecution call allows me to call send as the task is not cancelled in that scope. To that end, I've added an onExpiry function parameter to my EffectTask helper that allows me to optionally handle this.

[lukeredpath]

@stephencelis could you elaborate a bit more on the cancellation stuff because I'm not seeing this behaviour. Using my original approach, I've successfully tested:

• Cancelling the task wrapping the operation when the background task is about to expire.
• Throwing a cancellation error from the operation.

In both cases the background task ends correctly and the overall EffectTask finishes.

[lukeredpath]

I did a bit of real world testing - I found that there does seem to be enough time when the expiration handler is called to send one more action (although I guess this isn't guaranteed). The problem with doing it by catching the cancellation error for the background executing task is that by that point, endBackgroundTask has already been called and the app seems to immediately enter the background.

I need to do some more testing of this on a device but so far I've found that adding an onExpiry handler to withExtendedBackgroundExecution and then calling that inside a new high-priority Task inside the background task expiry handler before ending the background task seems to work as I expected:

taskIdentifier = client.beginBackgroundTask(taskName) {
        Task(priority: .high) { @MainActor in
            // We'll call the expiry handler first to give it a small amount of time to do some
            // work before we cancel the task.
            await expiryHandler?()

            // We don't need to call end background task here because cancelling the task will
            // cause a cancellation error to be thrown and caught by the catch block below.
            task.cancel()
        }
    }

[jshier]

There's a bit of conflict in the suggested behavior here. According to Quinn, there are two parts here:

Your expiry handler is your opportunity to clean things up. It should not return until everything is actually cleaned up. It must run quickly, that is, in less than a second or so. If it takes too long, your app will be killed by the watchdog.

So a quick cancellation that's async meets the second condition (less than a second) but not the first (it's not finished by the time the expiration handler returns). So this may be something we need more clarity on.

[lukeredpath]

Yes, in my tests this seems to work but I was uneasy about spinning up a high-priority task here. I have found an alternative approach.

The only reason I need a task here is because the expiryHandler is async and the only reason it is async is because I need to call await send(.foo). I believe send will synchronously send an action to the store but it's isolated to the @MainActor as the TCA store can only be used from the main queue.

I found an alternate solution - perhaps this could be added to the Send API:

extension EffectPublisher.Send {
    @MainActor(unsafe)
    func sendUnsafe(_ action: Action) {
        self.send(action)
    }
}

This can now be called synchronously, but only if you are certain you're running on the main actor. The documentation for beginBackgroundTask states that the expiration handler will always be called on the main thread so this seems like a safe opportunity to do this.

I can now make the expiry handler closure non-async and change my implementation to:

client.beginBackgroundTask(taskName) {
        expiryHandler?()
        task.cancel()
    }

[lukeredpath]

Actually, on testing this again on device I found that calling task.cancel() was no longer resulting in the task being ended before the expiration handler returned so I added an explicit call to my endBackgroundTask() helper.

[lukeredpath]

Bit of a brain fart moment...none of the unsafe stuff above is necessary, I just needed to mark withExtendedBackgroundExecution as @MainActor and now I can also mark my expiryHandler as a @MainActor closure and call it synchronously in the background task expiration handler and consequently, just call send(.foo). In other words, making sure the entire expiry callback chain was main actor isolated was what I was missing here.

[lukeredpath]

I made one other small change to the backgroundExecutionTask handler and that's to move the non-cancellation error handling down a level so errors thrown from the underlying operation can be handled before the background task is ended - before I was passing the catch handler directly to .run but by the time that gets called, the errors have already passed through withExtendedBackgroundExecution and the background task has been ended - if the app is in the background when that happens, the app would enter a background state before the catch handler was called:

.run(
    priority: priority,
    operation: { send in
        try await withExtendedBackgroundExecution(taskName: name, priority: priority) {
            do {
                try await operation(send)
            } catch is CancellationError {
                return
            } catch {
                // Rather than passing the handler to `run` directly, we'll catch
                // any errors here and call the handler here instead - this will
                // ensure any error handler is called _before_ the background execution
                // task is ended. If no handler is passed in and operation throws,
                // the default `.run` handler will trigger a runtime warning/test failure.
                await handler?(error, send)
            }
        } onExpiry: {
            onExpire?(send)
        }
    },
    catch: nil,
    file: file,
    fileID: fileID,
    line: line
)

To the caller the result is mostly the same - cancellation errors will bubble up, skipping the catch handler and cause the task to be cancelled and the background task to end. Other errors will get caught first by the provided catch handler, then withExtendedBackgroundExecution which will cancel the operation and end the background task. If no catch handler is provided, then any errors will bubble all the way up to .run where it will result in a runtime warning.

[dustinhowl]

I'm curious to know if you got this working. I'm looking into a similar solution myself.

My biggest question involves the task cancellation and the throwing of CancellationError:

// We don't need to call end background task here because cancelling the task will
// cause a cancellation error to be thrown and caught by the catch block below.
task.cancel()

Based on the Task documentation, I see nothing that suggests that calling task.cancel() will throw an error.

Task cancellation is cooperative: a task that supports cancellation checks whether it has been canceled at various points during its work.

Calling this method on a task that doesn’t support cancellation has no effect. Likewise, if the task has already run past the last point where it would stop early, calling this method has no effect.

There is Task.checkCancellation() that will do that, but that doesn't seem to be part of this solution and restricts the type of Task that it can be used with.