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:

  1. 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.

  2. 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.

  3. 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

template<class T>
inline void hash_combine(std::size_t &seed, const T &v)

Hashes v and combines it with seed (as in boost)

This is typically used to implement std::hash for composite types.

struct hash_pair
#include <vtr_hash.h>

Public Functions

template<class T1, class T2>
inline std::size_t operator()(const std::pair<T1, T2> &pair) const noexcept

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:

  1. 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.

  2. 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.

  3. 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.

Public Functions

inline pair_first_iter(PairIter init)

constructor

inline auto operator++()

increment operator (++)

inline auto operator--()

decrement operator (–)

inline auto operator*()

dereference * operator

inline auto operator->()

-> operator

template<typename PairIter>
class pair_second_iter
#include <vtr_pair_util.h>

Iterator which derefernces the ‘second’ element of a std::pair iterator

Public Functions

inline pair_second_iter(PairIter init)

constructor

inline auto operator++()

increment operator (++)

inline auto operator--()

decrement operator (&#8212;)

inline auto operator*()

dereference * operator

inline auto operator->()

-> operator

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:

  1. 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.

  2. 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.

  3. 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.

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:

  1. 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.

  2. 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.

  3. 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.

template<typename T>
auto make_value_range(T b, T e)

Returns a range iterating over a std::map’s values.

template<typename Container>
auto make_value_range(const Container &c)

Returns a range iterating over a std::map’s values.