vecmem::details Namespace Reference

Namespace for types that should not be used directly by clients. More...

Classes
class	arena_memory_resource_impl
	Implementation backend for vecmem::details::arena_page_memory_resource. More...
struct	binary_page_memory_resource_impl
	Implementation of vecmem::binary_page_memory_resource. More...
class	choice_memory_resource_impl
	Implementation for vecmem::details::choice_memory_resource. More...
class	coalescing_memory_resource_impl
	Implementation for vecmem::details::coalescing_memory_resource. More...
class	conditional_memory_resource_impl
	Implementation for vecmem::details::conditional_memory_resource. More...
struct	conjunction
	Implementation for std::conjunction. More...
struct	conjunction< B1 >
struct	conjunction< B1, Bn... >
class	contiguous_memory_resource_impl
	Implementation of vecmem::contiguous_memory_resource. More...
class	debug_memory_resource_impl
	Implementation for vecmem::details::debug_memory_resource. More...
struct	disjunction
	Implementation for std::disjunction. More...
struct	disjunction< B1 >
struct	disjunction< B1, Bn... >
class	instrumenting_memory_resource_impl
	Implementation for vecmem::details::instrumenting_memory_resource. More...
struct	is_same_nc
	Helper trait for detecting when a type is a non-const version of another. More...
struct	is_same_nc< const TYPE, TYPE >
class	jagged_device_vector_iterator
	Custom iterator for vecmem::jagged_device_vector. More...
class	memory_resource_base
	Base class for implementations of the vecmem::memory_resource interface. More...
struct	negation
	Implementation for std::negation. More...
class	pool_memory_resource_impl
	Implementation of vecmem::pool_memory_resource. More...
class	reverse_iterator
	Type mimicking std::reverse_iterator. More...
struct	static_array_type
	Helper type for an array with a given type and size. More...
struct	static_array_type< T, 0 >
struct	static_vector_type
	Helper type for an array in a static_vector with a given type and size. More...
struct	static_vector_type< T, 0 >
struct	tuple_get_impl
	Struct used to implement vecmem::get in a C++14 style. More...
struct	tuple_get_impl< 0 >
	Specialization of vecmem::details::tuple_get_impl for the 0th element. More...
struct	unique_alloc_deleter
	A deleter class for trivial allocations. More...
struct	unique_obj_deleter
	A deleter class for non-trivial objects. More...

Typedefs
template<typename iterator_type , typename value_type >
using	is_iterator_of = std::is_convertible< typename std::iterator_traits< iterator_type >::value_type, value_type >
	Helper trait for identifying input iterators.

Functions
template<typename... Ts, typename... Ps>
std::tuple< vecmem::unique_alloc_ptr< char[]>, std::add_pointer_t< Ts >... >	aligned_multiple_placement (vecmem::memory_resource &r, Ps &&... ps)
	Allocation of aligned arrays of given types.
template<typename T , typename ALLOC1 , typename ALLOC2 >
void	resize_jagged_vector (std::vector< std::vector< T, ALLOC1 >, ALLOC2 > &vec, std::size_t size)
	Resize a generic jagged vector.
template<typename T >
void	resize_jagged_vector (jagged_vector< T > &vec, std::size_t size)
	Resize a vecmem jagged vector.
template<typename T1 , typename T2 >
VECMEM_HOST_AND_DEVICE bool	operator== (const reverse_iterator< T1 > &itr1, const reverse_iterator< T2 > &itr2)
	Comparison operator for reverse iterators.
template<typename T1 , typename T2 >
VECMEM_HOST_AND_DEVICE bool	operator!= (const reverse_iterator< T1 > &itr1, const reverse_iterator< T2 > &itr2)
	Comparison operator for reverse iterators.
template<typename T , typename... Ts, typename P , typename... Ps>
std::tuple< std::add_pointer_t< T >, std::add_pointer_t< Ts >... >	aligned_multiple_placement_helper (void *p, std::size_t q, P n, Ps &&... ps)
	Helper function for aligned_multiple_placement.
VECMEM_HOST bool VECMEM_CORE_EXPORT	is_aligned (void *ptr, std::size_t alignment)
	Helper function checking if a given pointer has a given alignment.
constexpr int	memorder_to_posix_builtin (memory_order o)
	Convert a memory order to the corresponding builtin memory order.
template<typename T >
T	get_nonexistent_pointer ()
	Helper function for generating a nonexistent, but still "aligned" pointer.
template<typename T >
auto	max (T &&t)
	Find the maximum of a variadic number of elements, terminal function.
template<typename T , typename... Ts>
auto	max (T &&t, Ts &&... ts)
	Find the maximum of a variadic number of elements, recursive function.
bool	is_power_of_2 (std::size_t x)
	Check if a number is a power of 2.
std::size_t	clzl (std::size_t i)
	Count the leading zeroes in a number.
std::size_t	log2 (std::size_t x)
	Compute the base-2 logarithm of a number.
std::size_t	log2_ri (std::size_t x)
	Compute the base-2 logarithm of a number, rounding up to the nearest log.
std::size_t	round_up (std::size_t size)
	Rounds a size up to the nearest power of two, and returns the power (not the size itself).

Variables
template<class... B>
constexpr bool	conjunction_v = conjunction<B...>::value
template<class... B>
constexpr bool	disjunction_v = disjunction<B...>::value
template<class B >
constexpr bool	negation_v = negation<B>::value
template<class TYPE >
using	is_implicit_lifetime = std::true_type
	Type trait that indicates whether a given type is an implicit lifetime type.
template<class TYPE >
constexpr bool	is_implicit_lifetime_v = is_implicit_lifetime<TYPE>::value

Detailed Description

Namespace for types that should not be used directly by clients.

These would be classes/functions/types that are needed by the public interface of classes/functions outside of this namespace.

Typedef Documentation

is_implicit_lifetime

template<class TYPE >

using vecmem::details::is_implicit_lifetime = typedef std::true_type

Type trait that indicates whether a given type is an implicit lifetime type.

Note

The definition of "implicit lifetime type" differs a lot across C++ standards, as does the implementation of this type trait. In C++17 and earlier, the concept of such types did not exist. In C++20, these types were defined but no type trait for them was available. In C++23, a type trait is available.

Warning

On pre-C++17 translation units, this type trait is always assumed to be true.

is_iterator_of

template<typename iterator_type , typename value_type >

using vecmem::details::is_iterator_of = typedef std::is_convertible< typename std::iterator_traits<iterator_type>::value_type, value_type>

Helper trait for identifying input iterators.

It comes in handy in some of the functions of the custom (device) container types that use templated iterator values. Which could hide overloads of the same function with the same number of (non-templated) arguments.

The implementation is very simplistic at the moment. It could/should be made more elaborate when the need arises.

Function Documentation

aligned_multiple_placement()

template<typename... Ts, typename... Ps>

std::tuple< vecmem::unique_alloc_ptr< char[]>, std::add_pointer_t< Ts >... > vecmem::details::aligned_multiple_placement	(	vecmem::memory_resource &	r,
		Ps &&...	ps
	)

Allocation of aligned arrays of given types.

This function allocates a chunk of memory containing a set of arrays of different types in a consecutive fashion. For example, let's say we want to allocate:

1. 3 ints (4 bytes each, aligned to 4 byte boundaries)
2. 2 longs (8 bytes each, aligned to 8 byte boundaries)
3. 7 shorts (2 bytes each, unaligned)

This corresponds with the following evocation of this function:

aligned_multiple_placement<int, long, short>(r, 3, 2, 7)

Under these rules, the function would allocate a chunk of memory that looks like this:

     ┌────────────────────────────────────────────────────────────────┐
Byte │╭ 00      ╭ 10      ╭ 20      ╭ 30      ╭ 40      ╭ 50      ╭ 60│
Data │-----###IIIIIIIIIIII####LLLLLLLLLLLLLLLLSSSSSSSSSSSSSS###-------│
Info │╰ A  ╰ B╰ C             ╰ D             ╰ E             ╰ F     │
     └────────────────────────────────────────────────────────────────┘

In this diagram, we see a small 64-byte memory space, with the "-" character denoting memory that is unallocated, "#" denoting memory that is used as padding to meet alignment requirements, and "I", "L", and "S" denoting ints, longs, and shorts, respectively.

The total memory space runs from marker A to past the end of the diagram. The region from B to F indicates the memory that we have allocated to store our data. Note that we do not have control over where this region starts! In other words, A could be positioned anywhere along the memory space. In reality, most allocators have their own alignment guarantees and would not return memory at address 5 like we see here. However, we include it here for demonstrative purposes.

Marker C denotes the start of our region of three integers, which takes twelve bytes in total. The important idea here is that we cannot start this region right at the start of our allocation (at B), because address B, 5, is not a multiple of the 4-byte alignment requirement of the integer type. Thus, we must insert three bytes of padding (denoted by "#"), and our ints start at marker C (address 8). They end twelve bytes later, at address 20.

Following our integers, we want to allocate two longs, which must be aligned to 8 byte boundaries. If we were to immediately succeed our integers with these longs, they would start at address 20, which is not a multiply of 8. Therefore, we must insert additional padding before starting our region of longs at marker D (address 24).

It is worth noting that this method extends to an arbitrary number of type regions, although in practice the number will usually be limited (it might even just be 2 in all cases). If there is only a single type, this function simply serves as an alignment operator akin to std::align.

Note

This function is pessimistic in its allocation of memory, meaning that it will usually allocate slightly too much memory to be on the safe side. This should have a negligible impact on real-world applications.

Template Parameters

Ts	The types to allocate memory for.
Ps	Positional parameter types, which should all be std::size or a compatible type, and the length must be equal to that of Ts.

Parameters

r	The memory resource to use for allocation.
ps	The set of sizes of the differently typed regions.

Returns

A tuple of |Ts| + 1 elements, where the first element is a unique allocation pointer to the complete block of memory (such that it may be freed), and the other values represent the addresses in memory where the regions begin.

aligned_multiple_placement_helper()

template<typename T , typename... Ts, typename P , typename... Ps>

std::tuple< std::add_pointer_t< T >, std::add_pointer_t< Ts >... > vecmem::details::aligned_multiple_placement_helper	(	void *	p,
		std::size_t	q,
		P	n,
		Ps &&...	ps
	)

Helper function for aligned_multiple_placement.

First, please don't use this function by itself. It is meant to be used only as a helper function.

This function recursively reserves regions in a pre-allocated region of memory, and enforces most of the alignment semantics that are given for the aligned_multiple_placement function.

Warning

This function enforces no requirements on anything, because those requirements are already enforced by aligned_multiple_placement.

Template Parameters

T	The head of the pack of types.
Ts	The (possibly empty) tail of the pack of types.
P	The head of the pack of sizes.
Ps	The (possibly empty) tail of the pack of sizes.

Parameters

p	The pointer at which (or past which) to begin this region.
q	The remaining space available for allocation.
n	The number of objects of type T to allocate space for.
Ps	The remaining sizes for future types.

Returns

A tuple of size |Ts| + 1, where each element is a pointer to the address that marks the beginning of those regions.

clzl()

std::size_t vecmem::details::clzl ( std::size_t  i )

inline

Count the leading zeroes in a number.

Parameters

i	The number to count the leading zeroes in

Returns

The number of leading zeroes in i

get_nonexistent_pointer()

template<typename T >

T vecmem::details::get_nonexistent_pointer

(

)

Helper function for generating a nonexistent, but still "aligned" pointer.

Template Parameters

T	The type of the pointer

Returns

The pointer

is_aligned()

VECMEM_HOST bool vecmem::details::is_aligned	(	void *	ptr,
		std::size_t	alignment
	)

Helper function checking if a given pointer has a given alignment.

It is used for debugging/validation by some parts of the code, it is not meant to be used by clients of the library directly.

Parameters

ptr	The pointer that is to be checked
alignment	The alignment that the pointer should be checked for

Returns

true if the pointer has the queried alignment, false otherwise

is_power_of_2()

bool vecmem::details::is_power_of_2 ( std::size_t  x )

inline

Check if a number is a power of 2.

Parameters

x	The number to check

Returns

true if x is a power of 2, false otherwise

log2()

std::size_t vecmem::details::log2 ( std::size_t  x )

inline

Compute the base-2 logarithm of a number.

Parameters

x	The number to compute the logarithm of

Returns

The base-2 logarithm of x

log2_ri()

std::size_t vecmem::details::log2_ri ( std::size_t  x )

inline

Compute the base-2 logarithm of a number, rounding up to the nearest log.

Parameters

x	The number to compute the logarithm of

Returns

The base-2 logarithm of x

max() [1/2]

template<typename T >

auto vecmem::details::max

(

T &&

t

)

Find the maximum of a variadic number of elements, terminal function.

Template Parameters

T	The type of the (final) element

Parameters

t	The value of the (final) element

Returns

The value of the (final) element

max() [2/2]

template<typename T , typename... Ts>

auto vecmem::details::max	(	T &&	t,
		Ts &&...	ts
	)

Find the maximum of a variadic number of elements, recursive function.

Template Parameters

T	The type of the (next) element
Ts	The types of the remaining element(s)

Parameters

t	The value of the (next) element
ts	The values of the remaining element(s)

Returns

The maximum of the elements

memorder_to_posix_builtin()

constexpr int vecmem::details::memorder_to_posix_builtin ( memory_order  o )

constexpr

Convert a memory order to the corresponding builtin memory order.

Parameters

o	The (vecmem) memory order

Returns

The corresponding builtin memory order

resize_jagged_vector() [1/2]

template<typename T >

void vecmem::details::resize_jagged_vector	(	jagged_vector< T > &	vec,
		std::size_t	size
	)

Resize a vecmem jagged vector.

It makes sure that all of the "internal" vectors would use the same memory resource as the "external" one does.

Parameters

vec	The vector to resize
size	The size to resize the jagged vector to

resize_jagged_vector() [2/2]

template<typename T , typename ALLOC1 , typename ALLOC2 >

void vecmem::details::resize_jagged_vector	(	std::vector< std::vector< T, ALLOC1 >, ALLOC2 > &	vec,
		std::size_t	size
	)

Resize a generic jagged vector.

It does exactly what std::vector::resize does.

Parameters

vec	The vector to resize
size	The size to resize the jagged vector to