Description:

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

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 108 of file exception.inl.

Inheritance diagram for alib::exceptions::Exception:

[legend]

Collaboration diagram for alib::exceptions::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_DLL Message &	Back () const

ForwardIterator	begin ()

ConstForwardIterator	begin () const

ForwardIterator	end ()

ConstForwardIterator	end () const

AString	Format () const

ALIB_DLL AString &	Format (AString &target) const

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

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

Exception &	operator= (Exception &) noexcept=default

ALIB_DLL int	Size () const

ALIB_DLL 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:
ALIB_DLL Message *	allocMessageLink ()

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

Protected Method Index: inherited from alib::monomem::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 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 112 of file exception.inl.

◆ ConstForwardIterator

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

The constant iterator exposed by this container.

Definition at line 417 of file exception.inl.

◆ ForwardIterator

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

The mutable iterator exposed by this container.

Definition at line 420 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.

Here is the call graph for this function:

◆ 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 139 of file exception.inl.

Here is the call graph for this function:

◆ 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 157 of file exception.inl.

Here is the call graph for this function:

◆ 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 183 of file exception.inl.

Here is the call graph for this function:

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.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 260 of file exception.inl.

Here is the call graph for this function:

◆ 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 64 of file exception.cpp.

Here is the call graph for this function:

◆ 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 135 of file exception.cpp.

Here is the call graph for this function:

◆ 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 425 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 439 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 432 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 446 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 78 of file exception.cpp.

Here is the call graph for this function:

◆ 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, theFormatter::DefaultLock 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 312 of file exception.inl.

Here is the call graph for this function:

◆ 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, theFormatter::DefaultLock 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 170 of file exception.cpp.

Here is the call graph for this function:

◆ Format() [3/3]

ALIB_DLL 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, theFormatter::DefaultLock 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 298 of file exception.inl.

Here is the call graph for this function:

◆ operator=() [1/2]

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

defaultnoexcept

Defaulted move assignment operator.

Returns: Nothing (deleted).

Here is the call graph for this function:

◆ operator=() [2/2]

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

defaultnoexcept

Defaulted copy assignment operator.

Returns: Nothing (deleted).

Here is the call graph for this function:

◆ 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 144 of file exception.cpp.

Here is the call graph for this function:

◆ Type()

const Enum & alib::exceptions::Exception::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 157 of file exception.cpp.

Here is the call graph for this function:

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()