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_ 73
