sync/engine/sync_scheduler.h

   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
  19 namespace tracked_objects {
  20 class Location;
  21 }  // namespace tracked_objects
  22
  23 namespace syncer {
  24
  25 struct ServerConnectionEvent;
  26
  27 struct 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
  49 struct SYNC_EXPORT_PRIVATE ClearParams {
  50   ClearParams(const base::Closure& report_success_task);
  51   ~ClearParams();
  52
  53   // Callback to invoke on successful completion.
  54   base::Closure report_success_task;
  55 };
  56
  57 class SYNC_EXPORT_PRIVATE SyncScheduler
  58     : public sessions::SyncSession::Delegate {
  59  public:
  60   enum Mode {
  61     // In this mode, the thread only performs configuration tasks.  This is
  62     // designed to make the case where we want to download updates for a
  63     // specific type only, and not continue syncing until we are moved into
  64     // normal mode.
  65     CONFIGURATION_MODE,
  66     // This mode is used to issue a clear server data command.  The scheduler
  67     // may only transition to this mode from the CONFIGURATION_MODE.  When in
  68     // this mode, the only schedulable operation is |SchedulerClearServerData|.
  69     CLEAR_SERVER_DATA_MODE,
  70     // Resumes polling and allows nudges, drops configuration tasks.  Runs
  71     // through entire sync cycle.
  72     NORMAL_MODE,
  73   };
  74
  75   // All methods of SyncScheduler must be called on the same thread
  76   // (except for RequestEarlyExit()).
  77
  78   SyncScheduler();
  79   ~SyncScheduler() override;
  80
  81   // Start the scheduler with the given mode.  If the scheduler is
  82   // already started, switch to the given mode, although some
  83   // scheduled tasks from the old mode may still run. |last_poll_time| will
  84   // be used to decide what the poll timer should be initialized with.
  85   virtual void Start(Mode mode, base::Time last_poll_time) = 0;
  86
  87   // Schedules the configuration task specified by |params|. Returns true if
  88   // the configuration task executed immediately, false if it had to be
  89   // scheduled for a later attempt. |params.ready_task| is invoked whenever the
  90   // configuration task executes. |params.retry_task| is invoked once if the
  91   // configuration task could not execute. |params.ready_task| will still be
  92   // called when configuration finishes.
  93   // Note: must already be in CONFIGURATION mode.
  94   virtual void ScheduleConfiguration(const ConfigurationParams& params) = 0;
  95
  96   // Schedules clear of server data in preparation for transitioning to
  97   // passphrase encryption. The scheduler must be in CLEAR_SERVER_DATA_MODE
  98   // before calling this method.
  99   virtual void ScheduleClearServerData(const ClearParams& params) = 0;
 100
 101   // Request that the syncer avoid starting any new tasks and prepare for
 102   // shutdown.
 103   virtual void Stop() = 0;
 104
 105   // The meat and potatoes. All three of the following methods will post a
 106   // delayed task to attempt the actual nudge (see ScheduleNudgeImpl).
 107   //
 108   // NOTE: |desired_delay| is best-effort. If a nudge is already scheduled to
 109   // depart earlier than Now() + delay, the scheduler can and will prefer to
 110   // batch the two so that only one nudge is sent (at the earlier time). Also,
 111   // as always with delayed tasks and timers, it's possible the task gets run
 112   // any time after |desired_delay|.
 113
 114   // The LocalNudge indicates that we've made a local change, and that the
 115   // syncer should plan to commit this to the server some time soon.
 116   virtual void ScheduleLocalNudge(
 117       ModelTypeSet types,
 118       const tracked_objects::Location& nudge_location) = 0;
 119
 120   // The LocalRefreshRequest occurs when we decide for some reason to manually
 121   // request updates.  This should be used sparingly.  For example, one of its
 122   // uses is to fetch the latest tab sync data when it's relevant to the UI on
 123   // platforms where tab sync is not registered for invalidations.
 124   virtual void ScheduleLocalRefreshRequest(
 125       ModelTypeSet types,
 126       const tracked_objects::Location& nudge_location) = 0;
 127
 128   // Invalidations are notifications the server sends to let us know when other
 129   // clients have committed data.  We need to contact the sync server (being
 130   // careful to pass along the "hints" delivered with those invalidations) in
 131   // order to fetch the update.
 132   virtual void ScheduleInvalidationNudge(
 133       syncer::ModelType type,
 134       scoped_ptr<InvalidationInterface> invalidation,
 135       const tracked_objects::Location& nudge_location) = 0;
 136
 137   // Requests a non-blocking initial sync request for the specified type.
 138   //
 139   // Many types can only complete initial sync while the scheduler is in
 140   // configure mode, but a few of them are able to perform their initial sync
 141   // while the scheduler is in normal mode.  This non-blocking initial sync
 142   // can be requested through this function.
 143   virtual void ScheduleInitialSyncNudge(syncer::ModelType model_type) = 0;
 144
 145   // Change status of notifications in the SyncSessionContext.
 146   virtual void SetNotificationsEnabled(bool notifications_enabled) = 0;
 147
 148   // Called when credentials are updated by the user.
 149   virtual void OnCredentialsUpdated() = 0;
 150
 151   // Called when the network layer detects a connection status change.
 152   virtual void OnConnectionStatusChange() = 0;
 153 };
 154
 155 }  // namespace syncer
 156
 157 #endif  // SYNC_ENGINE_SYNC_SCHEDULER_H_