alib::assert Namespace Reference

Description:

This namespace exposes entities of module ALib Assert.

Type Index:
struct	TLD

Type Definition Index:
using	AnyConversionFunc = void(*)(const std::any&, std::string&)

Function Index:
template<typename... TArgs>
void	CheckArgs (const CallerInfo &ci, TArgs &&... args)
ALIB_DLL void	CheckArgsImpl (const CallerInfo &ci, const std::span< std::any > &args)
TLD &	GetHaltFlagAndCounters ()
template<typename... TArgs>
void	Raise (const lang::CallerInfo &ci, int type, std::string_view domain, TArgs &&... args)
void	raise (const CallerInfo &ci, int type, std::string_view domain, const std::span< std::any > &args)
ALIB_DLL void	RegisterPrintable (std::type_index typeIndex, AnyConversionFunc func)
void	SingleThreaded ()

Variable Index:
std::string_view	FORMAT = "{file}:{line} {type}:\n{message}"
void(*	PLUGIN )(const CallerInfo &ci, int type, std::string_view domain, std::string_view msg) = nullptr
std::ostream *	STREAM_ERRORS = &std::cerr
std::ostream *	STREAM_MESSAGES = &std::cout
std::ostream *	STREAM_WARNINGS = &std::cout

Type Definition Details:

AnyConversionFunc

using alib::assert::AnyConversionFunc = void(*)(const std::any&, std::string&)

A type alias for a function pointer that defines a high-level mechanism for appending a std::any value to a std::string. Custom functions may be registered using function RegisterPrintable. This then allows to use custom objects as "printables" in assertions.

Definition at line 91 of file assert.inl.

Function Details:

CheckArgs()

template<typename... TArgs>

void alib::assert::CheckArgs	(	const CallerInfo &	ci,
		TArgs &&...	args )

This method is called by the assertion macros with any ALib invocation - hence regardless whether the assertion or warning was raised or not - in the case that the compiler-symbol ALIB_DEBUG_ASSERTION_PRINTABLES is given.
This is used to ensure that all arguments passed are of a known type. Otherwise, assertions that happen seldom would raise an inner assertion due to unsupported arguments.

Template Parameters

TArgs

Types of the variadic arguments args.

Parameters

ci	Source location of the assertion raised.
args	Variadic argument list comprising the assertion message, which are to be tested.

Definition at line 46 of file assert.inl.

Here is the call graph for this function:

CheckArgsImpl()

ALIB_DLL void alib::assert::CheckArgsImpl	(	const CallerInfo &	ci,
		const std::span< std::any > &	args )

This is the implementation of the templated sibling method, which fetches the variadic templated printables of an ALib assertion.

Available only if the compiler-symbol ALIB_DEBUG_ASSERTION_PRINTABLES is given.

Parameters

ci	Source location of the assertion raised.
args	The arguments of the assertion message.

GetHaltFlagAndCounters()

ALIB_DLL TLD & alib::assert::GetHaltFlagAndCounters

(

)

Returns the thread_local instance of flags and counters used by function alib::assert::Raise.

Returns

The singleton, thread-local instance of the flags.

Definition at line 573 of file assert.cpp.

Raise()

template<typename... TArgs>

void alib::assert::Raise	(	const lang::CallerInfo &	ci,
		int	type,
		std::string_view	domain,
		TArgs &&...	args )

This method is used by ALib modules to raise assertions, warnings and display debug-messages. (The latter usually depends on special the compiler-symbols like ALIB_DEBUG_MEMORY.)

It may be used by custom code for custom assertions as well.

This method first checks if the function pointer assert::PLUGIN is set and if yes, passes the parameters to this method and exits.

Otherwise, the method just writes to the standard error and output streams (which is changeable) and then, if type equals 0, invokes assert(0).

See also

The following entities are related to ALib assertions:

• assert::raise (called by this method after converting the variadic arguments to an array of std::any objects.
• Type definition assert::AnyConversionFunc to register custom printable types.
• Function RegisterPrintable to register a conversion function.
• Namespace variable assert::FORMAT that defines the output format.
• Namespace variables assert::STREAM_ERRORS, assert::STREAM_WARNINGS, and assert::STREAM_MESSAGES that allow to redirect assertion messages.
• Thread-local struct HALT_FLAGS_AND_COUNTERS, which allows tweaking the assertion behavior and implements usage counters. (Mostly done to support unit-tests.)
• Assertion and message macros:
  • ALIB_ERROR,
  • ALIB_WARNING,
  • ALIB_MESSAGE,
  • ALIB_ASSERT,
  • ALIB_ASSERT_ERROR,
  • ALIB_ASSERT_WARNING, and
  • ALIB_ASSERT_MESSAGE.
  • ALIB_ERROR,
  • ALIB_ERROR,

Template Parameters

TArgs

The types of the variadic function arguments args.

Parameters

ci	Caller information.
type	The type of the message: 0 for error, 1 for warning, higher values for messages.
domain	The domain of the assertion, warning, or message. (Usually the name of the ALib Module.) Has to be capital alphanumeric letters.
args	Variadic argument list comprising the message.

Definition at line 181 of file assert.inl.

Here is the call graph for this function:

raise()

ALIB_DLL void alib::assert::raise	(	const lang::CallerInfo &	ci,
		int	type,
		std::string_view	domain,
		const std::span< std::any > &	args )

The implementation of sibling method Raise that takes a variadic number of arguments.

Parameters

ci	Caller information.
type	The type of the message: 0 for error, 1 for warning, higher values for messages.
domain	The domain of the assertion, warning, or message. (Usually the name of the ALib Module.) Has to be capital alphanumeric letters.
args	The array of arguments.

Definition at line 575 of file assert.cpp.

RegisterPrintable()

ALIB_DLL void alib::assert::RegisterPrintable	(	std::type_index	typeIndex,
		AnyConversionFunc	func )

Allows registering custom types to be printable with debug-function alib::assert::Raise. The following snippet from the internal codebase that registers basic types as lambda functions demonstrates how this function can be called:

RegisterPrintable(typeid(double),
    [](const std::any& any, std::string& s) {
        s+= f::format("{}", std::any_cast<double     >(any));
    });
RegisterPrintable(typeid(const char*),
    [](const std::any& any, std::string& s) {
        auto* value= std::any_cast<const char*>(any);
        if (value)
            s+= value;
    });
RegisterPrintable(typeid(const char8_t*),
    [](const std::any& any, std::string& s) {
        auto* value= std::any_cast<const char*>(any);
        if (value)
            s+= value;
    });
RegisterPrintable(typeid(const wchar_t*),
    [](const std::any& any, std::string& s) {
        auto* value= std::any_cast<const wchar_t*>(any);
        if (value)
        {
          ALIB_WARNINGS_IGNORE_DEPRECATED
            std::wstring_convert<std::codecvt_utf8<wchar_t>> converter;
            s+= converter.to_bytes(value);
          ALIB_WARNINGS_RESTORE
        }
    });

Parameters

typeIndex	The type to register a conversion method for.
func	The conversion function.

SingleThreaded()

void alib::assert::SingleThreaded

(

)

This method stores the first thread that invokes it, and if in the future the method is visited by a different thread, it asserts.

In release compilations, this function is inlined and empty, and therefore it is not necessary to remove usages with preprocessor macro ALIB_DBG or similar.

In debug-compilations, this is not empty if:

1. Compiler symbol ALIB_SINGLE_THREADED is set (what disables thread-safeness throughout the library), and
2. Compiler symbol ALIB_EXT_LIB_THREADS_AVAILABLE was passed on library compilation, which allows using the C++ standard library's threading types without causing linker failures.

If given, this function is, for example, called by macros ALIB_LOCK or ALIB_DCS, which otherwise are defined to do what they are supposed to do. This exclamatory approach was made with ALib to motivate to write threading-agnostic software.

Besides several macros, some other prominent ALib entities, like lox::Lox, Formatter or TMonoAllocator invoke this method with their acquisition.

Definition at line 141 of file assert.cpp.

Here is the call graph for this function:

Variable Details:

FORMAT

ALIB_DLL std::string_view alib::assert::FORMAT = "{file}:{line} {type}:\n{message}"

A predefined format string used to generate consistent assertion messages. A goal here is to allow a user of ALib to change this format to have assertions, warnings, and messages in the IDE-console be clickable (to jump to the right source location). The default format works well with JetBrains CLion .

Defaults to: "{file}:{line} {type}:\\n{message}".

(With this default-value, the placeholder syntax should be self-explanatory.)

Definition at line 175 of file assert.cpp.

PLUGIN

void(* alib::assert::PLUGIN)(const lang::CallerInfo &ci, int type, std::string_view domain, std::string_view msg)	(	const CallerInfo &	ci,
		int	type,
		std::string_view	domain,
		std::string_view	msg ) = nullptr

This function pointer defaults to nullptr and may be set by from outside to redirect writing the assertion, warning or message text of functions Raise, respectively raise.

With the use of module ALox this pointer can be set to redirect the output to a Lox. Further information on this is found with the chapter 10.3.4 Logging ALib Assertions of the Programmer's Manual of module ALox.

• ci: Information about the scope of invocation.
• type: The type of the message. As a convention, 0 is severe error, others are warning levels.
• domain: Usually the name of the module that raised the assertion.
• msg: The assembled message to print.

Definition at line 172 of file assert.cpp.

STREAM_ERRORS

ALIB_DLL std::ostream * alib::assert::STREAM_ERRORS = &std::cerr

The output stream used to with function alib::assert::Raise, when the parameter type equals 0.
Defaults to std::err.

Definition at line 176 of file assert.cpp.

STREAM_MESSAGES

ALIB_DLL std::ostream * alib::assert::STREAM_MESSAGES = &std::cout

The output stream used to with function alib::assert::Raise, when the parameter type does not equal 0 or 1.
Defaults to std::cout.

Definition at line 178 of file assert.cpp.

STREAM_WARNINGS

ALIB_DLL std::ostream * alib::assert::STREAM_WARNINGS = &std::cout

The output stream used to with function alib::assert::Raise, when the parameter type equals 1.
Defaults to std::cout.

Definition at line 177 of file assert.cpp.