STAPL: Runtime Utilities

Support functions and classes for the Runtime System. More...

Collaboration diagram for Runtime Utilities:

Classes
class	stapl::runtime::exception
	Runtime base exception object. More...

class	stapl::runtime::runtime_error
	Runtime error exception object. More...

struct	stapl::runtime::heap_tracker_init
	Nifty counter idiom to initialize the heap tracker and keep it alive until the last object file that uses it is finalized. More...

class	stapl::runtime::memory_allocator
	Provides interfaces to do pool allocation for objects. More...

struct	stapl::runtime::uint_rng< size_t >
	Returns a suitable random number generator for the given unsigned integral type size. More...

class	stapl::runtime::any
	any can hold an object of any type. The object can be retrieved only by casting to the correct type. More...

class	stapl::runtime::any_range< T >
	Type erased range of const objects with associated size information. More...

class	stapl::runtime::block_registry< Key, Mapped >
	Implements a registry that allows registration of ranges (blocks) of keys to be used by an entity that has a unique id. More...

class	stapl::runtime::bool_mutex
	Bool based mutex. More...

class	stapl::runtime::c_string
	Wraps a C string into a class. More...

class	stapl::runtime::cache_line_aligned_allocator< T >
	An allocator that enforces that all allocated memory returned to the caller begins at the start of a cache line. More...

class	stapl::runtime::cache_line_aligned_storage< T >
	Storage for a single instance of type `T`. Class has `alignas` directive to ensure cache line alignment. Used as storage type for `cache_line_aligned_vector`. More...

class	stapl::runtime::cache_line_aligned_vector< T >
	Basic vector class based on `std::vector` which enforces cache line alignment. More...

struct	stapl::runtime::comparator< T, IsEmpty >
	Function object to test if two objects are equal. More...

class	stapl::runtime::comparable_proxy
	Proxy object that allows type-erased objects or function pointers to be compared between them. More...

struct	std::hash< stapl::runtime::comparable_proxy >
	Hash value creation functor for stapl::runtime::comparable_proxy. More...

struct	stapl::runtime::identity< Arg, Result >
	Identity mapping function. More...

struct	stapl::runtime::blocked< Arg, Result >
	Block mapping function. More...

struct	stapl::runtime::fixed< Result >
	Fixed mapping function. More...

struct	stapl::runtime::arbitrary< Arg, Result >
	Arbitrary mapping function. More...

class	stapl::runtime::logical_clock
	Implements a logical clock for managing epochs. More...

class	stapl::runtime::malloc_allocator< T >
	An allocator that uses `std::malloc()` directly. More...

class	stapl::runtime::papi_clock
	Represents a clock based on `PAPI_get_real_usec()`. More...

class	stapl::runtime::papi_cycle_clock
	Represents a clock based on `PAPI_get_real_cyc()` and `MHz`. More...

class	stapl::runtime::pool
	Pool of memory chunks of a specific size. More...

class	stapl::runtime::ref_counted< T, Deleter >
	Provides a reference counting mechanism for objects that derive from it. More...

class	stapl::runtime::ref_counted_wrapper< T >
	Wrapper over `T` to make it conformable with ref_counted. More...

class	stapl::runtime::ref_counted_range< T >
	Provides a range-based interface for ref_counted derived objects. More...

class	stapl::runtime::spmd_registry
	Registry for SPMD-registered objects. More...

class	stapl::runtime::timer< Clock >
	Provides a timer mechanism. More...

class	stapl::runtime::binomial_tree_iterator< IntType, Size >
	Iterator to generate range of children ids required from make_binomial_tree. More...

class	stapl::runtime::tl_pools
	Thread local memory chunk pools. More...

class	stapl::runtime::nested_wf
	Function object to create a new threads-only environment. More...

class	stapl::runtime::global_wf
	Function object to create a new distributed or mixed-mode environment. More...

Macros
#define	STAPL_RUNTIME_CHECK(E, M)
	Ensures the given input condition is true. More...

#define	STAPL_RUNTIME_ERROR(M) stapl::runtime::assert_fail("STAPL Runtime Error: " M, BOOST_CURRENT_FUNCTION)
	Prints the given message and aborts execution.

#define	STAPL_RUNTIME_WARNING(M) stapl::runtime::warning("STAPL Runtime Warning: " M, BOOST_CURRENT_FUNCTION)
	Prints the given message as a warning.

#define	STAPL_RUNTIME_ASSERT(E)
	Ensures the given input condition is true. More...

#define	STAPL_RUNTIME_ASSERT_MSG(E, M)
	Ensures the given input condition is true. More...

#define	STAPL_USE_MANAGED_ALLOC(class_name)
	Enables allocation through a pool back by the stapl::runtime::memory_allocator for the class that this macro is in. More...

Functions
int	stapl::runtime::get_debug_level (void) noexcept
	Returns the debug level of the runtime.

constexpr std::size_t	stapl::runtime::new_impl::normalize_size (const std::size_t s) noexcept
	Normalizes small number of bytes to specific buckets. More...

template<typename T , typename Handle >
T &	stapl::runtime::retrieve_object (Handle &&h, location_md &l) noexcept
	Returns a reference to the object that `h` refers to. More...

template<typename T , typename Handle >
T *	stapl::runtime::try_retrieve_object (Handle &&h, location_md *const l) noexcept
	Attempts to return a pointer to the object that `h` refers to. More...

c_string	stapl::runtime::demangle (const char *)
	Returns a demangled version of the given mangled name.

c_string	stapl::runtime::demangle (c_string const &)
	Returns a demangled version of the given mangled name.

std::size_t	stapl::runtime::get_total_physical_memory (void) noexcept
	Returns the total amount of physical memory in bytes.

std::size_t	stapl::runtime::get_used_physical_memory (void) noexcept
	Returns the amount of physical memory that is being used in bytes.

std::size_t	stapl::runtime::get_available_physical_memory (void) noexcept
	Returns the amount of physical memory available in bytes.

std::size_t	stapl::runtime::get_physical_memory_load (void) noexcept
	Returns the percentage of physical memory that is being used (0-100).

std::size_t	stapl::runtime::get_num_hardware_threads (void) noexcept
	Returns the number of hardware threads on the system.

template<typename Range , typename T >
auto	stapl::runtime::find_index (Range const &r, T const &v) noexcept -> typename std::iterator_traits< decltype(std::begin(r))>::difference_type
	Finds index of the given element in a range. More...

template<typename Range >
bool	stapl::runtime::all_unique (Range const &r)
	Returns `true` if the range has unique elements, otherwise returns `false`.

template<typename UIntType >
UIntType	stapl::runtime::integral_ceil_log2 (UIntType i) noexcept
	Log2 algorithm for unsigned integral types. More...

template<typename UIntType , typename Size >
UIntType	stapl::runtime::set_bits (UIntType dst, UIntType v, Size msb, Size lsb) noexcept
	Sets the [`msb`, `lsb`] bits of `dst` to value `v` and returns the new `dst`.

template<typename UIntType , typename Size >
UIntType	stapl::runtime::read_bits (UIntType dst, Size msb, Size lsb) noexcept
	Reads the [`msb`, `lsb`] bits of `dst`.

template<typename T >
std::vector< T >	stapl::runtime::make_vector (std::vector< T > v)
	Returns a `std::vector<T>`. More...

template<typename T , typename InputIterator >
std::vector< T >	stapl::runtime::make_vector (InputIterator first, InputIterator last)
	Returns a `std::vector<T>`. More...

template<typename T , typename U , typename = typename std::enable_if< !std::is_same< std::vector<T>, typename std::decay<U>::type >::value>::type>
std::vector< T >	stapl::runtime::make_vector (U &&u)
	Returns a `std::vector<T>`. More...

template<typename T , typename Deleter >
void	stapl::runtime::intrusive_ptr_add_ref (ref_counted< T, Deleter > *p) noexcept
	Increases the reference count of the object pointed to by `p`. More...

template<typename T , typename Deleter >
void	stapl::runtime::intrusive_ptr_release (ref_counted< T, Deleter > *p) noexcept
	Decreases the reference count of the object pointed to by `p` and and deletes it if the count has reached `0`. More...

template<typename T , typename... Args>
boost::intrusive_ptr< T >	stapl::runtime::make_ref_counted (Args &&... args)
	Constructs an object of type `T` that provides the interface and functionality of ref_counter using `args` as the parameter list for the constructor of `T`.

template<typename T >
std::vector< T >	stapl::runtime::split_string_to_vector (std::string const &s, const char *delims)
	Splits the given `std::string` to a vector of `T`, based on the delimiters. More...

template<typename IntType , typename Size >
std::tuple< IntType, IntType, decltype(boost::irange(std::declval< IntType >), std::declval< IntType >)))>	stapl::runtime::make_flat_tree (IntType myid, Size n)
	Returns the root, parent and children ids for the part of a flat tree that `myid` belongs to. More...

template<typename IntType , typename Size >
std::tuple< IntType, IntType, decltype(boost::irange(std::declval< IntType >), std::declval< IntType >)))>	stapl::runtime::make_binary_tree (IntType myid, Size n)
	Returns the root, parent and children ids for the part of a binary tree that `myid` belongs to. More...

template<typename IntType , typename Size >
std::tuple< IntType, IntType, boost::iterator_range< binomial_tree_iterator< IntType, Size > > >	stapl::runtime::make_binomial_tree (IntType myid, Size n)
	Returns the root, parent and children ids for the part of a binomial tree that `myid` belongs to. More...

template<typename... T>
void	stapl::runtime::unused (T &&...)
	Function to remove warnings on unused variables.

std::size_t	hash_value (comparable_proxy const &t) noexcept
	Returns the hash value for `t`.

Variables
static struct stapl::runtime::heap_tracker_init	stapl::runtime::hpi

Detailed Description

Support functions and classes for the Runtime System.

Macro Definition Documentation

◆ STAPL_RUNTIME_CHECK

#define STAPL_RUNTIME_CHECK	(	E,
		M
	)

Value:

( (E) ?                                                                   \
    (static_cast<void>(0)) :                                                \
    (stapl::runtime::assert_fail("STAPL Runtime Check Failed (" #E "): " M, \
                                 __FILE__, __LINE__, BOOST_CURRENT_FUNCTION)) )

Ensures the given input condition is true.

If E is true, nothing happens, otherwise the error message M is printed and the program aborts.

This is not disabled by STAPL_NDEBUG or STAPL_RUNTIME_NDEBUG.

◆ STAPL_RUNTIME_ASSERT

#define STAPL_RUNTIME_ASSERT ( E )

Value:

( (std::uncaught_exception() || (E)) ?                                    \
    (static_cast<void>(0)) :                                                \
    (stapl::runtime::assert_fail("STAPL Runtime Assertion (" #E ") failed", \
                                 __FILE__, __LINE__, BOOST_CURRENT_FUNCTION)) )

Ensures the given input condition is true.

If E is true, nothing happens, otherwise the E is printed and the program aborts.

◆ STAPL_RUNTIME_ASSERT_MSG

#define STAPL_RUNTIME_ASSERT_MSG	(	E,
		M
	)

Value:

( (std::uncaught_exception() || (E)) ?                               \
    (static_cast<void>(0)) :                                           \
    (stapl::runtime::assert_fail("STAPL Runtime Assertion: \"" M "\"", \
                                 __FILE__, __LINE__, BOOST_CURRENT_FUNCTION)) )

Ensures the given input condition is true.

If E is true, nothing happens, otherwise the error message M is printed and the program aborts.

◆ STAPL_USE_MANAGED_ALLOC

#define STAPL_USE_MANAGED_ALLOC ( class_name )

Value:

static void* operator new(std::size_t size)                                 \
  {                                                                           \
    STAPL_RUNTIME_ASSERT_MSG(size==sizeof(class_name), "sizes do not match"); \
    const std::size_t ns = stapl::runtime::new_impl::normalize_size(size);    \
    return stapl::runtime::memory_allocator::allocate(ns);                    \
  }                                                                           \
                                                                              \
  static void operator delete(void* p, std::size_t size) noexcept             \
  {                                                                           \
    STAPL_RUNTIME_ASSERT_MSG(size==sizeof(class_name), "sizes do not match"); \
    const std::size_t ns = stapl::runtime::new_impl::normalize_size(size);    \
    return stapl::runtime::memory_allocator::deallocate(p, ns);               \
  }

Enables allocation through a pool back by the stapl::runtime::memory_allocator for the class that this macro is in.

Warning: This macro has to be after a public storage specifier.

Function Documentation

◆ normalize_size()

constexpr std::size_t stapl::runtime::new_impl::normalize_size ( const std::size_t s )

noexcept

Normalizes small number of bytes to specific buckets.

If the number of bytes is less that 16, 32, 64 or 128, then it goes to the 16-byte bucket, 32-byte bucket, 64-byte bucket or 128-byte bucket respectively.

◆ retrieve_object()

template<typename T , typename Handle >

T& stapl::runtime::retrieve_object	(	Handle &&	h,
		location_md &	l
	)

noexcept

Returns a reference to the object that h refers to.

◆ try_retrieve_object()

template<typename T , typename Handle >

T* stapl::runtime::try_retrieve_object	(	Handle &&	h,
		location_md *const	l
	)

noexcept

Attempts to return a pointer to the object that h refers to.

This function will return a pointer to the object even if the requesting code executes in a gang other than the one that the object was registered in. The only requirement is that the location the object registered in and the location that the caller executes in are scheduled on the same thread.

Warning: If the function is given an invalid handle, it will return nullptr.

◆ find_index()

template<typename Range , typename T >

auto stapl::runtime::find_index	(	Range const &	r,
		T const &	v
	)		-> typename std::iterator_traits<decltype(std::begin(r))>::difference_type

noexcept

Finds index of the given element in a range.

Template Parameters

Range	Range type.
T	Element type.

Warning: This function has time complexity.

Parameters

r	Range to find the element in.
v	Element to be found.

Returns: The index of v in r. If not found, returns r.size().

◆ integral_ceil_log2()

template<typename UIntType >

UIntType stapl::runtime::integral_ceil_log2 ( UIntType i )

noexcept

Log2 algorithm for unsigned integral types.

From http://graphics.stanford.edu/~seander/bithacks.html

◆ make_vector() [1/3]

template<typename T >

std::vector<T> stapl::runtime::make_vector ( std::vector< T > v )

Returns a std::vector<T>.

Parameters

v	The vector to return.

◆ make_vector() [2/3]

template<typename T , typename InputIterator >

std::vector<T> stapl::runtime::make_vector	(	InputIterator	first,
		InputIterator	last
	)

Returns a std::vector<T>.

Parameters

first	Iterator to the start of the range.
last	Iterator to the end of the range.

◆ make_vector() [3/3]

template<typename T , typename U , typename = typename std::enable_if< !std::is_same< std::vector<T>, typename std::decay<U>::type >::value>::type>

std::vector<T> stapl::runtime::make_vector ( U && u )

Returns a std::vector<T>.

Parameters

u	Value range.

◆ intrusive_ptr_add_ref()

template<typename T , typename Deleter >

void stapl::runtime::intrusive_ptr_add_ref ( ref_counted< T, Deleter > * p )

noexcept

Increases the reference count of the object pointed to by p.

Required for boost::intrusive_ptr compliance.

◆ intrusive_ptr_release()

template<typename T , typename Deleter >

void stapl::runtime::intrusive_ptr_release ( ref_counted< T, Deleter > * p )

noexcept

Decreases the reference count of the object pointed to by p and and deletes it if the count has reached 0.

Required for boost::intrusive_ptr compliance.

◆ split_string_to_vector()

template<typename T >

std::vector<T> stapl::runtime::split_string_to_vector	(	std::string const &	s,
		const char *	delims
	)

Splits the given std::string to a vector of T, based on the delimiters.

Parameters

s	String to split.
delims	List of delimiters to split the string with.

Returns: An std::vector of the tokens or an empty std::vector if an error occurred.

◆ make_flat_tree()

template<typename IntType , typename Size >

std::tuple<IntType, IntType, decltype(boost::irange(std::declval<IntType>), std::declval<IntType>)))> stapl::runtime::make_flat_tree	(	IntType	myid,
		Size	n
	)

Returns the root, parent and children ids for the part of a flat tree that myid belongs to.

Template Parameters

IntType Integral type.

Parameters

myid	Id for which the part of the tree will be generated.
n	Total number of ids.

Returns: A tuple with the root, parent and children ids as a range.

◆ make_binary_tree()

template<typename IntType , typename Size >

std::tuple<IntType, IntType, decltype(boost::irange(std::declval<IntType>), std::declval<IntType>)))> stapl::runtime::make_binary_tree	(	IntType	myid,
		Size	n
	)

Returns the root, parent and children ids for the part of a binary tree that myid belongs to.

Template Parameters

IntType Integral type.

Parameters

myid	Id for which the part of the tree will be generated.
n	Total number of ids.

Returns: A tuple with the root, parent and children ids.

◆ make_binomial_tree()

template<typename IntType , typename Size >

std::tuple<IntType, IntType, boost::iterator_range<binomial_tree_iterator<IntType, Size> > > stapl::runtime::make_binomial_tree	(	IntType	myid,
		Size	n
	)

Returns the root, parent and children ids for the part of a binomial tree that myid belongs to.

Template Parameters

IntType Integral type.

Parameters

myid	Id for which the part of the tree will be generated.
n	Total number of ids.

Returns: A tuple with the root, parent and children ids.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ STAPL_RUNTIME_CHECK

◆ STAPL_RUNTIME_ASSERT

◆ STAPL_RUNTIME_ASSERT_MSG

◆ STAPL_USE_MANAGED_ALLOC

Function Documentation

◆ normalize_size()

◆ retrieve_object()

◆ try_retrieve_object()

◆ find_index()

◆ integral_ceil_log2()

◆ make_vector() [1/3]

◆ make_vector() [2/3]

◆ make_vector() [3/3]

◆ intrusive_ptr_add_ref()

◆ intrusive_ptr_release()

◆ split_string_to_vector()

◆ make_flat_tree()

◆ make_binary_tree()

◆ make_binomial_tree()