Bikeshedding names for StoreTask.finish()

[randomeizer]

It was mooted in Slack that the StoreTask.finish() name feels ambiguous in its intention. The designed usage is something like:

await store.send(.action).finish()

However, because finish is an imperative verb, it may feel like it's a command to finish, rather than waiting for the task to finish.

There is some prior art from Apple for using waitXXX:

It does feel somewhat redundant having await and wait in the statement. For example:

await store.send(.action).waitUntilFinished()

Other possible options suggested include:

• await store.send(.action).finished()
• await store.send(.action).untilFinished()
• await store.send(.action).hasFinished()

None of these really have prior art in an async sense.

I would also say that it should make sense if just checking on the StoreTask directly. For example:

let myTask = await store.send(.action)

await myTask.waitUntilFinished() // clear, but redundant
await myTask.finished() // feels more like checking state than waiting for something
await myTask.untilFinished() // does not read like good English
await myTask.isFinished() // also feels like checking state, and `isCancelled` is not async.
await myTask.hasFinished() // reads ok, but no prior art

Of these, my favourite is actually probably hasFinished or hasCompleted. It's more clearly a 'past tense' phrase than isFinished. But it's not really out there much as a convention.

Otherwise, waitUntilFinished or waitUntilCompleted would be clearer than what we have at the moment.

What are people's thoughts or suggestions?

[jshier]

Use of wait is certainly redundant, and most of the examples in that list are old, synchronous interfaces. In fact, I'd say even TaskGroup's APIs are misnamed, as await group.waitForAll() is rather ambiguous and redundant. Wait for all what? await group.allFinished() makes more sense to me. In that case, .finished() seems good enough for the singular version.

I'd also like to point out that your dislike of various options due to checking state rather than waiting for something doesn't seem true, given the use of await. With await, the wait is implicit in all of these APIs. So really it's down to whether or not the API is grammatical and conveys the relevant information.

Personally, and given finish() can't function in a way that may be confused with it's current use (we can't command an arbitrary action to finish), and the use of await conveying the suspension point (wait over time), it's use seems fine to me. If the confusion is that it's something that happens in the future, and await isn't enough to convey that, then the past tense, finished() seem to convey that bit of information. If we consider waitUntilFinished() redundant, untilFinished() non grammatical, then finished() seems correct.

Unfortunately Apple has stopped updating the Swift naming guidelines as Swift adds new capabilities like native concurrency, so there's really no official guidance here.

[randomeizer]

Counter to that, there is cancel() and isCancelled. finished() as a function is somewhere between the two. Not sure that's ideal.

An isFinished property would probably not be appropriate, although you have examples like Task.value which is async. But the fact that isFinished would be waiting until the task is finished makes it different to isCancelled, which is a synchronous call.

[randomeizer]

Another possibility that occurred. Task has value and result which allows access to the final outcome of the task, waiting for it to conclude. StoreTask doesn't have a value type, and can never fail, but it does have two possible outcomes: finished and cancelled.

What if we had an enum that indicated that outcome, and a property to check the result. Something like:

extension StoreTask {
  public enum Completion {
    case finished
    case cancelled
  }
  
  public var completion: Completion {
    get async {
      await self.rawValue?.cancellableValue
      return self.isCancelled ? .cancelled : .finished
     }
  }
}

This would then be used as:

await store.send(.action).completion

[randomeizer]

Why not allow distinction though? Task lets you distinguish between success and failure via result. We could call it result too, but I think that would imply an actual Result, which is not the case here.

There are also Subscribers.Completion from Combine, used by Sink, etc., which is defined as:

    /// A signal that a publisher doesn’t produce additional elements, either due to normal completion or an error.
    @frozen public enum Completion<Failure> where Failure : Error {

        /// The publisher finished normally.
        case finished

        /// The publisher stopped publishing due to the indicated error.
        case failure(Failure)
    }

If the point is that cancellations aren't usually communicated so directly, sure. Is that a good thing though?

If it's the phrase that's the issue, here's some possible other terms for "finished and didn't get cancelled":

• resolved
• terminated
• ended
• finalised
• closed

[jshier]

If you do want to know how the task finished (not sure why, but it may be useful), and you don't want to use finished() -> Completion, perhaps completed() -> Completion would be appropriate, as long as you could ignore the value. await store.send(.action).completed() But the return value doesn't really give you anything that simply checking an isCancelled property after the fact wouldn't. In fact, if completed() simply returned the task itself, I think you could do let isCancelled = await store.send(.action).completed().isCancelled, if having it on one line was important.

[randomeizer]

Sure, those are possibilities. Grammatically speaking, await ... completion is more correct than await ... completed, but there are a lot of other grammatically incorrect combinations with await all over the place, so not that big a deal.

Ignoring completion as a computed variable is possible, but requires _ = store.send(...).completion. Making it a function would allow using @discardableResult, but would be less of a match with Task.value and Task.result.

[jshier]

You must consider the whole usage to determine whether it reads grammatically, you can't just cut out the middle. await store.send(.action).completed() seems just as grammatical (wait until the store's send is completed) as await store.send(.action).completion (wait for the completion value of the store's send).

And given that you'll usually want to ignore the completion value, unlike Task.value, it seems like we'd want an interface you can actually ignore.

[randomeizer]

And here we're back to adding words back into the prefix, such as untilCompletion, hasCompleted, or something along those lines.

[jegnux]

I like completion but I don't think a car can be @discardableResult so it would require to write

_ = await store.send(.action).completion

What about having an async counterpart to .send() that just conveys the fact that it does not just send but also wait for all effects to run?

await store.run(.action)

Or eventually

await store.reduce(.action)

[randomeizer]

Correct, computed var values can't be discarded, (although this does seem to compile, which is interesting):

var foo { 
  @discardableResult
  get async { ... }
}

An async alternate to send could work, and potentially be clearer. I think run is not necessarily clear as far as expecting it to wait. Maybe sendAndFinish(.action) or something? This is getting back to the deprecated API though.

[Mackarous]

I think run is clear considering we already use it within the reducer pattern

[randomeizer]

True that.