Retry: sync: Gracefully handle early shutdown

sync/internal_api/public/base/cancelation_signal.h

+// Copyright 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_CANCELATION_SIGNAL_H_
+#define SYNC_INTERNAL_API_PUBLIC_BASE_CANCELATION_SIGNAL_H_
+
+#include "base/synchronization/lock.h"
+#include "sync/base/sync_export.h"
+
+namespace syncer {
+
+class CancelationObserver;
+
+// 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 Signal() at any time.
+// After that call, this class' IsSignalled() will always return true.  The
+// intended use case is that the task intending to support early exit will
+// periodically check the value of IsSignalled() to see if it should return
+// early.
+//
+// The receiving task may also choose to register an CancelationObserver whose
+// OnSignalReceived() method will be executed on the signaller's thread when
+// Signal() is called.  This may be used for sending an early Signal() to a
+// WaitableEvent.  The registration of the handler is necessarily racy.  If
+// Signal() 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 CancelationSignal {
+ public:
+  CancelationSignal();
+  ~CancelationSignal();
+
+  // Tries to register a handler to be invoked when Signal() is called.
+  //
+  // If Signal() 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 CancelationSignal is destroyed.
+  bool TryRegisterHandler(CancelationObserver* handler);
+
+  // Unregisters the abort handler.
+  void UnregisterHandler(CancelationObserver* handler);
+
+  // Returns true if Signal() has been called.
+  bool IsSignalled();
+
+  // Sets the stop_requested_ flag and calls the OnSignalReceived() method of
+  // the registered handler, if there is one registered at the time.
+  // SignalReceived() will be called with the |signal_lock_| held.
+  void Signal();
+
+ private:
+  // Protects all members of this class.
+  base::Lock signal_lock_;
+
+  // True if Signal() has been invoked.
+  bool signalled_;
+
+  // The registered abort handler.  May be NULL.
+  CancelationObserver* handler_;
+};
+
+}  // namespace syncer
+
+#endif  // SYNC_INTERNAL_API_PUBLIC_BASE_CANCELATION_SIGNAL_H_