SSL FailureLatch.h   Sprache: unbekannt

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

// This header contains an interface `FailureLatch`, and some implementation
// helpers that may be used across a range of classes and functions to handle
// failures at any point during a process, and share that failure state so that
// the process may gracefully stop quickly and report the first error.
//
// It could be thought as a replacement for C++ exceptions, but it's less strong
// (cancellations may be delayed).
// Now, if possible, mozilla::Result may be a better option as C++ exceptions
// replacement, as it is more visible in all affected functions.
// Consider FailureLatch if failures may happen in different places, but where
// `return`ing this potential failure from all functions would be too arduous.

#ifndef mozilla_FailureLatch_h
#define mozilla_FailureLatch_h

#include <mozilla/Assertions.h>

#include <string>

namespace mozilla {

// ----------------------------------------------------------------------------
// Main interface
// ----------------------------------------------------------------------------

// Interface handling a failure latch (starting in a successful state, the first
// failure gets recorded, subsequent failures are ignored.)
class FailureLatch {
 public:
  virtual ~FailureLatch() = default;

  // Can this ever fail? (This may influence how some code deals with
  // failures, e.g., if infallible, OOMs should assert&crash.)
  [[nodiscard]] virtual bool Fallible() const = 0;

  // Set latch in its failed state because of an external cause.
  // The first call sets the reason, subsequent calls are ignored.
  virtual void SetFailure(std::string aReason) = 0;

  // Has there been any failure so far?
  [[nodiscard]] virtual bool Failed() const = 0;

  // Return first failure string, may be null if not failed yet.
  [[nodiscard]] virtual const char* GetFailure() const = 0;

  // Retrieve the one source FailureLatch. It could reference `*this`!
  // This may be used by dependent proxy FailureLatch'es to find where to
  // redirect calls.
  [[nodiscard]] virtual const FailureLatch& SourceFailureLatch() const = 0;
  [[nodiscard]] virtual FailureLatch& SourceFailureLatch() = 0;

  // Non-virtual helpers.

  // Transfer any failure from another FailureLatch.
  void SetFailureFrom(const FailureLatch& aOther) {
    if (Failed()) {
      return;
    }
    if (const char* otherFailure = aOther.GetFailure(); otherFailure) {
      SetFailure(otherFailure);
    }
  }
};

// ----------------------------------------------------------------------------
// Concrete implementations
// ----------------------------------------------------------------------------

// Concrete infallible FailureLatch class.
// Any `SetFailure` leads to an assert-crash, so the final runtime result can
// always be assumed to be succesful.
class FailureLatchInfallibleSource final : public FailureLatch {
 public:
  [[nodiscard]] bool Fallible() const final { return false; }

  void SetFailure(std::string aReason) final {
    MOZ_RELEASE_ASSERT(false,
                       "SetFailure in infallible FailureLatchInfallibleSource");
  }

  [[nodiscard]] bool Failed() const final { return false; }

  [[nodiscard]] const char* GetFailure() const final { return nullptr; }

  [[nodiscard]] const ::mozilla::FailureLatch& SourceFailureLatch()
      const final {
    return *this;
  }

  [[nodiscard]] ::mozilla::FailureLatch& SourceFailureLatch() final {
    return *this;
  }

  // Singleton FailureLatchInfallibleSource that may be used as default
  // FailureLatch proxy.
  static FailureLatchInfallibleSource& Singleton() {
    static FailureLatchInfallibleSource singleton;
    return singleton;
  }
};

// Concrete FailureLatch class, intended to be intantiated as an object shared
// between classes and functions that are part of a long operation, so that
// failures can happen anywhere and be visible everywhere.
// Not thread-safe.
class FailureLatchSource final : public FailureLatch {
 public:
  [[nodiscard]] bool Fallible() const final { return true; }

  void SetFailure(std::string aReason) final {
    if (!mFailed) {
      mFailed = true;
      mReason = std::move(aReason);
    }
  }

  [[nodiscard]] bool Failed() const final { return mFailed; }

  [[nodiscard]] const char* GetFailure() const final {
    return mFailed ? mReason.c_str() : nullptr;
  }

  [[nodiscard]] const FailureLatch& SourceFailureLatch() const final {
    return *this;
  }

  [[nodiscard]] FailureLatch& SourceFailureLatch() final { return *this; }

 private:
  bool mFailed = false;
  std::string mReason;
};

// ----------------------------------------------------------------------------
// Helper macros, to be used in FailureLatch-derived classes
// ----------------------------------------------------------------------------

// Classes deriving from FailureLatch can use this to forward virtual calls to
// another FailureLatch.
#define FAILURELATCH_IMPL_PROXY(FAILURELATCH_REF)                        \
  [[nodiscard]] bool Fallible() const final {                            \
    return static_cast<const ::mozilla::FailureLatch&>(FAILURELATCH_REF) \
        .Fallible();                                                     \
  }                                                                      \
  void SetFailure(std::string aReason) final {                           \
    static_cast<::mozilla::FailureLatch&>(FAILURELATCH_REF)              \
        .SetFailure(std::move(aReason));                                 \
  }                                                                      \
  [[nodiscard]] bool Failed() const final {                              \
    return static_cast<const ::mozilla::FailureLatch&>(FAILURELATCH_REF) \
        .Failed();                                                       \
  }                                                                      \
  [[nodiscard]] const char* GetFailure() const final {                   \
    return static_cast<const ::mozilla::FailureLatch&>(FAILURELATCH_REF) \
        .GetFailure();                                                   \
  }                                                                      \
  [[nodiscard]] const FailureLatch& SourceFailureLatch() const final {   \
    return static_cast<const ::mozilla::FailureLatch&>(FAILURELATCH_REF) \
        .SourceFailureLatch();                                           \
  }                                                                      \
  [[nodiscard]] FailureLatch& SourceFailureLatch() final {               \
    return static_cast<::mozilla::FailureLatch&>(FAILURELATCH_REF)       \
        .SourceFailureLatch();                                           \
  }

// Classes deriving from FailureLatch can use this to forward virtual calls to
// another FailureLatch through a pointer, unless it's null in which case act
// like an infallible FailureLatch.
#define FAILURELATCH_IMPL_PROXY_OR_INFALLIBLE(FAILURELATCH_PTR, CLASS_NAME)    \
  [[nodiscard]] bool Fallible() const final {                                  \
    return FAILURELATCH_PTR                                                    \
               ? static_cast<const ::mozilla::FailureLatch*>(FAILURELATCH_PTR) \
                     ->Fallible()                                              \
               : false;                                                        \
  }                                                                            \
  void SetFailure(std::string aReason) final {                                 \
    if (FAILURELATCH_PTR) {                                                    \
      static_cast<::mozilla::FailureLatch*>(FAILURELATCH_PTR)                  \
          ->SetFailure(std::move(aReason));                                    \
    } else {                                                                   \
      MOZ_RELEASE_ASSERT(false, "SetFailure in infallible " #CLASS_NAME);      \
    }                                                                          \
  }                                                                            \
  [[nodiscard]] bool Failed() const final {                                    \
    return FAILURELATCH_PTR                                                    \
               ? static_cast<const ::mozilla::FailureLatch*>(FAILURELATCH_PTR) \
                     ->Failed()                                                \
               : false;                                                        \
  }                                                                            \
  [[nodiscard]] const char* GetFailure() const final {                         \
    return FAILURELATCH_PTR                                                    \
               ? static_cast<const ::mozilla::FailureLatch*>(FAILURELATCH_PTR) \
                     ->GetFailure()                                            \
               : nullptr;                                                      \
  }                                                                            \
  [[nodiscard]] const FailureLatch& SourceFailureLatch() const final {         \
    return FAILURELATCH_PTR                                                    \
               ? static_cast<const ::mozilla::FailureLatch*>(FAILURELATCH_PTR) \
                     ->SourceFailureLatch()                                    \
               : ::mozilla::FailureLatchInfallibleSource::Singleton();         \
  }                                                                            \
  [[nodiscard]] FailureLatch& SourceFailureLatch() final {                     \
    return FAILURELATCH_PTR                                                    \
               ? static_cast<::mozilla::FailureLatch*>(FAILURELATCH_PTR)       \
                     ->SourceFailureLatch()                                    \
               : ::mozilla::FailureLatchInfallibleSource::Singleton();         \
  }

}  // namespace mozilla

#endif /* mozilla_FailureLatch_h */