217 lines
10 KiB
C++
217 lines
10 KiB
C++
/* -*- 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 */
|