chsvexception.h File Reference

The file contains definitions of various exceptions thrown by the mechanisms of the chsvcode library and can be used by clients. More...

#include "chsvstring.h"
#include "chsvthrd.h"

Classes
class	Exception
	Defines a class of objects specifying various exceptions with extended support for description formatting. . More...
class	ExceptionWithGenericCode< code_t, class >
	A class template specifying a generic exception which has a corresponding integral error code. More...
struct	ExceptionWithGenericCode< code_t, class >::noprintf
	An empty type defining an overload of SetCodeAndDescription method that discards Printf formatting during construction of an exception description. More...
struct	ChsvCodeExceptionTempl< errc >
	A template defining classes depending on the specified chsvlib error code. . More...
struct	ChsvCodeExceptionTempl< errc >::noformat
	A type used to overload protected formatting methods in order to turn off the Printf formatting. More...
struct	OutOfMemoryException
	Insufficient memory exception. More...
struct	InvalidParameterException
	Invalid parameter exception. More...
struct	InsufficientBufferException
	Insufficient buffer exception. More...
struct	OutOfRangeException
	Out of range exception. More...
struct	InitializationFailureException
	Initialization failure exception. More...
struct	NotInitializedException
	Reading an uninitialized resource exception. More...
struct	AlreadyInitializedException
	Initializing an already initialized resource exception. More...
struct	InvalidVersionException
	Improper version exception. More...
struct	NotFoundException
	Item not found exception. More...
struct	AlreadyExistsException
	Resource already exists exception. More...
struct	InvalidResourceException
	Invalid resource exception. More...
struct	AccessDeniedException
	Access denied exception. More...
struct	StorageFullnessException
	Storage full exception. More...
struct	InvalidCharSequenceException
	Invalid multibyte character sequence exception. More...
struct	OperationCancelledException
	Operation is cancelled exception. More...
struct	NameTooLongException
	Name is too long exception. More...
struct	PossibleDeadlockException
	Possible deadlock exception. More...
struct	TimeoutException
	Timeout exception. More...
struct	OwnerDeadException
	A thread owning a resource is dead. More...
struct	UnsupportedCallException
	Unsupported (unimplemented) call exception. More...
struct	ArithmeticOverflowException
	Arithmetic overflow exception. More...
struct	StackOverflowException
	Stack overflow exception. More...
struct	UnknownException
	Unknown exception corresponding to an unknown error code . More...
class	PlatformException< pltfrm_code_t >
	A class template designed specifically for using with externally defined error codes. More...
struct	code_based_exception< exception_code >
	Defines a nested type alias to a chsvlib exception depending on the chsvlib error code. More...
class	nested_exception
	Together with throw_with_nested and rethrow_if_nested implements a behaviour of the standard C++11 nested exceptions mechanism as defined by the std::nested_exception class and by the std::throw_with_nested and std::rethrow_if_nested functions respectively. . More...

Namespaces
	Chusov
	Basic chsvlib namespace.
	Chusov::Exceptions
	A namespace for chsvlib generic exception classes and for special helper function.

Macros
#define	EXCEPTIONS_BEGIN   namespace Exceptions {
	Defines the beginning of the Chusov::Exceptions namespace without defining the encapsulating namespace. More...
#define	EXCEPTIONS_END   }
	Defines the end of the Chusov::Exceptions namespace. More...
#define	chsv_monitor_exceptions   Chusov::Exceptions::Implementation::ExceptionStack_t chsv_impl_trace_db(__FILE__, STRINGIFY(__LINE__), __func__, __WFILE__, STRINGIFYW(__LINE__), __wfunc__)
	Turns on exception tracing during stack unwinding within a function. More...
#define	chsv_list_of_exceptions   Chusov::Exceptions::Implementation::ExceptionStack_t::get_list()
	Returns a list of registered exceptions thrown within a current thread with the front elements being the top-level functions and the back elements being the deepest stack calls. More...
#define	chsv_monitor_exceptions_debug   Chusov::Exceptions::Implementation::ExceptionStack_t chsv_impl_trace_db(__FILE__, STRINGIFY(__LINE__), __func__, __WFILE__, STRINGIFYW(__LINE__), __wfunc__)
	If the build configuration is set to debug, the definition turns on exception tracing during stack unwinding within a function. More...

Typedefs
typedef ExceptionWithGenericCode< chsverror_t >	ChsvCodeException
	An alias for the type of exception objects to be bound with chsvlib error codes.
template<chsverror_t exception_code>
using	code_based_exception_t = typename code_based_exception< exception_code >::type
	A type alias for an exception class which corresponds to the given error code. More...

Functions
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByChsvCode (chsverror_t nCode, const char *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class, bound with the specified chsvlib error code, and throws it as an exception. . More...
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByChsvCode (chsverror_t nCode, const wchar_t *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class, bound with the specified chsvlib error code, and throws it as an exception. . More...
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByChsvCode (chsverror_t nCode)
	Creates an instance of the ChsvCodeExceptionTempl class, bound with the specified chsvlib error code, and throws it as an exception. More...
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByChsvCode ()
	Constructs and throws an exception object by a chsvlib error code returned by the GetLastChsvError function. More...
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByPosixCode (errno_t nCode, const char *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified POSIX error code to the corresponding chsvlib error code. . More...
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByPosixCode (errno_t nCode, const wchar_t *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified POSIX error code to the corresponding chsvlib error code. . More...
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByPosixCode (errno_t nCode)
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByPosixCode ()
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByWindowsCode (unsigned long nCode, const char *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified Windows error code to the corresponding chsvlib error code. More...
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByWindowsCode (unsigned long nCode, const wchar_t *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified Windows error code to the corresponding chsvlib error code. More...
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByWindowsCode (unsigned long nCode)
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByWindowsCode ()
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByPlatformCode (chsv_syserror_t nCode, const char *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified operating system error code to the corresponding chsvlib error code. More...
template<bool fProcessSuccessCodeAsUnknownError = true, class ... DescriptionFormatParams>
void	ChsvExceptionByPlatformCode (chsv_syserror_t nCode, const wchar_t *restrict pszDescription, DescriptionFormatParams ... format_params)
	Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified operating system error code to the corresponding chsvlib error code. More...
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByPlatformCode (chsv_syserror_t nCode)
template<bool fProcessSuccessCodeAsUnknownError = true>
void	ChsvExceptionByPlatformCode ()
void	RethrowStdExceptionAsChsvException (std::exception_ptr eptr)
	Tries to rethrow an exception pointed to by the parameter as a predefined exception. If there is no predefined match to the input exception, the function throws the exception as it is. More...
template<class E >
void	throw_with_nested (E &&e)
	Implements a behaviour of the standard std::throw_with_nested function storing an exception having been caught by a caller and retrieved by a call to the std::current_exception function in the constructed nested_exception object and throwing an exception specified by the only parameter. . More...
template<class E >
void	rethrow_if_nested (E &&e)
	Implements a behaviour of the standard std::rethrow_if_nested function checking if the most derived dynamic type of the specified exception inherits the nested_exception class and, if that is true, throws an exception stored by the nested_exception object calling nested_exception::rethrow_nested(). If an exception object given by the parameter is not dynamically connected with the nested_exception class through inheritance, the function does nothing. . More...

Detailed Description

The file contains definitions of various exceptions thrown by the mechanisms of the chsvcode library and can be used by clients.

Needs for chsvmem.h:

1. We need printf formatting in C++-specific exceptions because of i8n when formatting strings are located in dedicated files.

2. <CODE> and <DESCRIPTION> (as well as <PLATFORM_CODE> and <PLATFORM_DESCRIPTION>) tags may be a more convenient way to include corresponding substrings into the description than using calling constructs like

   ExceptionWithGenericCode(nCode, std::wstring(L"Exception caught: ").append(std::to_string(nCode)).append(" (").append(GetDescription(nCode))
       .append(") in " __WFILE__).append(":").append(std::to_string(__LINE__)));

   compared to

   ExceptionWithGenericCode(nCode, GetDescription, L"Exception caught: <CODE> (<DESCRIPTION>) in %s:%u", __WFILE__, __LINE__);

   The first call, that involves an std::wstring object, has the following drawbacks:

   • Readability.
   • The std::basic_string object can generate std::bad_alloc exception, which cannot be handled by the ExceptionWithGenericCode object, as the std::bad_alloc exception occurs outside the constructor scope.
   • Errors on the client's implementation of GetDescription are not handled at all. And if in case of failure the function returns a NULL pointer to a C string, the behavior of the constructed string object is undefined. If the function throws an exception, it wouldn't have been handled internally by the exception.

   The second call has the following drawbacks:

   • The GetDescription function has to have a fixed predefined prototype or be implemented as a function object. This requires additional code on the client's side.

   • Composite C++ objects cannot be included straightforwardly into the definition of the description format and this inclusion would require either additional formatting of the format string with the first method, e.g.:

     ExceptionWithGenericCode(nCode, GetDescription, std::wstring(L"Error <CODE>: <DESCRIPTION>. ").append(MyDetailedInformationObject).c_str());

     or by providing functions converting the objects into a string (which as an automatically managed object), like:

     ExceptionWithGenericCode(nCode, GetDescription, L"Error <CODE>: <DESCRIPTION>. %s",
         std::unique_ptr<wchar_t>(MyDetailedInformationObject.ToString()).get());

     Still, it may be somewhat better than

     ExceptionWithGenericCode(nCode, std::wstring(L"Error ").append(std::to_string(nCode)).append(": ").append(GetDescription(nCode)).append(". ").append(MyDetailedInformationObject));

3. If we discard functionality of the chsvmem.h, than it may not be possible to guarantee that a thrown exception object will not itself generate exceptions, such as std::bad_alloc, causing the whole program termination. If we want to guarantee a good state of the generated exceptions, even in rarest exception cases, such as construction default std::basic_string objects, wee need to avoid a usage of complex C++ classes, such as std::basic_string within exception classes.

Allocators (operator new vs. Chusov::String::AllocateString).

• Both of these allocation methods can operate without throwing exceptions, see void* std::operator new(std::size_t count, std::nothrow_t).
• The new operator can also throw std::bad_alloc exception, but available overloads of functions in chsvmem.h cannot.
• Because the formatting functions are used, chsvmem.h allocations will be used anyway.

Decisions:

• Provide formatting constructors of both types: the one receiving Chusov::String::PrintfW parameters together with tags, and the one receiving std::basic_string description.
• Do not make the client using Chusov::Memory functions, let him calling standard C++ primitives like std::basic_string and operator new instead, this especially relates to callbacks.
• Inherit all predefined exceptions from standard C++ exception through multiple inheritance, and maybe from std::system_error of Chusov::chsvlib_general_category_t.
• Inherit PlatformException from std::system_error of std::generic_category for errno errors and of std::system_category for Windows errors.