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