More Control Over isLoading

[mhayes853]

The value of isLoading on @Shared properties seems to only be true when some LoadContinuation has been passed to the underlying shared key either through loading the initial value, or when load is called explicitly on the Shared property.

However, let's take a simplified version of a SharedReaderKey that checks the current CKAccountStatus from CloudKit as an example.

struct CKAccountStatusKey: SharedReaderKey {
  typealias Value = CKAccountStatus

  let id = UUID()

  func load(context: LoadContext<Value>, continuation: LoadContinuation<Value>) {
    Task {
      continuation.resume(with: await Result { try await CKContainer.default().accountStatus() })
    }
  }

  func subscribe(
    context: LoadContext<Value>,
    subscriber: SharedSubscriber<Value>
  ) -> SharedSubscription {
    nonisolated(unsafe) let observer = NotificationCenter.default.addObserver(
      forName: .CKAccountChanged,
      object: nil,
      queue: nil
    ) { _ in
      Task {
        subscriber.yield(with: await Result { try await CKContainer.default().accountStatus() })
      }
    }
    return SharedSubscription { NotificationCenter.default.removeObserver(observer) }
  }
}

Ignoring potential race conditions from contention between load and subscribe making separate calls to accountStatus, there seems to be no way to indicate a new loading state to the @SharedReader property from within this SharedReaderKey.

For instance, when the key receives a new CKAccountChanged notification, it must load the new account status asynchronously in the background. However, the fact that there is background loading going on is not reflected in the @SharedReader property as there is no way to indicate that loading has started up again inside subscribe. Despite there possibly being a loaded CKAccountStatus available in the @SharedReader property, we may still want to display a loading indicator alongside the available status whilst this background loading is occurring.

We could work around this a bit by creating a custom type that holds this loading state, that gets emitted from the key. Eg.

struct CKAccountStatusState {
  var isLoading = false
  var status = CKAccountStatus.couldNotDetermine
}

Then we could update CKAccountStatusKey in a similar manner:

final class CKAccountStatusKey: SharedReaderKey {
  typealias Value = CKAccountStatusState

  private let state = Mutex(CKAccountStatusState())

  // Other SharedReaderKey requirements...

  func subscribe(
    context: LoadContext<Value>,
    subscriber: SharedSubscriber<Value>
  ) -> SharedSubscription {
    nonisolated(unsafe) let observer = NotificationCenter.default.addObserver(
      forName: .CKAccountChanged,
      object: nil,
      queue: nil
    ) { _ in
      Task {
        do {
          self.state.withLock {
            $0.isLoading = true
            subscriber.yield($0)
          }
          let newStatus = try await CKContainer.default().accountStatus()
          self.state.withLock {
            $0.isLoading = false
            $0.status = newStatus
            subscriber.yield($0)
          }
        } catch {
          self.state.withLock {
            $0.isLoading = false
            subscriber.yield($0)
          }
          subscriber.yield(throwing: error)
        }
      }
    }
    return SharedSubscription { NotificationCenter.default.removeObserver(observer) }
  }
}

While this certainly allows for more control over the loading state, the consumer of this key using @SharedReader now must be aware that they shouldn't be using the isLoading property on the SharedReader, but rather the isLoading property in CKAccountStatusState.

If we wanted to rely on the isLoading property on @SharedReader, we could omit the subscription logic from the CKAccountStatusKey, and opt instead to observe the CKAccountChanged notification outside of the key say at the root of the application instead. When we observe the notification, we can then invoke load directly on the @SharedReader like so:

@SharedReader(.ckAccountStatus) var accountStatus

// ...

Task {
  let notifications = NotificationCenter.default.notifications(named: .CKAccountChanged)
  for await _ in notifications {
    // Now allows us to use $accountStatus.isLoading as the source of truth for the loading state.
    try await $accountStatus.load()
  }
}

This allows us to use $accountStatus.isLoading as the main source of truth for the loading state, but I think it would be ideal for maintainability to keep this subscription logic within CKAccountStatusKey as then it would be the sole component that deals with the account status (and also we can take advantage of the fact that we can automatically unsubscribe from NotificationCenter when no consumers of CKAccountStatusKey are active).

For some more advanced use cases of this kind of control of the loading state, I'm currently working on some tooling that makes common asynchronous data fetching like network calls more friendly with @SharedReader. In particular, some of this tooling includes automatically refetching the data when the network comes back online. The work of observing the current internet connectivity status, and refetching the data would occur somewhere in the subscribe method of some SharedReaderKey. Naturally, I would like to indicate to the consumer of the @SharedReader that the data is being refetched through isLoading such that a loading indicator can be displayed in the UI.

Additionally, I may want to send back multiple payloads of data over time (say in a case where we first want to load some cached data on disk, and then fetch the latest data via the network), but still indicate that the data is in a collective "loading" state. It would be ideal to have precise control of the loading state here, but currently it seems that isLoading will automatically be set to false when sending back any payload through LoadContinuation. To illustrate this a bit more clearly, I think it would be cool if something like this could be done:

struct LongLoadingKey: SharedReaderKey {
  // Other requirements...

  func load(context: LoadContext<Value>, continuation: LoadContinuation<Value>) {
    // withOperation would ensure that `isLoading` on @SharedReader would always be true 
    // whilst the operation is in progress.
    continutation.withOperation { resumer in
       let cachedData = try await cache.loadData()
       resume(with: cachedData)
       let latestData = try await apiClient.loadData()
       resume(with: latestData)
    }
  }
}

I have a couple of final questions to ask. As of right now, what would be the recommended way for handling these kinds of complex loading states? Secondly, is it possible that the library could address these use cases in the future?

Anyways, thanks for taking the time to read through this.

[stephencelis]

@mhayes853 Thanks for the discussion and thoughtfulness. We definitely think there are improvements we can make to the loading infrastructure of Sharing, and better interplay between the load and subscribe endpoints.

I think the main thing you bring up would be solvable with a new API on SharedSubscriber that flips isLoading to true until the next yielded value or error. Something like:

 func subscribe(
   context: LoadContext<Value>,
   subscriber: SharedSubscriber<Value>
 ) -> SharedSubscription {
   nonisolated(unsafe) let observer = NotificationCenter.default.addObserver(
     forName: .CKAccountChanged,
     object: nil,
     queue: nil
   ) { _ in
+    subscriber.yieldLoading()
     Task {
       subscriber.yield(with: await Result { try await CKContainer.default().accountStatus() })
     }
   }
   return SharedSubscription { NotificationCenter.default.removeObserver(observer) }
 }

Would you be up for attempting a PR for such functionality?

As for allowing load to resume more than once, we're not quite sure how that would work, even with a scoping operation. It seems a little tricky to account for all the permutations of multiple load results of success/failure, but maybe a demo would help us understand, if you want to cook one up.

One thought I have is that if load() also was handed the subscriber you could do something like this:

 func load(
   context: LoadContext<Value>,
   continuation: LoadContinuation<Value>,
+  subscriber: SharedSubscriber<Value>
 ) {
   Task {
     let cachedData = try await cache.loadData()
     resume(with: cachedData)
+    subscriber.yieldLoading()
+    subscriber.yield(with: await Result { try await apiClient.loadData() }
   }
 }

Again, could be worth exploring if you have the inclination!

[mhayes853]

Thanks for taking the time to respond.

I've opened #125 to add yieldLoading to SharedSubscriber.

As for load resuming more than once, I've had a chance to do some thinking about it, and I'll see if I have time to cook up something more concrete later.

In essence, what I'm really looking for here is the ability to define a multi-stage load operation within a shared key. Each stage would constitute loading data from a different source and then subsequently feeding that data back into the system using either LoadContinuation or SharedSubscriber depending on the context. However, until the final stage is completed, the operation would still be collectively "loading".

Therefore, I think it's best that the definition of "operation completeness" is left to the shared key. Additional APIs on both SharedSubscriber and LoadContinuation could be optimal here. Particularly, I want to be able to:

• Feed a value back into the system without affecting the loading state.
• Have an explicit API to stop loading if for some reason the operation need be terminated without sending a new value back into the system (I've addressed this for SharedSubscriber by adding an isLoading parameter to yieldLoading in Add yieldLoading to SharedSubscriber #125).

In the case of load, I think I would rather not have a SharedSubscriber instance as I think it could be a bit confusing alongside subscribe. I would rather have something like this:

func load(
  context: LoadContext<Value>,
  continuation: LoadContinuation<Value>
) {
   Task {
     let cachedData = try await cache.loadData()
+    // First stage completed, sends cachedData without changing the loading state.
+    continuation.resume(with: cachedData, completeLoading: false)
+    // Final stage completed, so loading stops.
+    continuation.resume(with: await Result { try await apiClient.loadData() })
   }
 }

Of course, it would be the responsibility of the shared key to indicate when the operation is completed by passing true for completeLoading (which would be the default value). The current issue could be reported if the key fails to do this. However, if the key resumes the continuation with completeLoading set to false, and for some reason at a later point wants to consider the operation "completed" with the payload is previously resumed with, some kind of finish API could be added.

func load(
  context: LoadContext<Value>,
  continuation: LoadContinuation<Value>
) {
   Task {
     let cachedData = try await cache.loadData()
     continuation.resume(with: cachedData, completeLoading: false)

     // More operations of trying to load the latest data, but for some reason decides it's not suitable to resume with...

     // Indicates that the operation has been completed, and that cachedData is the final resumed value.
     continuation.finish()
   }
 }

Of course, continuation.finish should only be invoked if a prior value has been passed to continuation.resume with completeLoading set to false, so reporting an issue could be suitable here. Additionally, finish shouldn't be invoked more than once, and the existing issue about multiple resume calls could still be reported here.

A similar completeLoading parameter could also be added to the yield methods on SharedSubscriber. yieldLoading already can play the equivalent role of continuation.finish since you can pass false to indicate that loading should stop.

[mhayes853]

In terms of the tooling that I'm writing around async fetching. I have a class called QueryStore, and it has a subscribe API that allows listeners to listen for explicit events in a multi-stage operation. The listener looks something like this:

struct QueryStoreEventHandler<Value: Sendable>: Sendable {
  let onFetchingStarted: (@Sendable () -> Void)?
  let onFetchingEnded: (@Sendable () -> Void)?

  // Can be invoked multiple times throughout the duration of an operation (once per stage).
  let onResultReceived: (@Sendable (Result<Value, any Error>) -> Void)?
}

Using this would fit nicely into my suggested APIs for SharedSubscriber and LoadContinuation.

func load(
  context: LoadContext<Value>,
  continuation: LoadContinuation<Value>
) {
   Task {
     try await queryStore.fetch(
       handleEvents: QueryStoreEventHandler<Value>(
         onFetchingEnded: { continuation.finish() },
         onResultReceived: { continuation.resume(with: $0, completeLoading: false) }
       )
     )
   }
 }

 func subscribe(
   context: LoadContext<Value>,
   subscriber: SharedSubscriber<Value>
 ) -> SharedSubscription {
   let subscription = queryStore.subscribe(
     with: QueryStoreEventHandler<Value>(
       onFetchingStarted: { subscriber.yieldLoading() },
       onFetchingEnded: { subscriber.yieldLoading(false) },
       onResultReceived: { subscriber.yield(with: $0, completeLoading: false) }
     )
   )
   return SharedSubscription { subscription.cancel() }
 }