Description:

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

Please consult the Programmer's Manual of module ALib Exceptions 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 3. Exceptions of the Programmer's Manual of camp ALib Exceptions.

Definition at line 107 of file exception.inl.

Inheritance diagram for alib::exceptions::Exception:

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)
Message &	Back () const
ForwardIterator	begin ()
ConstForwardIterator	begin () const
ForwardIterator	end ()
ConstForwardIterator	end () const
AString	Format () const
AString &	Format (AString &target) const
strings::TAString< complementChar, lang::HeapAllocator > &	Format (strings::TAString< complementChar, lang::HeapAllocator > &target) const
Exception &	operator= (Exception &&) noexcept=default
Exception &	operator= (Exception &) noexcept=default
int	Size () const
const Enum &	Type () const

Protected Type Index:
using	base = TSharedMonoVal<detail::ExceptionEntry*, HeapAllocator, void>
	Shortcut to the parent class.
Protected Type Index: inherited from alib::monomem::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:
Message *	allocMessageLink ()
void	finalizeMessage (Message message, bool hasRecord, ResourcePool pool, const NString &category)
Protected Method Index: inherited from alib::monomem::TSharedMonoVal< detail::ExceptionEntry *, HeapAllocator, void >
	TSharedMonoVal (HeapAllocator &allocator, size_t initialBufferSizeInKB, unsigned bufferGrowthInPercent)
	~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)
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
detail::ExceptionEntry *&	operator* () noexcept
detail::ExceptionEntry **	operator-> () noexcept
TSharedMonoVal &	operator= (const 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)
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::Duration &waitDuration, const CallerInfo &ci) const noexcept
bool	TryAcquireTimed (const Ticks::Duration &waitDuration, const CallerInfo &ci) const noexcept
bool	Unique () const noexcept
unsigned	UseCount () const noexcept

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

Type Definition Details:

◆ base

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

protected

Shortcut to the parent class.

Definition at line 111 of file exception.inl.

◆ ConstForwardIterator

using alib::exceptions::Exception::ConstForwardIterator = IteratorType <const Message>

The constant iterator exposed by this container.

Definition at line 377 of file exception.inl.

◆ ForwardIterator

using alib::exceptions::Exception::ForwardIterator = IteratorType < Message>

The mutable iterator exposed by this container.

Definition at line 380 of file exception.inl.

Constructor(s) / Destructor Details:

◆ Exception() [1/4]

alib::exceptions::Exception::Exception ( Exception && src )

defaultnoexcept

Defaulted move constructor.

Parameters

src	The object to move.

◆ Exception() [2/4]

alib::exceptions::Exception::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 138 of file exception.inl.

◆ Exception() [3/4]

template<typename TIntegral>

alib::exceptions::Exception::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 154 of file exception.inl.

◆ Exception() [4/4]

template<typename TEnum, typename... TArgs>

alib::exceptions::Exception::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 177 of file exception.inl.

Method Details:

◆ Add()

template<typename TEnum, typename... TArgs>

Exception & alib::exceptions::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 a string-type and is taken from field DescriptionOrItsResourceName of the associated enum record. As described in chapter alib_exceptions_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, the type trait ResourcedTraits 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 3.7 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 242 of file exception.inl.

◆ allocMessageLink()

Message * alib::exceptions::Exception::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 63 of file exception.cpp.

◆ Back()

Message & alib::exceptions::Exception::Back ( ) const

Returns the last message in the list of stored messages.

Returns: The most recently added message.

Definition at line 126 of file exception.cpp.

◆ begin() [1/2]

ForwardIterator alib::exceptions::Exception::begin ( )

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 385 of file exception.inl.

◆ begin() [2/2]

ConstForwardIterator alib::exceptions::Exception::begin ( ) const

inline

Returns an iterator pointing to the first message entry.

Returns: A forward iterator to the first message entry.

Definition at line 393 of file exception.inl.

◆ end() [1/2]

ForwardIterator alib::exceptions::Exception::end ( )

inline

Returns an iterator representing the end of the message entries.

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

Definition at line 389 of file exception.inl.

◆ end() [2/2]

ConstForwardIterator alib::exceptions::Exception::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 397 of file exception.inl.

◆ finalizeMessage()

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

protected

Non-inlined portion of the 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 76 of file exception.cpp.

◆ Format() [1/3]

AString alib::exceptions::Exception::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, thestatic threads::RecursiveLock DEFAULT_LOCK has to be acquired before invoking this method.

Availability: This method is available only if the module ALib Format is included in the ALib Build.

Returns: The formatted description of the Exception.

Definition at line 293 of file exception.inl.

◆ Format() [2/3]

AString & alib::exceptions::Exception::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, thestatic threads::RecursiveLock DEFAULT_LOCK has to be acquired before invoking this method.

Availability: This method is available only if the module ALib Format is included in the ALib Build.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 157 of file exception.cpp.

◆ Format() [3/3]

strings::TAString< complementChar, lang::HeapAllocator > & alib::exceptions::Exception::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, thestatic threads::RecursiveLock DEFAULT_LOCK has to be acquired before invoking this method.

Availability: This method is available only if the module ALib Format is included in the ALib Build.

Parameters

target The target string to format the entry description to.

Returns: Returns given AString target for convenience.

Definition at line 279 of file exception.inl.

◆ operator=() [1/2]

Exception & alib::exceptions::Exception::operator= ( Exception && )

defaultnoexcept

Defaulted move assignment operator.

Returns: Nothing (deleted).

◆ operator=() [2/2]

Exception & alib::exceptions::Exception::operator= ( Exception & )

defaultnoexcept

Defaulted copy assignment operator.

Returns: Nothing (deleted).

◆ Size()

int alib::exceptions::Exception::Size ( ) const

Returns the number of message entries.

Returns: The number of messages added to this exception.

Definition at line 134 of file exception.cpp.

◆ Type()

const Enum & alib::exceptions::Exception::Type ( ) const

Returns field Enum 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 145 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()