feat($rootScope): allow suspending and resuming watchers on scope

This can be very helpful for external modules that help making the digest
loop faster by ignoring some of the watchers under some circumstance.
Example: https://github.com/shahata/angular-viewport-watch

Thanks to @shahata for the original implementation.

Closes #5301

Author: petebacondarwin

src/ng/rootScope.js

@@ -91,6 +91,7 @@ function $RootScopeProvider() {
       this.$$watchersCount = 0;
       this.$id = nextUid();
       this.$$ChildScope = null;
+      this.$$suspended = false;
     }
     ChildScope.prototype = parent;
     return ChildScope;
@@ -178,6 +179,7 @@ function $RootScopeProvider() {
                      this.$$childHead = this.$$childTail = null;
       this.$root = this;
       this.$$destroyed = false;
+      this.$$suspended = false;
       this.$$listeners = {};
       this.$$listenerCount = {};
       this.$$watchersCount = 0;
@@ -811,7 +813,7 @@ function $RootScopeProvider() {
 
           traverseScopesLoop:
           do { // "traverse the scopes" loop
-            if ((watchers = current.$$watchers)) {
+            if ((watchers = !current.$$suspended && current.$$watchers)) {
               // process our watches
               watchers.$$digestWatchIndex = watchers.length;
               while (watchers.$$digestWatchIndex--) {
@@ -855,7 +857,7 @@ function $RootScopeProvider() {
             // Insanity Warning: scope depth-first traversal
             // yes, this code is a bit crazy, but it works and we have tests to prove it!
             // this piece should be kept in sync with the traversal in $broadcast
-            if (!(next = ((current.$$watchersCount && current.$$childHead) ||
+            if (!(next = ((!current.$$suspended && current.$$watchersCount && current.$$childHead) ||
                 (current !== target && current.$$nextSibling)))) {
               while (current !== target && !(next = current.$$nextSibling)) {
                 current = current.$parent;
@@ -892,6 +894,94 @@ function $RootScopeProvider() {
         $browser.$$checkUrlChange();
       },
 
+      /**
+       * @ngdoc method
+       * @name $rootScope.Scope#$suspend
+       * @kind function
+       *
+       * @description
+       * Suspend watchers of this scope subtree so that they will not be invoked during digest.
+       *
+       * This can be used to optimize your application when you know that running those watchers
+       * is redundant.
+       *
+       * **Warning**
+       *
+       * Suspending scopes from the digest cycle can have unwanted and difficult to debug results.
+       * Only use this approach if you are confident that you know what you are doing and have
+       * ample tests to ensure that bindings get updated as you expect.
+       *
+       * Some of the things to consider are:
+       *
+       * * Any external event on a directive/component will not trigger a digest while the hosting
+       *   scope is suspended - even if the event handler calls `$apply` or `$digest`.
+       * * Transcluded content exists on a scope that inherits from outside a directive but exists
+       *   as a child of the directive's containing scope. If the containing scope is suspended the
+       *   transcluded scope will also be suspended, even if the scope from which the transcluded
+       *   scope inherits is not suspended.
+       * * Multiple directives trying to manage the suspended status of a scope can confuse each other:
+       *    * A call to `$suspend` an already suspended scope is a no-op.
+       *    * A call to `$resume` a non-suspended scope is a no-op.
+       *    * If two directives suspend a scope, then one of them resumes the scope, the scope will no
+       *      longer be suspended. This could result in the other directive believing a scope to be
+       *      suspended when it is not.
+       * * If a parent scope is suspended then all its descendants will be excluded from future digests
+       *   whether or not they have been suspended themselves. Note that this also applies to isolate
+       *   child scopes.
+       * * Calling `$resume()` on a scope that has a suspended ancestor will not cause the scope to be
+       *   included in future digests until all its ancestors have been resumed.
+       * * Resolved promises, e.g. from explicit `$q` deferreds and `$http` calls, trigger `$apply`
+       *   against the `$rootScope` and so will still trigger a global digest even if the promise was
+       *   initialized by a component that lives on a suspended scope.
+       */
+      $suspend: function() {
+        this.$$suspended = true;
+      },
+
+      /**
+       * @ngdoc method
+       * @name $rootScope.Scope#$isSuspended
+       * @kind function
+       *
+       * @description
+       * Call this method to determine if this scope or one of its ancestors have been suspended.
+       *
+       * Be aware that a scope may not be included in digests if it has a suspended ancestor,
+       * even if `$isSuspended()` returns false.
+       *
+       * To determine if this scope will be excluded in digests then you must check all its ancestors:
+       *
+       * ```
+       * function isExcludedFromDigest(scope) {
+       *   while(scope) {
+       *     if (scope.$isSuspended()) return true;
+       *     scope = scope.$parent;
+       *   }
+       *   return false;
+       * ```
+       *
+       * @returns true if the current scope has been suspended.
+       */
+      $isSuspended: function() {
+        return this.$$suspended;
+      },
+
+      /**
+       * @ngdoc method
+       * @name $rootScope.Scope#$resume
+       * @kind function
+       *
+       * @description
+       * Resume watchers of this scope subtree in case it was suspended.
+       *
+       * It is recommended to digest on this scope after it is resumed to catch any modifications
+       * that might have happened while it was suspended.
+       *
+       * See {@link $rootScope.Scope#$suspend} for information about the dangers of using this approach.
+       */
+      $resume: function() {
+        this.$$suspended = false;
+      },
 
       /**
        * @ngdoc event

test/ng/rootScopeSpec.js

@@ -1255,6 +1255,84 @@ describe('Scope', function() {
       });
     });
 
+
+    describe('$suspend/$resume', function() {
+      it('should suspend watchers on scope', inject(function($rootScope) {
+        var watchSpy = jasmine.createSpy('watchSpy');
+        $rootScope.$watch(watchSpy);
+        $rootScope.$suspend();
+        $rootScope.$digest();
+        expect(watchSpy).not.toHaveBeenCalled();
+      }));
+
+      it('should resume watchers on scope', inject(function($rootScope) {
+        var watchSpy = jasmine.createSpy('watchSpy');
+        $rootScope.$watch(watchSpy);
+        $rootScope.$suspend();
+        $rootScope.$resume();
+        $rootScope.$digest();
+        expect(watchSpy).toHaveBeenCalled();
+      }));
+
+      it('should suspend watchers on child scope', inject(function($rootScope) {
+        var watchSpy = jasmine.createSpy('watchSpy');
+        var scope = $rootScope.$new(true);
+        scope.$watch(watchSpy);
+        $rootScope.$suspend();
+        $rootScope.$digest();
+        expect(watchSpy).not.toHaveBeenCalled();
+      }));
+
+      it('should resume watchers on child scope', inject(function($rootScope) {
+        var watchSpy = jasmine.createSpy('watchSpy');
+        var scope = $rootScope.$new(true);
+        scope.$watch(watchSpy);
+        $rootScope.$suspend();
+        $rootScope.$resume();
+        $rootScope.$digest();
+        expect(watchSpy).toHaveBeenCalled();
+      }));
+
+      it('should not suspend watchers on parent or sibling scopes', inject(function($rootScope) {
+        var watchSpyParent = jasmine.createSpy('watchSpyParent');
+        var watchSpyChild = jasmine.createSpy('watchSpyChild');
+        var watchSpySibling = jasmine.createSpy('watchSpySibling');
+
+        var parent = $rootScope.$new();
+        parent.$watch(watchSpyParent);
+        var child = parent.$new();
+        child.$watch(watchSpyChild);
+        var sibling = parent.$new();
+        sibling.$watch(watchSpySibling);
+
+        child.$suspend();
+        $rootScope.$digest();
+        expect(watchSpyParent).toHaveBeenCalled();
+        expect(watchSpyChild).not.toHaveBeenCalled();
+        expect(watchSpySibling).toHaveBeenCalled();
+      }));
+
+      it('should return true from `$isSuspended()` when a scope is suspended', inject(function($rootScope) {
+        $rootScope.$suspend();
+        expect($rootScope.$isSuspended()).toBe(true);
+        $rootScope.$resume();
+        expect($rootScope.$isSuspended()).toBe(false);
+      }));
+
+      it('should return false from `$isSuspended()` for a non-suspended scope that has a suspended ancestor', inject(function($rootScope) {
+        var childScope = $rootScope.$new();
+        $rootScope.$suspend();
+        expect(childScope.$isSuspended()).toBe(false);
+        childScope.$suspend();
+        expect(childScope.$isSuspended()).toBe(true);
+        childScope.$resume();
+        expect(childScope.$isSuspended()).toBe(false);
+        $rootScope.$resume();
+        expect(childScope.$isSuspended()).toBe(false);
+      }));
+    });
+
+
     describe('optimizations', function() {
 
       function setupWatches(scope, log) {