[Layout Transition API] Simplify applying layout transition (#1886)

* Simplify applying layout transition in preparation for bigger layout transition API work

* Change from apply to complete in if layout transitions are involved and _applyLayout: to _setCalculatedLayout: for layout

* Change to applySubnodeInsertions and applySubnodeRemovals

* Change from completeTransition to commitTransition and flip logic around when to trampoline to the main thread for implicit hierarchy management

* More internal API improvements

* Fix merge conflicts

* Rename _layout to _calculatedLayout

Author: maicki

AsyncDisplayKit/ASDisplayNode.mm

@@ -642,30 +642,23 @@ - (ASLayout *)measureWithSizeRange:(ASSizeRange)constrainedSize
 {
   ASDN::MutexLocker l(__instanceLock__);
   if (! [self shouldMeasureWithSizeRange:constrainedSize]) {
-    return _layout;
+    return _calculatedLayout;
   }
 
   [self cancelLayoutTransitionsInProgress];
 
-  ASLayout *previousLayout = _layout;
+  ASLayout *previousLayout = _calculatedLayout;
   ASLayout *newLayout = [self calculateLayoutThatFits:constrainedSize];
 
-  if (ASHierarchyStateIncludesLayoutPending(_hierarchyState)) {
-    _pendingLayoutTransition = [[ASLayoutTransition alloc] initWithNode:self
-                                                          pendingLayout:newLayout
-                                                         previousLayout:previousLayout];
-  } else {
-    ASLayoutTransition *layoutTransition = nil;
-    if (self.usesImplicitHierarchyManagement) {
-      layoutTransition = [[ASLayoutTransition alloc] initWithNode:self
-                                                    pendingLayout:newLayout
-                                                   previousLayout:previousLayout];
-    }
-    
-    [self _applyLayout:newLayout layoutTransition:layoutTransition];
-    [self _completeLayoutCalculation];
+  _pendingLayoutTransition = [[ASLayoutTransition alloc] initWithNode:self
+                                                        pendingLayout:newLayout
+                                                       previousLayout:previousLayout];
+  
+  if (ASHierarchyStateIncludesLayoutPending(_hierarchyState) == NO) {
+    // Complete the pending layout transition immediately
+    [self _completePendingLayoutTransition];
   }
-
+  
   return newLayout;
 }
 
@@ -686,12 +679,12 @@ - (BOOL)shouldMeasureWithSizeRange:(ASSizeRange)constrainedSize
   // Only generate a new layout if:
   // - The current layout is dirty
   // - The passed constrained size is different than the layout's constrained size
-  return ([self _hasDirtyLayout] || !ASSizeRangeEqualToSizeRange(constrainedSize, _layout.constrainedSizeRange));
+  return ([self _hasDirtyLayout] || !ASSizeRangeEqualToSizeRange(constrainedSize, _calculatedLayout.constrainedSizeRange));
 }
 
 - (BOOL)_hasDirtyLayout
 {
-  return _layout == nil || _layout.isDirty;
+  return _calculatedLayout == nil || _calculatedLayout.isDirty;
 }
 
 - (ASLayoutableType)layoutableType
@@ -710,13 +703,14 @@ - (void)transitionLayoutWithAnimation:(BOOL)animated
                    shouldMeasureAsync:(BOOL)shouldMeasureAsync
                 measurementCompletion:(void(^)())completion
 {
-  if (_layout == nil) {
+  if (_calculatedLayout == nil) {
     // constrainedSizeRange returns a struct and is invalid to call on nil.
     // Defaulting to CGSizeZero can cause negative values in client layout code.
     return;
   }
+  
   [self invalidateCalculatedLayout];
-  [self transitionLayoutWithSizeRange:_layout.constrainedSizeRange
+  [self transitionLayoutWithSizeRange:_calculatedLayout.constrainedSizeRange
                              animated:animated
                    shouldMeasureAsync:shouldMeasureAsync
                 measurementCompletion:completion];
@@ -778,12 +772,11 @@ - (void)transitionLayoutWithSizeRange:(ASSizeRange)constrainedSize
         return;
       }
 
-      ASLayout *previousLayout = _layout;
-      [self _applyLayout:newLayout layoutTransition:nil];
+      ASLayout *previousLayout = _calculatedLayout;
+      [self setCalculatedLayout:newLayout];
 
       ASDisplayNodePerformBlockOnEverySubnode(self, ^(ASDisplayNode * _Nonnull node) {
-        [node _applyPendingLayoutContext];
-        [node _completeLayoutCalculation];
+        [node _completePendingLayoutTransition];
         node.hierarchyState &= (~ASHierarchyStateLayoutPending);
       });
 
@@ -793,48 +786,26 @@ - (void)transitionLayoutWithSizeRange:(ASSizeRange)constrainedSize
         completion();
       }
 
+      // Setup pending layout transition for animation
       _pendingLayoutTransition = [[ASLayoutTransition alloc] initWithNode:self
                                                             pendingLayout:newLayout
-                                                          previousLayout:previousLayout];
+                                                           previousLayout:previousLayout];
+      // Setup context for pending layout transition. we need to hold a strong reference to the context
+      _pendingLayoutTransitionContext = [[_ASTransitionContext alloc] initWithAnimation:animated
+                                                                         layoutDelegate:_pendingLayoutTransition
+                                                                     completionDelegate:self];
+      
+      // Apply the subnode insertion immediately to be able to animate the nodes
       [_pendingLayoutTransition applySubnodeInsertions];
-
-      _transitionContext = [[_ASTransitionContext alloc] initWithAnimation:animated
-                                                            layoutDelegate:_pendingLayoutTransition
-                                                        completionDelegate:self];
-      [self animateLayoutTransition:_transitionContext];
+      
+      // Kick off animating the layout transition
+      [self animateLayoutTransition:_pendingLayoutTransitionContext];
     });
   };
 
   ASPerformBlockOnBackgroundThread(transitionBlock);
 }
 
-- (void)_completeLayoutCalculation
-{
-  ASDN::MutexLocker l(__instanceLock__);
-  [self calculatedLayoutDidChange];
-
-  // We generate placeholders at measureWithSizeRange: time so that a node is guaranteed to have a placeholder ready to go.
-  // This is also because measurement is usually asynchronous, but placeholders need to be set up synchronously.
-  // First measurement is guaranteed to be before the node is onscreen, so we can create the image async. but still have it appear sync.
-  if (_placeholderEnabled && [self _displaysAsynchronously] && self.contents == nil) {
-    
-    // Zero-sized nodes do not require a placeholder.
-    CGSize layoutSize = (_layout ? _layout.size : CGSizeZero);
-    if (CGSizeEqualToSize(layoutSize, CGSizeZero)) {
-      return;
-    }
-
-    if (!_placeholderImage) {
-      _placeholderImage = [self placeholderImage];
-    }
-  }
-}
-
-- (void)calculatedLayoutDidChange
-{
-  // subclass override
-}
-
 - (void)cancelLayoutTransitionsInProgress
 {
   ASDN::MutexLocker l(__instanceLock__);
@@ -888,25 +859,108 @@ - (BOOL)_shouldAbortTransitionWithID:(int32_t)transitionID
   return (!_transitionInProgress || _transitionID != transitionID);
 }
 
+#pragma mark - Layout Transition API / ASDisplayNode (Beta)
+
+/*
+ * Hook for subclasse to perform an animation based on the given ASContextTransitioning. By default this just layouts
+ * applies all subnodes without animation and calls completes the transition on the context.
+ */
 - (void)animateLayoutTransition:(id<ASContextTransitioning>)context
 {
-  [self __layoutSubnodes];
+  [self __layoutSublayouts];
   [context completeTransition:YES];
 }
 
+/*
+ * Hook for subclasses to clean up nodes after the transition happened. Furthermore this can be used from subclasses
+ * to manually perform deletions.
+ */
 - (void)didCompleteLayoutTransition:(id<ASContextTransitioning>)context
 {
   [_pendingLayoutTransition applySubnodeRemovals];
-  [self _completeLayoutCalculation];
-  _pendingLayoutTransition = nil;
 }
 
 #pragma mark - _ASTransitionContextCompletionDelegate
 
+/*
+ * After completeTransition: is called on the ASContextTransitioning object in animateLayoutTransition: this
+ * delegate method will be called that start the completion process of the 
+ */
 - (void)transitionContext:(_ASTransitionContext *)context didComplete:(BOOL)didComplete
 {
   [self didCompleteLayoutTransition:context];
-  _transitionContext = nil;
+  _pendingLayoutTransitionContext = nil;
+
+  [self _pendingLayoutTransitionDidComplete];
+}
+
+#pragma mark - Layout
+
+/*
+ * Completes the pending layout transition immediately without going through the the Layout Transition Animation API
+ */
+- (void)_completePendingLayoutTransition
+{
+  ASDN::MutexLocker l(__instanceLock__);
+  if (_pendingLayoutTransition) {
+    [self setCalculatedLayout:_pendingLayoutTransition.pendingLayout];
+    [self _completeLayoutTransition:_pendingLayoutTransition];
+  }
+  [self _pendingLayoutTransitionDidComplete];
+}
+
+/*
+ * Can be directly called to commit the given layout transition immediately to complete without calling through to the
+ * Layout Transition Animation API
+ */
+- (void)_completeLayoutTransition:(ASLayoutTransition *)layoutTransition
+{
+  // Layout transition is not supported for non implicit hierarchy managed nodes yet
+  if (layoutTransition == nil || self.usesImplicitHierarchyManagement == NO) {
+    return;
+  }
+
+  // Trampoline to the main thread if necessary
+  if (ASDisplayNodeThreadIsMain() || layoutTransition.isSynchronous == NO) {
+    [layoutTransition commitTransition];
+  } else {
+    // Subnode insertions and removals need to happen always on the main thread if at least one subnode is already loaded
+    ASPerformBlockOnMainThread(^{
+      [layoutTransition commitTransition];
+    });
+  }
+}
+
+- (void)_pendingLayoutTransitionDidComplete
+{
+  ASDN::MutexLocker l(__instanceLock__);
+  
+  // Subclass hook
+  [self calculatedLayoutDidChange];
+
+  // We generate placeholders at measureWithSizeRange: time so that a node is guaranteed to have a placeholder ready to go.
+  // This is also because measurement is usually asynchronous, but placeholders need to be set up synchronously.
+  // First measurement is guaranteed to be before the node is onscreen, so we can create the image async. but still have it appear sync.
+  if (_placeholderEnabled && [self _displaysAsynchronously] && self.contents == nil) {
+    
+    // Zero-sized nodes do not require a placeholder.
+    CGSize layoutSize = (_calculatedLayout ? _calculatedLayout.size : CGSizeZero);
+    if (CGSizeEqualToSize(layoutSize, CGSizeZero)) {
+      return;
+    }
+
+    if (!_placeholderImage) {
+      _placeholderImage = [self placeholderImage];
+    }
+  }
+  
+  // Cleanup pending layout transition
+  _pendingLayoutTransition = nil;
+}
+
+- (void)calculatedLayoutDidChange
+{
+  // subclass override
 }
 
 #pragma mark - Asynchronous display
@@ -1068,7 +1122,7 @@ - (void)__setNeedsLayout
 
   __instanceLock__.lock();
 
-  if (_layout == nil) {
+  if (_calculatedLayout == nil) {
     // Can't proceed without a layout as no constrained size would be available
     __instanceLock__.unlock();
     return;
@@ -1086,11 +1140,11 @@ - (void)__setNeedsLayout
   }
 
   // This is the root node. Trigger a full measurement pass on *current* thread. Old constrained size is re-used.
-  [self measureWithSizeRange:_layout.constrainedSizeRange];
+  [self measureWithSizeRange:_calculatedLayout.constrainedSizeRange];
 
   CGRect oldBounds = self.bounds;
   CGSize oldSize = oldBounds.size;
-  CGSize newSize = _layout.size;
+  CGSize newSize = _calculatedLayout.size;
 
   if (! CGSizeEqualToSize(oldSize, newSize)) {
     self.bounds = (CGRect){ oldBounds.origin, newSize };
@@ -1168,24 +1222,6 @@ - (void)measureNodeWithBoundsIfNecessary:(CGRect)bounds
   }
 }
 
-- (void)layout
-{
-  ASDisplayNodeAssertMainThread();
-  
-  if ([self _hasDirtyLayout]) {
-    return;
-  }
-  
-  [self __layoutSubnodes];
-}
-
-- (void)__layoutSubnodes
-{
-  for (ASLayout *subnodeLayout in _layout.sublayouts) {
-    ((ASDisplayNode *)subnodeLayout.layoutableObject).frame = [subnodeLayout frame];
-  }
-}
-
 - (void)layoutDidFinish
 {
   // Hook for subclasses
@@ -2080,19 +2116,30 @@ - (ASLayoutSpec *)layoutSpecThatFits:(ASSizeRange)constrainedSize
 - (ASLayout *)calculatedLayout
 {
   ASDN::MutexLocker l(__instanceLock__);
-  return _layout;
+  return _calculatedLayout;
+}
+
+- (void)setCalculatedLayout:(ASLayout *)calculatedLayout
+{
+  ASDN::MutexLocker l(__instanceLock__);
+  
+  ASDisplayNodeAssertTrue(calculatedLayout.layoutableObject == self);
+  ASDisplayNodeAssertTrue(calculatedLayout.size.width >= 0.0);
+  ASDisplayNodeAssertTrue(calculatedLayout.size.height >= 0.0);
+  
+  _calculatedLayout = calculatedLayout;
 }
 
 - (CGSize)calculatedSize
 {
   ASDN::MutexLocker l(__instanceLock__);
-  return _layout.size;
+  return _calculatedLayout.size;
 }
 
 - (ASSizeRange)constrainedSizeForCalculatedLayout
 {
   ASDN::MutexLocker l(__instanceLock__);
-  return _layout.constrainedSizeRange;
+  return _calculatedLayout.constrainedSizeRange;
 }
 
 - (void)setLayoutSpecBlock:(ASLayoutSpecBlock)layoutSpecBlock
@@ -2149,7 +2196,7 @@ - (void)invalidateCalculatedLayout
 
   // This will cause the next call to -measureWithSizeRange: to actually compute a new layout
   // instead of returning the current layout
-  _layout.dirty = YES;
+  _calculatedLayout.dirty = YES;
 }
 
 - (void)__didLoad
@@ -2516,7 +2563,7 @@ - (void)_applyPendingLayoutContext
 - (void)_applyLayout:(ASLayout *)layout layoutTransition:(ASLayoutTransition *)layoutTransition
 {
   ASDN::MutexLocker l(__instanceLock__);
-  _layout = layout;
+  _calculatedLayout = layout;
 
   ASDisplayNodeAssertTrue(layout.layoutableObject == self);
   ASDisplayNodeAssertTrue(layout.size.width >= 0.0);
@@ -2531,15 +2578,35 @@ - (void)_applyLayout:(ASLayout *)layout layoutTransition:(ASLayoutTransition *)l
 
     // Subnode insertions and removals need to happen always on the main thread if at least one subnode is already loaded
     ASPerformBlockOnMainThread(^{
-      [layoutTransition startTransition];
+      [layoutTransition commitTransition];
     });
 
     return;
   }
 
-  [layoutTransition startTransition];
+  [layoutTransition commitTransition];
 }
 
+- (void)layout
+{
+  ASDisplayNodeAssertMainThread();
+
+  if ([self _hasDirtyLayout]) {
+    return;
+  }
+  
+  [self __layoutSublayouts];
+}
+
+- (void)__layoutSublayouts
+{
+  for (ASLayout *subnodeLayout in _calculatedLayout.sublayouts) {
+    ((ASDisplayNode *)subnodeLayout.layoutableObject).frame = [subnodeLayout frame];
+  }
+}
+
+#pragma mark - Display
+
 - (void)displayWillStart
 {
   ASDisplayNodeAssertMainThread();