Unclear sentence in the documentation

[ghost]

Hello :)

The documentation (0.46.0) for ViewStoreTask states

You can use this value to tie the effect's lifecycle and cancellation to an asynchronous context, such as the task view modifier.

  .task { await viewStore.send(.task).finish() }

Are you saying that .finish() alone, as shown in the example code above, is sufficient to trigger a cancellation of the underlying task? I suspect not.

I think what you meant is that .finish() ties the result of the underlying task to the effect's lifecycle (but doesn't necessarily cancel the effect) and .cancel() ties the result of the underlying task to the effect's lifecycle, while also cancelling it. At least that's my understanding from reading the actual implementations of .finish() and .cancel().

If I'm correct in the above interpretation, may I suggest amending the documentation? Not everyone would bother to read the actual code and some might get confused by the sentence as written.

Thanks!

[tgrapperon]

Hey @wtruppel! Forget about the .task modifier for a second:

viewstore.send(.action)

This is a sync function. It returns when the reducer finishes reducing .action. Note however that this doesn't include side-effects like .run, .task, and .fireAndForget that you may have produced, because these ones are not evaluated synchronously. This is similar to what happens with

print("1")
DispatchQueue.global.async { … }
print("2")

This prints "2" immediately, regardless of the duration of what happens in the dispatched block.

viewstore.send(.action).finish()

This is now an async function that will return when all the effects (including side effects) produced by the reducers are finished. It means that if you trigger a .run that takes 10min or forever to return, calling this function will take 10min or forever.

Because of the way Swift concurrency works, if you cancel the .task generated in the view, this will also cancel the child tasks you may have spawned from this modifier (this is not systematic with Swift concurrency, but it was made sure that this is the case for ViewStoreTasks). If in your .run, you're checking try Task.checkCancellation (or Task.isCancelled), your run effect will automatically be cancelled because the .task from the view was cancelled. But for this to work, you need the viewStore.send to be "alive" (awaiting) when the task is cancelled.

In other words, .finish() is just something that makes viewStore.send async instead of sync, and this allows the viewStore.send to take as long as all the side-effects produced by your reducer. Because of the way Swift concurrency works, this allows these side effects to receive the cancellation signal from the view.

Please note that this task from the view is cancelled if the view goes away, or if you change its identifier.

You may also directly cancel the viewStore.send(.action) effects. For example:

.task {
  let viewStoreTask = viewStore.send(.action) // We don't await, but an effect may be running.
  try await Task.sleep(for: .seconds(1))
  await viewStoreTask.cancel() // Manually cancel the effect if it's still ongoing and if this 
                               // line is reached, that is, if the task wasn't cancelled while 
                               // we were sleeping.
  // At this stage, we know that the effect were effectively cancelled.
}

The .cancel() method is async too because it may take time for the effect to effectively receive and process this cancellation request. Having this function async allows to include this factor into structured concurrency patterns. In my experience, uses of this function are rarer, and often the sign that you're running non-trivial logic on the UI layer.

So you're getting it right. I simply rephrased it in any case it helps confirming your understanding. I don't know how the documentation can be improved, but I'm aware that there are plans to expand the concurrency section.

[mbrandonw]

In addition to what @tgrapperon, note that this is the implementation of ViewStoreTask:

/// Waits for the task to finish.
public func finish() async {
  await self.rawValue?.cancellableValue
}

And that cancellableValue is a helper specifically for making a Task cancellable based on its surrounding context:

extension Task where Failure == Never {
  @usableFromInline
  var cancellableValue: Success {
    get async {
      await withTaskCancellationHandler {
        await self.value
      } onCancel: {
        self.cancel()
      }
    }
  }
}

So indeed, if the task created by SwiftUI's .task view modifier is cancelled, the ViewStoreTask will be cancelled, which trickles down to cancelling the effect from sending the action (as well as the effects of effects, etc...).

[ghost]

@tgrapperon @mbrandonw
Thank you both. All I was asking for really was an amendment to the documentation, for the benefit of those who don't dig into the code, but the extra explanations are much appreciated.

[mbrandonw]

@wtruppel We are definitely open to clarifying the documentation. From you original post it seems that you understood the docs to mean that finish() does handle cancellation, but that you weren't sure it was actually true:

Are you saying that .finish() alone, as shown in the example code above, is sufficient to trigger a cancellation of the underlying task? I suspect not.

Given that it is true, do you still think the docs need updating? Do you have any suggestions of what we could say to make this clearer?

[ghost]

Hi @mbrandonw, perhaps the addition of a sentence to clarify what .cancel() buys you because, if .finish() already handles cancellation, then why/when would you ever need to use .cancel() ? Thanks!