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
11namespace syncer {
12
13class 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.
34class 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