Errata.h File Reference

#include <vector>
#include <string_view>
#include <functional>
#include <atomic>
#include <optional>
#include "swoc/swoc_version.h"
#include "swoc/MemSpan.h"
#include "swoc/MemArena.h"
#include "swoc/bwf_base.h"
#include "swoc/bwf_std.h"
#include "swoc/IntrusiveDList.h"

Include dependency graph for Errata.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	swoc::Errata
struct	swoc::Errata::Severity
class	swoc::Errata::Annotation
struct	swoc::Errata::Data
	Implementation class. More...
struct	swoc::Errata::AutoText
	Used to indicate automatically generated annotation text.
class	swoc::Errata::Sink
struct	swoc::Errata::SinkWrapper
	Convenience wrapper class to enable using functions directly for sinks. More...
class	swoc::Rv< R >

Namespaces
namespace	swoc
	For template deduction guides.
namespace	std
	STL namespace.

Functions
std::ostream &	swoc::operator<< (std::ostream &os, Errata const &err)
template<typename R>
Rv< typename std::remove_reference< R >::type >	swoc::MakeRv (R &&r, Errata &&erratum)
BufferWriter &	swoc::bwformat (BufferWriter &bw, bwf::Spec const &spec, Errata::Severity level)
BufferWriter &	swoc::bwformat (BufferWriter &w, bwf::Spec const &spec, Errata::Annotation const &)
BufferWriter &	swoc::bwformat (BufferWriter &bw, bwf::Spec const &spec, Errata const &errata)

Detailed Description

Stacking error message handling.

The problem addressed by this library is the ability to pass back detailed error messages from failures. It is hard to get good diagnostics because the specific failures and general context are located in very different stack frames. This library allows local functions to pass back local messages which can be easily augmented as the error travels up the stack frame.

This aims to improve over exceptions by being lower cost and not requiring callers to handle the messages. On the other hand, the messages could be used just as easily with exceptions.

Each message on a stack contains text and a numeric identifier. The identifier value zero is reserved for messages that are not errors so that information can be passed back even in the success case.

The implementation takes the position that success must be fast and failure is expensive. Therefore Errata is optimized for the success path, imposing very little overhead in that case. On the other hand, if an error occurs and is handled, that is generally so expensive that optimizations are pointless (although, of course, code should not be gratuitiously expensive).

The library provides the Rv ("return value") template to make returning values and status easier. This template allows a function to return a value and status pair with minimal changes. The pair acts like the value type in most situations, while providing access to the status.

Each instance of an erratum is a wrapper class that emulates value semantics (copy on write). This means passing even large message stacks is inexpensive, involving only a pointer copy and reference counter increment and decrement. A success value is represented by an internal NULL so it is even cheaper to copy.

To further ease use, the library has the ability to define sinks. A sink is a function that acts on an erratum when it becomes unreferenced. The intended use is to send the messages to an output log. This makes reporting errors to a log from even deeply nested functions easy while preserving the ability of the top level logic to control such logging.

Definition in file Errata.h.