SnapshotController implementation. It will be used in WebContentsObservers for Offline Pages - to d…

components/offline_pages/snapshot_controller.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef COMPONENTS_OFFLINE_PAGES_SNAPSHOT_CONTROLLER_H_
+#define COMPONENTS_OFFLINE_PAGES_SNAPSHOT_CONTROLLER_H_
+
+#include "base/memory/ref_counted.h"
+#include "base/memory/weak_ptr.h"
+#include "base/single_thread_task_runner.h"
+
+namespace offline_pages {
+
+// Takes various signals and produces StartSnapshot calls following a specific
+// policy. Can request snapshots multiple times per 'session'. Session can be
+// ended and another one started by calling Reset().
+// Main invariants:
+// - It never starts overlapping snapshots, Client reports when previous
+//   snapshot is done.
+// - If a snapshot is in process (pending), another snapshot attempt is
+//   abandoned w/o waiting for the completion of the current one.

[fgorski, 2016/04/25 04:28:45]

The part staring with "w/o" is not clear.
I presume you mean: the currently worked on snapshot is allowed to complete,
while the new one is ignored.

[Dmitry Titov, 2016/04/26 01:45:29]

Done.

+// - Some signals cause 'last' snapshot - no signals after those will cause

[fgorski, 2016/04/25 04:28:45]

some signals prevent more snapshots to be taken.

[Dmitry Titov, 2016/04/26 01:45:29]

Done.

+//   another snapshot. OnLoad is currently such signal.
+class SnapshotController {
+ public:
+  // kStateReady - listening to input, will start snapshot when needed.
+  // kStateSnapshotPending - snapshot is in progress, don't start another.
+  // kStateStopped - terminal state, no snapshots until reset.
+  enum class State { kStateReady, kStateSnapshotPending, kStateStopped };
+
+  // Client of the SnapshotController.
+  class  Client {
+   public:
+    // Invoked at a good moment to start a snapshot. May be invoked multiple
+    // times, but not in overlapping manner - waits until
+    // PreviousSnapshotCompleted() before the next StatrSnapshot().
+    // Client should overwrite the result of previous snapshot with the new one,
+    // it is assumed that later snapshots are better then previous.
+    // Returns true if the snapshot actually started.
+    virtual bool StartSnapshot() = 0;
+
+   protected:
+    virtual ~Client() {}
+  };
+
+  SnapshotController(
+      const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
+      SnapshotController::Client* client);
+  virtual ~SnapshotController();
+
+  // Resets the 'session', returning controller to initial state.
+  void Reset();
+
+  // Stops current session, no more Client::StartSnapshot calls will be
+  // invoked from the SnapshotController until current session is Reset().

[fgorski, 2016/04/25 04:28:46]

Is this meant to be called by the client? (I think so, based on the next
question.)

If not, is there a way to tell client that snapshot controller stopped?

Please document.

[Dmitry Titov, 2016/04/26 01:45:29]

Done.

+  void Stop();
+
+  // The way for Client to report that previously started snapshot is
+  // now completed (so the next one can be started).
+  void PreviousSnapshotCompleted();

[fgorski, 2016/04/25 04:28:45]

Since your state is kStateSnapshotPending I suggest this be named:
PendingSnapshotCompleteted for consistency.

[Dmitry Titov, 2016/04/26 01:45:29]

Done.

+
+  // Invoked from WebContentObserver::DocumentAvailableInMainFrame
+  void DocumentAvailableInMainFrame();
+
+  // Invoked from WebContentObserver::DocumentOnLoadCompletedInMainFrame
+  void DocumentOnLoadCompletedInMainFrame();
+
+  size_t GetDelayAfterDocumentAvailableForTest();
+
+ private:
+  void MaybeStartSnapshot();
+
+  scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
+  // Client owns this class.
+  SnapshotController::Client* client_;
+  SnapshotController::State state_;
+
+  base::WeakPtrFactory<SnapshotController> weak_ptr_factory_;
+
+  DISALLOW_COPY_AND_ASSIGN(SnapshotController);
+};
+
+}  // namespace offline_pages
+
+#endif  // COMPONENTS_OFFLINE_PAGES_SNAPSHOT_CONTROLLER_H_