sync: make scheduling logic and job ownership more obvious.

sync/engine/sync_scheduler.h

 // Copyright (c) 2012 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.
 //
 // A class to schedule syncer tasks intelligently.
 #ifndef SYNC_ENGINE_SYNC_SCHEDULER_H_
 #define SYNC_ENGINE_SYNC_SCHEDULER_H_
 
 #include <string>
 
@@ skipping 67 matching lines @@
   // Request that any running syncer task stop as soon as possible and
   // cancel all scheduled tasks. This function can be called from any thread,
   // and should in fact be called from a thread that isn't the sync loop to
   // allow preempting ongoing sync cycles.
   // Invokes |callback| from the sync loop once syncer is idle and all tasks
   // are cancelled.
   virtual void RequestStop(const base::Closure& callback) = 0;
 
   // The meat and potatoes. Both of these methods will post a delayed task
   // to attempt the actual nudge (see ScheduleNudgeImpl).
+  // NOTE: |delay| is best-effort. If a nudge is already scheduled to depart

[rlarocque, 2012/09/24 21:15:14]

Rename to max_delay?  I think that would make the effect clear without requiring
a comment.

[akalin, 2012/09/25 22:37:24]

but it's not a max delay, right?  the nudge can happen anytime after the delay
(due to the nature of timers, delayed tasks, etc.)

delay_hint?

[tim (not reviewing), 2012/10/08 00:20:03]

I renamed to desired_delay (following the base/timer.h desired_run_time pattern)
but I still think the comment is interesting. I added to it to mention the fact
that it may happen later as well, although that part is arguably "status quo"
when interacting with timers / delayed tasks in Chrome... but let me know what
you think.  If you prefer delay_hint, I'm fine with that too.

+  // earlier than Now() + delay, the scheduler can and will prefer to batch
+  // the two so that only one nudge is sent (at the earlier time).
   virtual void ScheduleNudgeAsync(
       const base::TimeDelta& delay,
       NudgeSource source,
       ModelTypeSet types,
       const tracked_objects::Location& nudge_location) = 0;
   virtual void ScheduleNudgeWithStatesAsync(
       const base::TimeDelta& delay, NudgeSource source,
       const ModelTypeStateMap& type_state_map,
       const tracked_objects::Location& nudge_location) = 0;
 
   // Change status of notifications in the SyncSessionContext.
   virtual void SetNotificationsEnabled(bool notifications_enabled) = 0;
 
   virtual base::TimeDelta GetSessionsCommitDelay() const = 0;
 
   // Called when credentials are updated by the user.
   virtual void OnCredentialsUpdated() = 0;
 
   // Called when the network layer detects a connection status change.
   virtual void OnConnectionStatusChange() = 0;
 };
 
 }  // namespace syncer
 
 #endif  // SYNC_ENGINE_SYNC_SCHEDULER_H_