sync/internal_api/public/base/cancelation_signal.h

   1 // Copyright 2013 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 #ifndef SYNC_INTERNAL_API_PUBLIC_BASE_CANCELATION_SIGNAL_H_
   6 #define SYNC_INTERNAL_API_PUBLIC_BASE_CANCELATION_SIGNAL_H_
   7
   8 #include "base/synchronization/lock.h"
   9 #include "sync/base/sync_export.h"
  10
  11 namespace syncer {
  12
  13 class CancelationObserver;
  14
  15 // This class is used to allow one thread to request that another abort and
  16 // return early.
  17 //
  18 // The signalling thread owns this class and my call Signal() at any time.
  19 // After that call, this class' IsSignalled() will always return true.  The
  20 // intended use case is that the task intending to support early exit will
  21 // periodically check the value of IsSignalled() to see if it should return
  22 // early.
  23 //
  24 // The receiving task may also choose to register an CancelationObserver whose
  25 // OnSignalReceived() method will be executed on the signaller's thread when
  26 // Signal() is called.  This may be used for sending an early Signal() to a
  27 // WaitableEvent.  The registration of the handler is necessarily racy.  If
  28 // Signal() is executes before TryRegisterHandler(), TryRegisterHandler() will
  29 // not perform any registration and return false.  That function's caller must
  30 // handle this case.
  31 //
  32 // This class supports only one handler, though it could easily support multiple
  33 // observers if we found a use case for such a feature.
  34 class SYNC_EXPORT_PRIVATE CancelationSignal {
  35  public:
  36   CancelationSignal();
  37   ~CancelationSignal();
  38
  39   // Tries to register a handler to be invoked when Signal() is called.
  40   //
  41   // If Signal() has already been called, returns false without registering
  42   // the handler.  Returns true when the registration is successful.
  43   //
  44   // If the registration was successful, the handler must be unregistered with
  45   // UnregisterHandler before this CancelationSignal is destroyed.
  46   bool TryRegisterHandler(CancelationObserver* handler);
  47
  48   // Unregisters the abort handler.
  49   void UnregisterHandler(CancelationObserver* handler);
  50
  51   // Returns true if Signal() has been called.
  52   bool IsSignalled();
  53
  54   // Sets the stop_requested_ flag and calls the OnSignalReceived() method of
  55   // the registered handler, if there is one registered at the time.
  56   // SignalReceived() will be called with the |signal_lock_| held.
  57   void Signal();
  58
  59  private:
  60   // Protects all members of this class.
  61   base::Lock signal_lock_;
  62
  63   // True if Signal() has been invoked.
  64   bool signalled_;
  65
  66   // The registered abort handler.  May be NULL.
  67   CancelationObserver* handler_;
  68 };
  69
  70 }  // namespace syncer
  71
  72 #endif  // SYNC_INTERNAL_API_PUBLIC_BASE_CANCELATION_SIGNAL_H_