[ASCollectionNode] Add -isProcessingUpdates and -onDidFinishProcessingUpdates: APIs.

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## master
 
 * Add your own contributions to the next release on the line below this with your name.
+- [ASCollectionNode] Add -isProcessingUpdates and -onDidFinishProcessingUpdates: APIs. [#522](https://github.com/TextureGroup/Texture/pull/522) [Scott Goodson](https://github.com/appleguy)
 - [Accessibility] Add .isAccessibilityContainer property, allowing automatic aggregation of children's a11y labels. [#468][Scott Goodson](https://github.com/appleguy)
 - [ASImageNode] Enabled .clipsToBounds by default, fixing the use of .cornerRadius and clipping of GIFs. [Scott Goodson](https://github.com/appleguy) [#466](https://github.com/TextureGroup/Texture/pull/466)
 - Fix an issue in layout transition that causes it to unexpectedly use the old layout [Huy Nguyen](https://github.com/nguyenhuy) [#464](https://github.com/TextureGroup/Texture/pull/464)

Source/ASCollectionNode.h

@@ -252,10 +252,39 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)performBatchUpdates:(nullable AS_NOESCAPE void (^)())updates completion:(nullable void (^)(BOOL finished))completion;
 
+/**
+ *  Returns YES if the ASCollectionNode is still processing changes from performBatchUpdates:.
+ *  This is typically the concurrent allocation (calling nodeBlocks) and layout of newly inserted
+ *  ASCellNodes. If YES is returned, then calling -waitUntilAllUpdatesAreProcessed may take tens of
+ *  milliseconds to return as it blocks on these concurrent operations.
+ *
+ *  Returns NO if ASCollectionNode is fully synchronized with the underlying UICollectionView. This
+ *  means that until the next performBatchUpdates: is called, it is safe to compare UIKit values
+ *  (such as from UICollectionViewLayout) with your app's data source.
+ *
+ *  This method will always return NO if called immediately after -waitUntilAllUpdatesAreProcessed.
+ */
+@property (nonatomic, readonly) BOOL isProcessingUpdates;
+
+/**
+ *  Schedules a block to be performed (on the main thread) after processing of performBatchUpdates:
+ *  is finished (completely synchronized to UIKit). The blocks will be run at the moment that
+ *  -isProcessingUpdates changes from YES to NO;
+ *
+ *  When isProcessingUpdates == NO, the block is run block immediately (before the method returns).
+ *
+ *  Blocks scheduled by this mechanism are NOT guaranteed to run in the order they are scheduled.
+ *  They may also be delayed if performBatchUpdates continues to be called; the blocks will wait until
+ *  all running updates are finished.
+ *
+ *  Calling -waitUntilAllUpdatesAreProcessed is one way to flush any pending update completion blocks.
+ */
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())didFinishProcessingUpdates;
+
 /**
  *  Blocks execution of the main thread until all section and item updates are committed to the view. This method must be called from the main thread.
  */
-- (void)waitUntilAllUpdatesAreCommitted;
+- (void)waitUntilAllUpdatesAreProcessed;
 
 /**
  * Inserts one or more sections.
@@ -501,9 +530,13 @@ NS_ASSUME_NONNULL_BEGIN
  * @warning This method is substantially more expensive than UICollectionView's version.
  *
  * @deprecated This method is deprecated in 2.0. Use @c reloadDataWithCompletion: and
- *   then @c waitUntilAllUpdatesAreCommitted instead.
+ *   then @c waitUntilAllUpdatesAreProcessed instead.
  */
-- (void)reloadDataImmediately ASDISPLAYNODE_DEPRECATED_MSG("Use -reloadData / -reloadDataWithCompletion: followed by -waitUntilAllUpdatesAreCommitted instead.");
+- (void)reloadDataImmediately ASDISPLAYNODE_DEPRECATED_MSG("Use -reloadData / -reloadDataWithCompletion: followed by -waitUntilAllUpdatesAreProcessed instead.");
+
+// TODO: Rename framework uses of this method and add deprecation message.
+// ASDISPLAYNODE_DEPRECATED_MSG("This method has been renamed to -waitUntilAllUpdatesAreProcessed.");
+- (void)waitUntilAllUpdatesAreCommitted;
 
 @end
 

Source/ASCollectionNode.mm

@@ -713,6 +713,25 @@ - (void)waitUntilAllUpdatesAreCommitted
   }
 }
 
+- (void)waitUntilAllUpdatesAreProcessed
+{
+  [self waitUntilAllUpdatesAreCommitted];
+}
+
+- (BOOL)isProcessingUpdates
+{
+  return (self.nodeLoaded ? [self.view isProcessingUpdates] : NO);
+}
+
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())completion
+{
+  if (!self.nodeLoaded) {
+    completion();
+  } else {
+    [self.view onDidFinishProcessingUpdates:completion];
+  }
+}
+
 - (void)reloadDataWithCompletion:(void (^)())completion
 {
   ASDisplayNodeAssertMainThread();

Source/ASCollectionView.h

@@ -296,8 +296,10 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)relayoutItems ASDISPLAYNODE_DEPRECATED_MSG("Use ASCollectionNode method instead.");
 
 /**
- *  Blocks execution of the main thread until all section and row updates are committed. This method must be called from the main thread.
+ * See ASCollectionNode.h for full documentation of these methods.
  */
+@property (nonatomic, readonly) BOOL isProcessingUpdates;
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())completion;
 - (void)waitUntilAllUpdatesAreCommitted ASDISPLAYNODE_DEPRECATED_MSG("Use ASCollectionNode method instead.");
 
 /**

Source/ASCollectionView.mm

@@ -371,6 +371,16 @@ - (void)waitUntilAllUpdatesAreCommitted
   [_dataController waitUntilAllUpdatesAreCommitted];
 }
 
+- (BOOL)isProcessingUpdates
+{
+  return [_dataController isProcessingUpdates];
+}
+
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())completion
+{
+  [_dataController onDidFinishProcessingUpdates:completion];
+}
+
 - (void)setDataSource:(id<UICollectionViewDataSource>)dataSource
 {
   // UIKit can internally generate a call to this method upon changing the asyncDataSource; only assert for non-nil. We also allow this when we're doing interop.

Source/Details/ASDataController.h

@@ -254,6 +254,11 @@ extern NSString * const ASCollectionInvalidUpdateException;
  */
 - (void)relayoutNodes:(id<NSFastEnumeration>)nodes nodesSizeChanged:(NSMutableArray * _Nonnull)nodesSizesChanged;
 
+/**
+ * See ASCollectionNode.h for full documentation of these methods.
+ */
+@property (nonatomic, readonly) BOOL isProcessingUpdates;
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())completion;
 - (void)waitUntilAllUpdatesAreCommitted;
 
 /**

Source/Details/ASDataController.mm

@@ -437,6 +437,35 @@ - (void)waitUntilAllUpdatesAreCommitted
   [self _scheduleBlockOnMainSerialQueue:^{ }];
 }
 
+- (BOOL)isProcessingUpdates
+{
+  ASDisplayNodeAssertMainThread();
+  if (_mainSerialQueue.numberOfScheduledBlocks > 0) {
+    return YES;
+  } else if (dispatch_group_wait(_editingTransactionGroup, DISPATCH_TIME_NOW) != 0) {
+    // After waiting for zero duration, a nonzero value is returned if blocks are still running.
+    return YES;
+  }
+  // Both the _mainSerialQueue and _editingTransactionQueue are drained; we are fully quiesced.
+  return NO;
+}
+
+- (void)onDidFinishProcessingUpdates:(nullable void (^)())completion
+{
+  ASDisplayNodeAssertMainThread();
+  if ([self isProcessingUpdates] == NO) {
+    ASPerformBlockOnMainThread(completion);
+  } else {
+    dispatch_async(_editingTransactionQueue, ^{
+      // Retry the block. If we're done processing updates, it'll run immediately, otherwise
+      // wait again for updates to quiesce completely.
+      [_mainSerialQueue performBlockOnMainThread:^{
+        [self onDidFinishProcessingUpdates:completion];
+      }];
+    });
+  }
+}
+
 - (void)updateWithChangeSet:(_ASHierarchyChangeSet *)changeSet
 {
   ASDisplayNodeAssertMainThread();

Source/Details/ASMainSerialQueue.h

@@ -21,6 +21,7 @@
 AS_SUBCLASSING_RESTRICTED
 @interface ASMainSerialQueue : NSObject
 
+@property (nonatomic, readonly) NSUInteger numberOfScheduledBlocks;
 - (void)performBlockOnMainThread:(dispatch_block_t)block;
 
 @end

Source/Details/ASMainSerialQueue.mm

@@ -40,6 +40,11 @@ - (instancetype)init
   return self;
 }
 
+- (NSUInteger)numberOfScheduledBlocks
+{
+  return _blocks.count;
+}
+
 - (void)performBlockOnMainThread:(dispatch_block_t)block
 {
   ASDN::MutexLocker l(_serialQueueLock);

Tests/ASCollectionViewTests.mm

@@ -1050,8 +1050,17 @@ - (void)testInitialRangeBounds
   // Trigger the initial reload to start
   [window layoutIfNeeded];
 
+  // Test the APIs that monitor ASCollectionNode update handling
+  XCTAssertTrue(cn.isProcessingUpdates, @"ASCollectionNode should still be processing updates after initial layoutIfNeeded call (reloadData)");
+  [cn onDidFinishProcessingUpdates:^{
+    XCTAssertTrue(!cn.isProcessingUpdates, @"ASCollectionNode should no longer be processing updates inside -onDidFinishProcessingUpdates: block");
+  }];
+
   // Wait for ASDK reload to finish
   [cn waitUntilAllUpdatesAreCommitted];
+
+  XCTAssertTrue(!cn.isProcessingUpdates, @"ASCollectionNode should no longer be processing updates after -wait call");
+
   // Force UIKit to read updated data & range controller to update and account for it
   [cn.view layoutIfNeeded];