1// Copyright 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4//
5// A class to schedule syncer tasks intelligently.
6#ifndef SYNC_ENGINE_SYNC_SCHEDULER_H_
7#define SYNC_ENGINE_SYNC_SCHEDULER_H_
8
9#include <string>
10
11#include "base/callback.h"
12#include "base/compiler_specific.h"
13#include "base/time/time.h"
14#include "sync/base/sync_export.h"
15#include "sync/engine/nudge_source.h"
16#include "sync/internal_api/public/base/invalidation_interface.h"
17#include "sync/sessions/sync_session.h"
18
19namespace tracked_objects {
20class Location;
21}  // namespace tracked_objects
22
23namespace syncer {
24
25struct ServerConnectionEvent;
26
27struct SYNC_EXPORT_PRIVATE ConfigurationParams {
28  ConfigurationParams();
29  ConfigurationParams(
30      const sync_pb::GetUpdatesCallerInfo::GetUpdatesSource& source,
31      ModelTypeSet types_to_download,
32      const ModelSafeRoutingInfo& routing_info,
33      const base::Closure& ready_task,
34      const base::Closure& retry_task);
35  ~ConfigurationParams();
36
37  // Source for the configuration.
38  sync_pb::GetUpdatesCallerInfo::GetUpdatesSource source;
39  // The types that should be downloaded.
40  ModelTypeSet types_to_download;
41  // The new routing info (superset of types to be downloaded).
42  ModelSafeRoutingInfo routing_info;
43  // Callback to invoke on configuration completion.
44  base::Closure ready_task;
45  // Callback to invoke on configuration failure.
46  base::Closure retry_task;
47};
48
49class SYNC_EXPORT_PRIVATE SyncScheduler
50    : public sessions::SyncSession::Delegate {
51 public:
52  enum Mode {
53    // In this mode, the thread only performs configuration tasks.  This is
54    // designed to make the case where we want to download updates for a
55    // specific type only, and not continue syncing until we are moved into
56    // normal mode.
57    CONFIGURATION_MODE,
58    // Resumes polling and allows nudges, drops configuration tasks.  Runs
59    // through entire sync cycle.
60    NORMAL_MODE,
61  };
62
63  // All methods of SyncScheduler must be called on the same thread
64  // (except for RequestEarlyExit()).
65
66  SyncScheduler();
67  virtual ~SyncScheduler();
68
69  // Start the scheduler with the given mode.  If the scheduler is
70  // already started, switch to the given mode, although some
71  // scheduled tasks from the old mode may still run.
72  virtual void Start(Mode mode) = 0;
73
74  // Schedules the configuration task specified by |params|. Returns true if
75  // the configuration task executed immediately, false if it had to be
76  // scheduled for a later attempt. |params.ready_task| is invoked whenever the
77  // configuration task executes. |params.retry_task| is invoked once if the
78  // configuration task could not execute. |params.ready_task| will still be
79  // called when configuration finishes.
80  // Note: must already be in CONFIGURATION mode.
81  virtual void ScheduleConfiguration(const ConfigurationParams& params) = 0;
82
83  // Request that the syncer avoid starting any new tasks and prepare for
84  // shutdown.
85  virtual void Stop() = 0;
86
87  // The meat and potatoes. All three of the following methods will post a
88  // delayed task to attempt the actual nudge (see ScheduleNudgeImpl).
89  //
90  // NOTE: |desired_delay| is best-effort. If a nudge is already scheduled to
91  // depart earlier than Now() + delay, the scheduler can and will prefer to
92  // batch the two so that only one nudge is sent (at the earlier time). Also,
93  // as always with delayed tasks and timers, it's possible the task gets run
94  // any time after |desired_delay|.
95
96  // The LocalNudge indicates that we've made a local change, and that the
97  // syncer should plan to commit this to the server some time soon.
98  virtual void ScheduleLocalNudge(
99      ModelTypeSet types,
100      const tracked_objects::Location& nudge_location) = 0;
101
102  // The LocalRefreshRequest occurs when we decide for some reason to manually
103  // request updates.  This should be used sparingly.  For example, one of its
104  // uses is to fetch the latest tab sync data when it's relevant to the UI on
105  // platforms where tab sync is not registered for invalidations.
106  virtual void ScheduleLocalRefreshRequest(
107      ModelTypeSet types,
108      const tracked_objects::Location& nudge_location) = 0;
109
110  // Invalidations are notifications the server sends to let us know when other
111  // clients have committed data.  We need to contact the sync server (being
112  // careful to pass along the "hints" delivered with those invalidations) in
113  // order to fetch the update.
114  virtual void ScheduleInvalidationNudge(
115      syncer::ModelType type,
116      scoped_ptr<InvalidationInterface> invalidation,
117      const tracked_objects::Location& nudge_location) = 0;
118
119  // Requests a non-blocking initial sync request for the specified type.
120  //
121  // Many types can only complete initial sync while the scheduler is in
122  // configure mode, but a few of them are able to perform their initial sync
123  // while the scheduler is in normal mode.  This non-blocking initial sync
124  // can be requested through this function.
125  virtual void ScheduleInitialSyncNudge(syncer::ModelType model_type) = 0;
126
127  // Change status of notifications in the SyncSessionContext.
128  virtual void SetNotificationsEnabled(bool notifications_enabled) = 0;
129
130  // Called when credentials are updated by the user.
131  virtual void OnCredentialsUpdated() = 0;
132
133  // Called when the network layer detects a connection status change.
134  virtual void OnConnectionStatusChange() = 0;
135};
136
137}  // namespace syncer
138
139#endif  // SYNC_ENGINE_SYNC_SCHEDULER_H_
140