alib::boxing Namespace Reference

Description:

DOXYGEN.

This is the reference documentation of sub-namespace boxing of the ALib C++ Library, which holds types of library module ALib Boxing.

Extensive documentation for this module is provided with ALib Module Boxing - Programmer's Manual.

Nested Namespaces:
namespace	compatibility
namespace	debug
namespace	detail
	This namespace implements internals of namespace alib::boxing.

Type Index:
class	Box
struct	BoxTraits
struct	DefaultBoxingTag
struct	Enum
struct	FAppend
struct	FClone
struct	FEquals
struct	FHashcode
struct	FIsLess
struct	FIsNotNull
struct	FIsTrue
struct	NotBoxableTag
struct	Pair
union	Placeholder
struct	SuppressCharArrayBoxingTraits
class	TBoxes
struct	VTableOptimizationTraits

Concepts
concept	IsCustomized
concept	IsStdPH
concept	IsConstExprWrite
concept	IsStringType
concept	IsUnboxableStringType
concept	IsLocked
concept	IsNotBoxable
concept	IsUnboxable

Function Index:
void	bootstrap ()
template<typename TFDecl, typename TMapped, bool TIsArray = false>
void	BootstrapRegister (typename TFDecl::Signature function)
template<typename TFDecl>
void	BootstrapRegisterDefault (typename TFDecl::Signature function)
template<typename TRecord>
const TRecord &	GetRecord (Enum e)
template<typename T1, typename T2> requires ( std::is_trivially_copyable_v<T1> && std::is_trivially_copyable_v<T2> && ( sizeof(T1) + sizeof(T2) <= 2 * sizeof(void*) ) )
constexpr Pair< T1, T2 >	MakePair (const T1 &t1, const T2 &t2)
void	shutdown ()
template<typename TRecord>
const TRecord *	TryRecord (Enum e)

Variable Index:
template<typename TMappedPlain>
constexpr unsigned int	SizeTraits = sizeof(TMappedPlain)
template<>
constexpr unsigned int	SizeTraits< long double > = ALIB_SIZEOF_LONGDOUBLE_WRITTEN

Function Details:

bootstrap()

ALIB_DLL void alib::boxing::bootstrap

(

)

This namespace function initializes the module ALib Boxing.

This function is automatically called by the standard bootstrap code of ALib, hence the (overloaded) functions alib::Bootstrap will call this function.

Definition at line 536 of file boxstrap.cpp.

Here is the call graph for this function:

BootstrapRegister()

template<typename TFDecl, typename TMapped, bool TIsArray = false>

void alib::boxing::BootstrapRegister ( typename TFDecl::Signature function )

inline

Registers box-function function of type TFDecl for boxes of mapped type TMapping.

Attention

Function registration and function invocation are not protected against racing conditions of multithreaded access. For this reason, it is advised to invoke this function exclusively while bootstrapping software, when no threads are started, yet. Registrations can be made before bootstrapping ALib, respectively during or after phase BootstrapPhases::PrepareResources.

If for any reason registration is performed after bootstrapping ALib and module ALib Monomem is included in the ALib Build, and this function is invoked after ALib was bootstrapped, then before an invocation of this method, mutex GLOBAL_ALLOCATOR_LOCK has to be acquired. This can be done with:

{ ALIB_LOCK_RECURSIVE_WITH( alib::monomem::GLOBAL_ALLOCATOR_LOCK )
    //...
    //... your code goes here
    //...
}

Note that even when this lock is set, still multithreaded access to registration and/or box-function invocations is not allowed.

Template Parameters

TFDecl	The type of function to register.
TMapped	The mapped type that boxes store, which are to be equipped with a specialized function implementation.
TIsArray	Denotes whether array-boxing is applied. Defaults to false.

Parameters

function

Pointer to the function implementation.

Definition at line 1254 of file box.inl.

Here is the call graph for this function:

BootstrapRegisterDefault()

template<typename TFDecl>

void alib::boxing::BootstrapRegisterDefault ( typename TFDecl::Signature function )

inline

Registers a default implementation of a box-function, which is invoked if no type-specific implementation is registered for a mapped type.

Attention

Function registration and function invocation are not protected against racing conditions of multithreaded access. For this reason, it is advised to invoke this function exclusively while bootstrapping software, when no threads are started, yet. Registrations can be made before bootstrapping ALib, respectively during or after phase BootstrapPhases::PrepareResources.

If for any reason registration is performed after bootstrapping ALib and module ALib Monomem is included in the ALib Build, and this function is invoked after ALib was bootstrapped, then, before an invocation of this method, mutex GLOBAL_ALLOCATOR_LOCK has to be acquired. This can be done with:

{ ALIB_LOCK_RECURSIVE_WITH( alib::monomem::GLOBAL_ALLOCATOR_LOCK )
    //...
    //... your code goes here
    //...
}

Note that even when this lock is set, still multithreaded access to registration and/or box-function invocations is not allowed.

Template Parameters

TFDecl

The type of function to register.

Parameters

function

Pointer to the function's default implementation.

Definition at line 1292 of file box.inl.

GetRecord()

template<typename TRecord>

const TRecord & alib::boxing::GetRecord

(

Enum

e

)

Returns the ALib Enum Record associated with the given instance of class Enum, which is defined in module ALib Boxing.

In debug-compilations an ALib assertion is raised, if no enum record was defined for the enumeration element represented by this instance.

See also

• Namespace function enumrecords::GetRecord of module ALib EnumRecords, which provides the standard way of accessing enum records for enum elements known at compile-time.
• Sibling method TryRecord.

Template Parameters

TRecord

The enumeration record type associated with the enum type. This has to be explicitly provided. It is the caller's obligation to ensure that the requested type equals the one associated. Otherwise, this method produces undefined behavior.

Parameters

e	The enumeration element, boxed in class Enum.

Returns

The record that is associated with this enumeration element.

Definition at line 31 of file boxing_enums.inl.

Here is the call graph for this function:

MakePair()

template<typename T1, typename T2>
requires ( std::is_trivially_copyable_v<T1> && std::is_trivially_copyable_v<T2> && ( sizeof(T1) + sizeof(T2) <= 2 * sizeof(void*) ) )

Pair< T1, T2 > alib::boxing::MakePair ( const T1 & t1, const T2 & t2 )

constexpr

This is a simple helper function that constructs a Pair.

Template Parameters

T1	The type of the first value. Deduced by the compiler.
T2	The type of the second first value. Deduced by the compiler.

Parameters

t1	The first value.
t2	The second value.

Returns

The pair of deduced types.

Definition at line 774 of file boxing/placeholder.inl.

shutdown()

ALIB_DLL void alib::boxing::shutdown

(

)

Frees resources and shuts down module ALib Boxing. Multiple invocations of this method are forbidden. The standard bootstrap code of ALib, hence the (overloaded) functions alib::Shutdown will call this function.

This function is automatically called by the standard bootstrap code of ALib, hence the (overloaded) functions alib::Bootstrap will call this function.

Definition at line 529 of file boxstrap.cpp.

Here is the call graph for this function:

TryRecord()

template<typename TRecord>

const TRecord * alib::boxing::TryRecord

(

Enum

e

)

Returns a pointer to the ALib Enum Record associated with this the enumeration element represented by this instance. If no enum record was is defined, nullptr is returned.

See also

• Namespace function enumrecords::TryRecord of module ALib EnumRecords, which provides the standard way of accessing enum records for enum elements known at compile-time.
• Sibling method GetRecord.

Template Parameters

TRecord

The enumeration record type associated with the enum type. This has to be explicitly provided. It is the caller's obligation to ensure that the requested type equals the one associated. Otherwise this method produces undefined behavior.

Parameters

e	The enumeration element, boxed in class Enum.

Returns

A pointer to the record that is associated with this enumeration element, respectively nullptr if no record was found.

Definition at line 58 of file boxing_enums.inl.

Here is the call graph for this function:

Variable Details:

SizeTraits

template<typename TMappedPlain>

unsigned int alib::boxing::SizeTraits = sizeof(TMappedPlain)

inlineconstexpr

This specializable constexpr must be set for custom types, if the following applies:

• A custom boxing implements BoxTraits::Write in a way that a different number of bytes are used in union Placeholder than the sizeof() operator reports on the mapped type's size.
• if the standard copy constructor (used with default boxing) writes a different size.
• One of the above and no specialized version of both box-functions FHashcode or FEquals are set.

Background:
The default implementations of FHashcode and FEquals must use the first N "relevant" bytes of the placeholder only. The non-relevant bytes are not written and therefore must not be taken into account.
To receive the number of relevant bytes, they invoke Box::GetPlaceholderUsageLength (at run-time). This value is set at compile-time with the creation of a mapped type's vtable. While for array types, the value is set to the overall size of union Placeholder, for non-array types, the value of this type trait is used.

It might be surprising, but a built-in specialization exists for even a C++ fundamental type long double, which is dependent on the compiler/platform. For example, on GNU/Linux 64-bit, GCC reports 16 with sizeof(long double). However, if a long double value is copied, e.g with:

 *pointerToLongDouble= 3.14L;

then only 10 bytes are written. The reason for this is that sizeof reports the size needed for alignment when placed in an array of that type. In the case of ALib Boxing, 6 bytes of the placeholder remain random and therefore must not be used for hashing or testing values on equality.

Template Parameters

TMappedPlain

The mapped type to modify relevant placeholder length for FHashcode and FEquals implementation.

Definition at line 267 of file boxingtraits.inl.

SizeTraits< long double >

template<>

unsigned int alib::boxing::SizeTraits< long double > = ALIB_SIZEOF_LONGDOUBLE_WRITTEN

inlineconstexpr

Specialization of traits-expression for type long double. The implementation of this type is platform-dependent and may be adopted to a certain compiler/processor combination by passing the compiler-symbol ALIB_SIZEOF_LONGDOUBLE_WRITTEN.

Definition at line 274 of file boxingtraits.inl.