Description:

The (one and only) "throwable" used with ALib C++ Library.

Please consult the Programmer's Manual of module ALib BaseCamp for detailed information about this class and its use.

In short, this class implements the following "exception paradigm":

There is only one exception type.
That type stores a forward list of messages.
With creation, a first message is added to the list of messages.
While unwinding the stack, new messages may be added to the list.
A new message may either add information to the previous entry or may change the meaning of the exception.
Messages contain IDs of arbitrary scoped enumeration types. This allows structured processing of Exceptions.

This type uses a smart memory model leveraging class TSharedMonoVal which places all internal data in a first buffer of a TMonoAllocator, even the Exception object itself! With that, exceptions usually perform only one single dynamic allocation, even if various messages with various data objects (boxes) are attached. Only when many messages are added, a next allocation might occur. The allocation size of the monotonic buffers is set to be one kilobyte.

Although the footprint (sizeof) of the class is just the size of a pointer (One into the first memory buffer of the monotonic allocator), objects of this type should be caught as references. Once caught, copies may be stored for later logging or similar.

See also: Chapter 2.2. Exceptions of the Programmer's Manual of camp ALib BaseCamp.

Definition at line 116 of file exception.hpp.

#include <exception.hpp>

Inheritance diagram for Exception:

[legend]

Collaboration diagram for Exception:

[legend]

Inner Type Index:
class	IteratorType

Public Type Index:
using	ConstForwardIterator = IteratorType <const Message>
	The constant iterator exposed by this container.

using	ForwardIterator = IteratorType < Message>
	The mutable iterator exposed by this container.

Public Method Index:
	Exception () noexcept=default
	Defaulted default constructor.

template<typename TEnum , typename... TArgs>
	Exception (const lang::CallerInfo &ci, TEnum type, TArgs &&... args)

	Exception (Exception &&src) noexcept=default

	Exception (Exception &) noexcept=default
	Deleted copy constructor. Exceptions must be caught only as references.

	Exception (std::nullptr_t) noexcept

template<typename TIntegral >
	Exception (TIntegral initialBufferSizeInKB, int bufferGrowthInPercent=100)

	~Exception () noexcept=default
	Defaulted destructor.

template<typename TEnum , typename... TArgs>
Exception &	Add (const lang::CallerInfo &ci, TEnum type, TArgs &&... args)

ALIB_API Message &	Back () const

ForwardIterator	begin ()

ConstForwardIterator	begin () const

ForwardIterator	end ()

ConstForwardIterator	end () const

AString	Format () const

ALIB_API AString &	Format (AString &target) const

ALIB_API strings::TAString< complementChar, lang::HeapAllocator > &	Format (strings::TAString< complementChar, lang::HeapAllocator > &target) const

Exception &	operator= (Exception &&) noexcept=default

Exception &	operator= (Exception &) noexcept=default

ALIB_API int	Size () const

ALIB_API const Enum &	Type () const

Protected Type Index:
using	base = TSharedMonoVal<detail::ExceptionEntry*, HeapAllocator, void>
	Shortcut to the parent class.

Protected Type Index: inherited from TSharedMonoVal< detail::ExceptionEntry *, HeapAllocator, void >
using	FieldMembers

using	AllocatorType
	Exposes the monotonic allocator used. Equals to `TMonoAllocator<TAllocator>`.

using	LockType
	Exposes the lock type specified with template parameter TLock.

using	StoredType
	Exposes the stored type specified with template parameter T.

Protected Method Index:
ALIB_API Message *	allocMessageLink ()

ALIB_API void	finalizeMessage (Message message, bool hasRecord, ResourcePool pool, const NString &category)

Protected Method Index: inherited from TSharedMonoVal< detail::ExceptionEntry *, HeapAllocator, void >
	TSharedMonoVal () noexcept
	Default Constructor. Leaves this object nulled.

	TSharedMonoVal (const TSharedMonoVal &other) noexcept

	TSharedMonoVal (HeapAllocator &allocator, size_t initialBufferSizeInKB, unsigned int bufferGrowthInPercent)

	TSharedMonoVal (size_t initialBufferSizeInKB, unsigned int bufferGrowthInPercent)

	TSharedMonoVal (std::nullptr_t) noexcept

	TSharedMonoVal (TSharedMonoVal &&other) noexcept

	~TSharedMonoVal ()

void	Acquire (const CallerInfo &ci) const noexcept

void	AcquireRecursive (const CallerInfo &ci) const noexcept

void	AcquireShared (const CallerInfo &ci) const noexcept

void	ConstructT (TArgs &&... args)

const detail::ExceptionEntry **	Get () const noexcept

detail::ExceptionEntry **	Get () noexcept

AllocatorType &	GetAllocator () noexcept

void &	GetLock () const noexcept

bool	IsNulled () const noexcept

	operator bool () const noexcept

bool	operator!= (std::nullptr_t) const noexcept

const detail::ExceptionEntry *&	operator* () const noexcept

detail::ExceptionEntry *&	operator* () noexcept

const detail::ExceptionEntry **	operator-> () const noexcept

detail::ExceptionEntry **	operator-> () noexcept

TSharedMonoVal &	operator= (const TSharedMonoVal &other) noexcept

void	operator= (std::nullptr_t)
	Assignment of `nullptr`. Same as SetNulled.

TSharedMonoVal &	operator= (TSharedMonoVal &&other) noexcept

bool	operator== (std::nullptr_t) const noexcept

void	Release (const CallerInfo &ci) const noexcept

void	ReleaseRecursive (const CallerInfo &ci) const noexcept

void	ReleaseShared (const CallerInfo &ci) const noexcept

void	Reset (TArgs &&... args)

const detail::ExceptionEntry *&	Self () const noexcept

detail::ExceptionEntry *&	Self () noexcept

void	SetNulled () noexcept

bool	TryAcquire (const CallerInfo &ci) const noexcept

bool	TryAcquireShared (const CallerInfo &ci) const noexcept

bool	TryAcquireSharedTimed (const Ticks &pointInTime, const CallerInfo &ci) const noexcept

bool	TryAcquireSharedTimed (const Ticks::Duration &waitDuration, const CallerInfo &ci) const noexcept

bool	TryAcquireSharedTimed (const Ticks::Duration::TDuration &waitDuration, const CallerInfo &ci) const noexcept

bool	TryAcquireSharedTimed (const Ticks::TTimePoint &pointInTime, const CallerInfo &ci) const noexcept

bool	TryAcquireTimed (const Ticks &pointInTime, const CallerInfo &ci) const noexcept

bool	TryAcquireTimed (const Ticks::Duration &waitDuration, const CallerInfo &ci) const noexcept

bool	TryAcquireTimed (const Ticks::Duration::TDuration &waitDuration, const CallerInfo &ci) const noexcept

bool	TryAcquireTimed (const Ticks::TTimePoint &pointInTime, const CallerInfo &ci) const noexcept

bool	Unique () const noexcept

unsigned int	UseCount () const noexcept

Additional Inherited Members
Protected Static Method Index: inherited from TSharedMonoVal< detail::ExceptionEntry *, HeapAllocator, void >
static constexpr size_t	SizeOfAllocation ()

Protected Field Index: inherited from TSharedMonoVal< detail::ExceptionEntry *, HeapAllocator, void >
FieldMembers *	members

Type Definition Details:

◆ base

using base = TSharedMonoVal<detail::ExceptionEntry*, HeapAllocator, void>

protected

Shortcut to the parent class.

Definition at line 120 of file exception.hpp.

◆ ConstForwardIterator

using ConstForwardIterator = IteratorType <const Message>

The constant iterator exposed by this container.

Definition at line 426 of file exception.hpp.

◆ ForwardIterator

using ForwardIterator = IteratorType < Message>

The mutable iterator exposed by this container.

Definition at line 429 of file exception.hpp.

Constructor(s) / Destructor Details:

◆ Exception() [1/4]

Exception ( Exception && src )

defaultnoexcept

Defaulted move constructor.

Parameters

src	The object to move.

◆ Exception() [2/4]

Exception ( std::nullptr_t )

inlinenoexcept

Constructs an empty instance from std::nullptr. This constructor is necessary to allow assignment of nullptr to values of this type, which clears the automatic pointer.

Definition at line 147 of file exception.hpp.

◆ Exception() [3/4]

template<typename TIntegral >

Exception	(	TIntegral	initialBufferSizeInKB,
		int	bufferGrowthInPercent = 100 )

inline

Constructor that allows providing the size of the allocated memory buffer in bytes. With other constructors, this size is fixed to 1kB (1024 bytes). A higher size may avoid a second allocation (which is not problematic in usual cases).

Note: The use of this constructor is advisable only in seldom cases. The same notes as given with the documentation of the default constructor apply.

Parameters

initialBufferSizeInKB	The initial allocation size of the internal MonoAllocator in kilobytes (1024 bytes).
bufferGrowthInPercent	Optional growth factor in percent, applied to the buffer size with each next buffer allocation. With this type, the parameter defaults to `100`, which does not increase subsequent buffer allocations.

Definition at line 165 of file exception.hpp.

◆ Exception() [4/4]

template<typename TEnum , typename... TArgs>

Exception	(	const lang::CallerInfo &	ci,
		TEnum	type,
		TArgs &&...	args )

inline

Constructs an exception and invokes Add to create the initial message entry.

In case that the enumeration type of given parameter type is equipped with ALib Enum Records according to record type ERException, the first argument added to the message entry is collected from the corresponding enum record. For more information consult the corresponding section of the Programmer's Manual.

Template Parameters

TEnum	Template type of the enumeration element.
TArgs	The variadic template argument types.

Parameters

ci	Source location of entry creation.
type	An enum element denoting the message type.
args	The message arguments.

Definition at line 191 of file exception.hpp.

Here is the call graph for this function:

Method Details:

◆ Add()

template<typename TEnum , typename... TArgs>

Exception & Add	(	const lang::CallerInfo &	ci,
		TEnum	type,
		TArgs &&...	args )

inline

Adds a new message to this exception. The parameters of this method are exactly those that are expected by the constructor of class Message.

The message object itself is created in the inherited monotonic allocator. After the insertion, method CloneAll is invoked, which creates "safe" copies of the arguments to guarantee their survival during this exception's lifespan.

If the enumeration type TEnum (which is deduced from parameter type) is equipped with ALib Enum Records of type ERException, an additional message argument is prepended to the message This argument is of string-type and is taken from field DescriptionOrItsResourceName of the associated enum record. As described in chapter alib_basecamp_message_exceptions_args of the Programmer's Manual, it is proposed that this argument of string-type, is a formatter-string that is used to format the arguments of an exception into a human-readable message.

If furthermore, TMP struct T_Resourced is specialized for enumeration type TEnum, then the value of DescriptionOrItsResourceName is not directly prepended, but interpreted as a resource name. In this case the resourced description is prepended instead.

For more information consult chapter 2.2.6 Resourced Exceptions of the Programmer's Manual.

Template Parameters

TEnum	The enumeration type used to define the message type.
TArgs	The variadic template argument types.

Parameters

ci	Source location of entry creation.
type	An enum element denoting the message type.
args	The message arguments.

Returns: Return *this to allow concatenated operations or use with throw statement.

Definition at line 268 of file exception.hpp.

Here is the call graph for this function:

◆ allocMessageLink()

Message * allocMessageLink ( )

protected

Searches the last linked message and attaches a new, monotonically allocated list node.

Returns: A pointer to the message in the allocated link node.

Definition at line 35 of file exception.cpp.

Here is the call graph for this function:

◆ Back()

Message & Back ( ) const

Returns the last message in the list of stored messages.

Returns: The most recently added message.

Definition at line 108 of file exception.cpp.

◆ begin() [1/2]

ForwardIterator begin ( )

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 434 of file exception.hpp.

◆ begin() [2/2]

ConstForwardIterator begin ( ) const

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 448 of file exception.hpp.

◆ end() [1/2]

ForwardIterator end ( )

inline

Returns an iterator representing the end of the message entries.

Returns: The end of this exception's message entries.

Definition at line 441 of file exception.hpp.

◆ end() [2/2]

ConstForwardIterator end ( ) const

inline

Returns an iterator representing the end of the message entries.

Returns: The end of this exception's message entries.

Definition at line 455 of file exception.hpp.

◆ finalizeMessage()

void finalizeMessage	(	Message *	message,
		bool	hasRecord,
		ResourcePool *	pool,
		const NString &	category )

protected

Non-inlined portion of method Add. Clones arguments and prepends description argument, in case the enum element of the message has an enum record attached. If furthermore, the enum element's record was resourced, then the record's description value is interpreted as a resource string's name, which is prepended instead.

Parameters

message	The message to finalize.
hasRecord	Indicates if a record is assigned.
pool	If records are resourced, this is the resource pool to use.
category	If records are resourced, this is the category to use.

Definition at line 49 of file exception.cpp.

Here is the call graph for this function:

◆ Format() [1/3]

AString Format ( ) const

inline

Inline shortcut to Format(AString&) that creates, uses and returns an AString value for the exception's description.

Note: In multithreaded applications, theFormatter::DefaultLock has to be acquired before invoking this method.

Returns: The formatted description of the Exception.

Definition at line 320 of file exception.hpp.

Here is the call graph for this function:

◆ Format() [2/3]

AString & Format ( AString & target ) const

Uses class Paragraphs to write all entries of this exception into the given narrow target string. Entries are expected to have a format string set as their description meta-information that corresponds (in respect to the placeholders within the string) to the arguments found in the entry.

Note: In multithreaded applications, theFormatter::DefaultLock has to be acquired before invoking this method.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 143 of file exception.cpp.

Here is the call graph for this function:

◆ Format() [3/3]

ALIB_API strings::TAString< complementChar, lang::HeapAllocator > & Format ( strings::TAString< complementChar, lang::HeapAllocator > & target ) const

inline

Same as Format(AString&), but writing to a string of complement character width.

Note: In multithreaded applications, theFormatter::DefaultLock has to be acquired before invoking this method.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 306 of file exception.hpp.

Here is the call graph for this function:

◆ operator=() [1/2]

Exception & operator= ( Exception && )

defaultnoexcept

Defaulted move assignment operator.

Returns: Nothing (deleted).

◆ operator=() [2/2]

Exception & operator= ( Exception & )

defaultnoexcept

Defaulted copy assignment operator.

Returns: Nothing (deleted).

◆ Size()

int Size ( ) const

Returns the number of message entries.

Returns: The number of messages added to this exception.

Definition at line 117 of file exception.cpp.

◆ Type()

const Enum & Type ( ) const

Returns field Message::Type of the last message in the list of messages that has a positive underlying enum element value.

The rationale here is explained in the Programmer's Manual. In short, positive and negative enum element values are used to separated "informational entries" (with a negative value) from message entries that change the type of the exception (positive value). Usually, only the latter ones are processed by exception handlers.

Returns: The most high level exception code.

Definition at line 130 of file exception.cpp.

The documentation for this class was generated from the following files:

Description:

Inner Type Index:

Public Type Index:

Public Method Index:

Protected Type Index:

Protected Method Index:

Additional Inherited Members

Type Definition Details:

◆ base

◆ ConstForwardIterator

◆ ForwardIterator

Constructor(s) / Destructor Details:

◆ Exception() [1/4]

◆ Exception() [2/4]

◆ Exception() [3/4]

◆ Exception() [4/4]

Method Details:

◆ Add()

◆ allocMessageLink()

◆ Back()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ finalizeMessage()

◆ Format() [1/3]

◆ Format() [2/3]

◆ Format() [3/3]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Size()

◆ Type()