Container Utils¶
vtr_hash¶
-
namespace vtr¶
std::optional-like interface with optional references. currently: import TartanLlama’s optional into the vtr namespace documentation at https://tl.tartanllama.xyz/en/latest/api/optional.html there are three main uses of this:
replace pointers when refactoring legacy code optional<T&> (reference) is in many ways a pointer, it even has * and -> operators, but it can’t be allocated or freed. this property is very helpful in refactoring.
explicit alternative for containers optional<T> (non-reference) allows you to put non-empty-initializable objects into a container which owns them. it is an alternative to unique_ptr<T> in that sense, but with a cleaner interface.
function return types returning an optional<T> gives the caller a clear hint to check the return value.
Q: why not use std::optional? A: std::optional doesn’t allow optional<T&> due to a disagreement about what it means to assign to an optional reference. tl::optional permits this, with “rebind on assignment” behavior. this means opt<T&> acts very similarly to a pointer. Q: why do we need opt<T&>? there’s already T*. A: in an ideal world where all pointers are aliases to existing values and nothing else, opt<T&> wouldn’t be that necessary. however VPR is full of legacy code where the usual C++ conventions about pointers don’t apply. when refactoring such code, turning all pointers into opt<T&> helps a lot. it can’t be allocated or freed and doesn’t allow pointer arithmetic. in that aspect it acts as a “enforced proper C++ ptr”. that’s why I think it’s worth keeping around in the codebase.
Functions
-
struct hash_pair¶
- #include <vtr_hash.h>
vtr_memory¶
-
namespace vtr
std::optional-like interface with optional references. currently: import TartanLlama’s optional into the vtr namespace documentation at https://tl.tartanllama.xyz/en/latest/api/optional.html there are three main uses of this:
replace pointers when refactoring legacy code optional<T&> (reference) is in many ways a pointer, it even has * and -> operators, but it can’t be allocated or freed. this property is very helpful in refactoring.
explicit alternative for containers optional<T> (non-reference) allows you to put non-empty-initializable objects into a container which owns them. it is an alternative to unique_ptr<T> in that sense, but with a cleaner interface.
function return types returning an optional<T> gives the caller a clear hint to check the return value.
Q: why not use std::optional? A: std::optional doesn’t allow optional<T&> due to a disagreement about what it means to assign to an optional reference. tl::optional permits this, with “rebind on assignment” behavior. this means opt<T&> acts very similarly to a pointer. Q: why do we need opt<T&>? there’s already T*. A: in an ideal world where all pointers are aliases to existing values and nothing else, opt<T&> wouldn’t be that necessary. however VPR is full of legacy code where the usual C++ conventions about pointers don’t apply. when refactoring such code, turning all pointers into opt<T&> helps a lot. it can’t be allocated or freed and doesn’t allow pointer arithmetic. in that aspect it acts as a “enforced proper C++ ptr”. that’s why I think it’s worth keeping around in the codebase.
-
struct t_chunk¶
- #include <vtr_memory.h>
This structure keeps track to chenks of memory
This structure is to keep track of chunks of memory that is being
allocated to save overhead when allocating very small memory pieces. For a complete description, please see the comment in chunk_malloc
-
template<class T>
struct aligned_allocator¶ - #include <vtr_memory.h>
aligned_allocator is a STL allocator that allocates memory in an aligned fashion
works if supported by the platform
It is worth noting the C++20 std::allocator does aligned allocations, but C++20 has poor support.
Functions
-
template<typename Container>
void release_memory(Container &container)¶ This function will force the container to be cleared.
It release it’s held memory. For efficiency, STL containers usually don’t release their actual heap-allocated memory until destruction (even if Container::clear() is called).
-
template<typename T>
T *chunk_new(t_chunk *chunk_info)¶ Like chunk_malloc, but with proper C++ object initialization.
-
template<typename T>
void chunk_delete(T *obj, t_chunk*)¶ Call the destructor of an obj which must have been allocated in the specified chunk.
-
inline int memalign(void **ptr_out, size_t align, size_t size)¶
-
template<typename T>
bool operator==(const aligned_allocator<T>&, const aligned_allocator<T>&)¶ compare two aligned_allocators.
Since the allocator doesn’t have any internal state, all allocators for a given type are the same.
vtr_pair_util¶
-
namespace vtr
-
template<typename PairIter>
class pair_first_iter¶ - #include <vtr_pair_util.h>
Iterator which derefernces the ‘first’ element of a std::pair iterator.
-
template<typename PairIter>
class pair_second_iter¶ - #include <vtr_pair_util.h>
Iterator which derefernces the ‘second’ element of a std::pair iterator
std::optional-like interface with optional references. currently: import TartanLlama’s optional into the vtr namespace documentation at https://tl.tartanllama.xyz/en/latest/api/optional.html there are three main uses of this:
replace pointers when refactoring legacy code optional<T&> (reference) is in many ways a pointer, it even has * and -> operators, but it can’t be allocated or freed. this property is very helpful in refactoring.
explicit alternative for containers optional<T> (non-reference) allows you to put non-empty-initializable objects into a container which owns them. it is an alternative to unique_ptr<T> in that sense, but with a cleaner interface.
function return types returning an optional<T> gives the caller a clear hint to check the return value.
Q: why not use std::optional? A: std::optional doesn’t allow optional<T&> due to a disagreement about what it means to assign to an optional reference. tl::optional permits this, with “rebind on assignment” behavior. this means opt<T&> acts very similarly to a pointer. Q: why do we need opt<T&>? there’s already T*. A: in an ideal world where all pointers are aliases to existing values and nothing else, opt<T&> wouldn’t be that necessary. however VPR is full of legacy code where the usual C++ conventions about pointers don’t apply. when refactoring such code, turning all pointers into opt<T&> helps a lot. it can’t be allocated or freed and doesn’t allow pointer arithmetic. in that aspect it acts as a “enforced proper C++ ptr”. that’s why I think it’s worth keeping around in the codebase.
-
template<typename PairIter>
vtr_map_util¶
-
namespace vtr
std::optional-like interface with optional references. currently: import TartanLlama’s optional into the vtr namespace documentation at https://tl.tartanllama.xyz/en/latest/api/optional.html there are three main uses of this:
replace pointers when refactoring legacy code optional<T&> (reference) is in many ways a pointer, it even has * and -> operators, but it can’t be allocated or freed. this property is very helpful in refactoring.
explicit alternative for containers optional<T> (non-reference) allows you to put non-empty-initializable objects into a container which owns them. it is an alternative to unique_ptr<T> in that sense, but with a cleaner interface.
function return types returning an optional<T> gives the caller a clear hint to check the return value.
Q: why not use std::optional? A: std::optional doesn’t allow optional<T&> due to a disagreement about what it means to assign to an optional reference. tl::optional permits this, with “rebind on assignment” behavior. this means opt<T&> acts very similarly to a pointer. Q: why do we need opt<T&>? there’s already T*. A: in an ideal world where all pointers are aliases to existing values and nothing else, opt<T&> wouldn’t be that necessary. however VPR is full of legacy code where the usual C++ conventions about pointers don’t apply. when refactoring such code, turning all pointers into opt<T&> helps a lot. it can’t be allocated or freed and doesn’t allow pointer arithmetic. in that aspect it acts as a “enforced proper C++ ptr”. that’s why I think it’s worth keeping around in the codebase.
Typedefs
-
template<typename Iter>
using map_key_iter = pair_first_iter<Iter>¶ An iterator who wraps a std::map iterator to return it’s key.
-
template<typename Iter>
using map_value_iter = pair_second_iter<Iter>¶ An iterator who wraps a std::map iterator to return it’s value.
Functions
-
template<typename T>
auto make_key_range(T b, T e)¶ Returns a range iterating over a std::map’s keys.
-
template<typename Container>
auto make_key_range(const Container &c)¶ Returns a range iterating over a std::map’s keys.