sync: Gracefully handle very early shutdown

sync/internal_api/public/base/cancellation_signal.h

+// Copyright (c) 2013 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 SYNC_INTERNAL_API_PUBLIC_BASE_ABORT_SIGNALLER_H_
+#define SYNC_INTERNAL_API_PUBLIC_BASE_ABORT_SIGNALLER_H_
+
+#include "base/synchronization/lock.h"
+#include "sync/base/sync_export.h"
+
+namespace syncer {
+
+class CancellationObserver;
+
+// This class is used to allow one thread to request that another abort and
+// return early.
+//
+// The signalling thread owns this class and my call RequestStop() at any time.
+// After that call, this class' IsStopRequested() will always return true.  The
+// intended use case is that the task intending to support early exit will
+// periodically check the value of IsStopRequested() to see if it should return
+// early.
+//
+// The receiving task may also choose to register an CancellationObserver whose
+// OnStopRequested() method will be executed on the signaller's thread when
+// RequestStop() is called.  This may be used for sending an early Signal() to a
+// WaitableEvent.  The registration of the handler is necessarily racy.  If
+// RequestStop() is executes before TryRegisterHandler(), TryRegisterHandler()
+// will not perform any registration and return false.  That function's caller
+// must handle this case.
+//
+// This class supports only one handler, though it could easily support multiple
+// observers if we found a use case for such a feature.
+class SYNC_EXPORT_PRIVATE CancellationSignal {
+ public:
+  CancellationSignal();
+  ~CancellationSignal();
+
+  // Tries to register a handler to be invoked when RequestStop() is called.
+  //
+  // If RequestStop() has already been called, returns false without registering
+  // the handler.  Returns true when the registration is successful.
+  //
+  // If the registration was successful, the handler must be unregistered with
+  // UnregisterHandler before this CancellationSignal is destroyed.
+  bool TryRegisterHandler(CancellationObserver* handler);
+
+  // Unregisters the abort handler.
+  void UnregisterHandler(CancellationObserver* handler);
+
+  // Returns true if RequestStop() has been called.
+  bool IsStopRequested();
+
+  // Sets the stop_requested_ flag and calls the OnStopRequested() method of the
+  // registered handler, if one exists.

[akalin, 2013/09/05 16:06:35]

might want to mention that OnStopRequested() is called under lock.

[rlarocque, 2013/09/05 22:37:06]

Done.

+  void RequestStop();
+
+ private:
+  // Protects all members of this class.
+  base::Lock stop_requested_lock_;
+
+  // True if RequestStop() has been invoked.
+  bool stop_requested_;
+
+  // The registered abort handler.  May be NULL.
+  CancellationObserver* handler_;
+};
+
+}  // namespace syncer
+
+#endif  // SYNC_INTERNAL_API_PUBLIC_BASE_ABORT_SIGNALLER_H_