Lock-free atomic primitives and implementations of data structures. More...

Namespaces
namespace	Ranges
	STL Ranges extensions.

namespace	Views
	STL Views extensions.

Classes
class	Allocator
	General Purpose Allocator (GPA) interface. More...

class	AllocatorHeap
	General purpose heap allocator. More...

class	AllocatorStack
	Implements a lock-free stack-based bump allocator. More...

struct	Arena
	A memory arena allocated from an Allocator. More...

class	AtomicPool
	Atomic, bounded object pool of fixed allocation sizes. Being a sibling to AtomicStack - key differences being how objects are allocated in a fixed-size arena and is never freed back to the system. Deallocation returns objects to the pool for reuse. That - and you get stable pointers to objects directly. More...

class	AtomicStack
	Atomic, unbounded LIFO stack with lock-free push and pop operations. More...

struct	BitmaskEnumWrapper
	Wrapper for bitmask enum types that provides bitwise operators. More...

class	MPMCQueue
	Atomic, bounded multi-producer multi-consumer FIFO ring buffer with a fixed maximum size. More...

struct	ScopedArena
	RAII wrapper for an arena allocated from an Allocator. More...

class	SPSCQueue
	Atomic, bounded single-producer single-consumer FIFO ring buffer with a fixed maximum size. More...

struct	StackArena
	A fixed-size stack memory arena. More...

struct	StlAllocator
	`std::allocator` adaptor for Foundation::Core::Allocator More...

struct	StlDeleter
	Custom deleter for Foundation::Core::UniquePtr and Foundation::Core::SharedPtr that uses a Foundation::Core::Allocator to deallocate memory. More...

class	ThreadPool
	Atomic, lock-free Thread Pool implementation with fixed bounds. More...

struct	ThreadPoolJob
	Job interface for use with ThreadPool. More...

struct	ThreadPoolLambdaJob
	State-carrying lambda job for use with ThreadPool. More...

struct	Variant
	Extended std::variant with C++23 visit() behavior and convenience Get()/GetIf() methods. More...

Typedefs
using	size_type = std::size_t

using	pointer = void *

template<typename T , typename Deleter = StlDeleter<T>>
using	UniquePtr = std::unique_ptr< T, Deleter >
	`std::unique_ptr` with custom deleter that uses a Foundation::Core::Allocator to deallocate memory.

template<typename T >
using	SharedPtr = std::shared_ptr< T >
	`std::shared_ptr` with custom deleter that uses a Foundation::Core::Allocator to deallocate memory.

template<typename T >
using	Atomic = std::atomic< T >
	Alias of `std::atomic<T>`.

template<typename T >
using	Optional = std::optional< T >
	Alias for `std::optional`

template<typename First , typename Second >
using	Pair = std::pair< First, Second >
	Alias for `std::pair`

template<typename ... Args>
using	Tuple = std::tuple< Args... >
	Alias for `std::tuple`

template<typename T , size_t Size>
using	Array = std::array< T, Size >
	Alias for `std::array`

template<size_t Size>
using	Bitset = std::bitset< Size >
	Alias for `std::bitset`

using	StringView = std::basic_string_view< char >
	Alias for `std::basic_string_view<char>`

template<typename T >
using	Span = std::span< T >
	Alias for `std::span`

using	String = std::basic_string< char >
	Alias for `std::basic_string<char>`, without an explicit allocator constructor.

using	StringAlloc = std::basic_string< char, std::char_traits< char >, StlAllocator< char > >
	`std::basic_string<char>` with explicit Foundation::Core::StlAllocator constructor

template<typename T >
using	Vector = std::vector< T, StlAllocator< T > >
	`std::vector` with explicit Foundation::Core::StlAllocator constructor

template<typename T , typename Predicate = std::less<T>>
using	Set = std::set< T, Predicate, StlAllocator< T > >
	`std::set` with explicit Foundation::Core::StlAllocator constructor

template<typename T , typename Predicate = std::less<T>>
using	MultiSet = std::multiset< T, Predicate, StlAllocator< T > >
	`std::multiset` with explicit Foundation::Core::StlAllocator constructor

template<typename K , typename V , typename Predicate = std::less<K>>
using	Map = std::map< K, V, Predicate, StlAllocator< Pair< const K, V > > >
	`std::map` with explicit Foundation::Core::StlAllocator constructor

template<typename K , typename V , typename Predicate = std::less<K>>
using	MultiMap = std::multimap< K, V, Predicate, StlAllocator< Pair< const K, V > > >
	`std::multimap` with explicit Foundation::Core::StlAllocator constructor

template<typename T >
using	Deque = std::deque< T, StlAllocator< T > >
	`std::deque` with explicit Foundation::Core::StlAllocator constructor

template<typename T >
using	List = std::list< T, StlAllocator< T > >
	`std::list` with explicit Foundation::Core::StlAllocator constructor

template<typename T , typename Container = Deque<T>>
using	Queue = std::queue< T, Container >
	`std::queue` with explicit Foundation::Core::StlAllocator constructor

template<typename T , typename Predicate = std::less<T>, typename Container = Vector<T>>
using	PriorityQueue = std::priority_queue< T, Container, Predicate >
	`std::priority_queue` with explicit Foundation::Core::StlAllocator constructor

template<typename T = void>
using	Promise = std::promise< T >

template<typename T = void>
using	Future = std::future< T >

using	CondVar = std::condition_variable

using	Mutex = std::mutex

using	Thread = std::jthread
	Alias of std::jthread.

using	JobQueue = MPMCQueue< UniquePtr< ThreadPoolJob > >
	Backing job queue type for ThreadPool.

Functions
constexpr uintptr_t	AlignUp (const uintptr_t value, const uintptr_t alignment)

constexpr uintptr_t	AlignDown (const uintptr_t value, const uintptr_t alignment)

template<typename Base , typename Derived , typename ... Args>
Base *	ConstructBase (Allocator *resource, Args &&...args)
	Placement new helper for constructing an object of type Derived (which can be a subclass of Base) using a Foundation::Core::Allocator.

template<typename T , typename ... Args>
T *	Construct (Allocator *resource, Args &&...args)
	Convenience placement new with object of type T using a Foundation::Core::Allocator.

template<typename T >
void	Destruct (Allocator resource, T obj)
	Convenience destructor for objects allocated with Construct or ConstructBase.

template<typename Base , typename Derived , typename ... Args>
UniquePtr< Base >	ConstructUniqueBase (Allocator *resource, Args &&...args)
	Helper function for constructing a pinned resource with a Foundation::Core::Allocator.

template<typename T , typename ... Args>
UniquePtr< T >	ConstructUnique (Allocator *resource, Args &&...args)
	Convenience wrapper for calling ConstructUniqueBase when Base and Derived are the same type.

template<typename Base , typename Derived , typename ... Args>
SharedPtr< Base >	ConstructSharedBase (Allocator *resource, Args &&...args)
	Helper function for constructing a ref-counted resource with a Foundation::Core::Allocator.

template<typename T , typename ... Args>
SharedPtr< T >	ConstructShared (Allocator *resource, Args &&...args)
	Convenience wrapper for calling ConstructSharedBase when Base and Derived are the same type.

Allocator *	getGlobalAllocator ()

template<typename T >
Span< const char >	AsBytes (Span< T > data)

template<typename T > requires std::is_trivially_copyable_v<T>
Span< const T >	AsSpan (T const &data)
	Helper to construct one const r-value as a single element span.

template<typename T , typename ... Args>
Span< T >	ConstructSpan (Allocator *resource, size_t size, Args &&...args)
	Convenience function for constructing a Span with memory allocated from a Foundation::Core::Allocator. Possibly constructs objects in-place if they are not trivially constructible (e.g. non-PODs)

template<typename T >
void	DestructSpan (Allocator *resource, Span< T > span)
	Convenience function for destructing a Span allocated with ConstructSpan. Calls destructors in-place if the type is not trivially destructible (e.g. non-PODs)

Variables
constexpr size_t	kDefaultStackArenaSize = 12 * 1024

Detailed Description

Lock-free atomic primitives and implementations of data structures.

Note

References:

Dmitry Vyukov's blog on lock-free algorithms and data structures
- https://www.1024cores.net/home/lock-free-algorithms/introduction
CppCon 2014: Herb Sutter "Lock-Free Programming (or, Juggling Razor Blades), Part I"
- https://www.youtube.com/watch?v=c1gO9aB9nbs
Single Producer Single Consumer Lock-free FIFO From the Ground Up - Charles Frasch - CppCon 2023
- https://www.youtube.com/watch?v=K3P_Lmq6pw0
Djordje Nedic's lockfree
- https://github.com/DNedic/lockfree
std::memory_order on cppreference
- https://en.cppreference.com/w/cpp/atomic/memory_order.html
Tracy Profiler's various lockfree implementations
- https://github.com/wolfpld/tracy/blob/master/public/client/tracy_concurrentqueue.h
SO answer on tagged pointers for ABA problem
- https://stackoverflow.com/a/38991835

Typedef Documentation

◆ Array

template<typename T , size_t Size>

using Foundation::Core::Array = typedef std::array<T, Size>

Alias for std::array

◆ Atomic

template<typename T >

using Foundation::Core::Atomic = typedef std::atomic<T>

Alias of std::atomic<T>.

◆ Bitset

template<size_t Size>

using Foundation::Core::Bitset = typedef std::bitset<Size>

Alias for std::bitset

◆ CondVar

using Foundation::Core::CondVar = typedef std::condition_variable

◆ Deque

template<typename T >

using Foundation::Core::Deque = typedef std::deque<T, StlAllocator<T> >

std::deque with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ Future

template<typename T = void>

using Foundation::Core::Future = typedef std::future<T>

◆ JobQueue

using Foundation::Core::JobQueue = typedef MPMCQueue<UniquePtr<ThreadPoolJob> >

Backing job queue type for ThreadPool.

◆ List

template<typename T >

using Foundation::Core::List = typedef std::list<T, StlAllocator<T> >

std::list with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ Map

template<typename K , typename V , typename Predicate = std::less<K>>

using Foundation::Core::Map = typedef std::map<K, V, Predicate, StlAllocator<Pair<const K, V> >>

std::map with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ MultiMap

template<typename K , typename V , typename Predicate = std::less<K>>

using Foundation::Core::MultiMap = typedef std::multimap<K, V, Predicate, StlAllocator<Pair<const K, V> >>

std::multimap with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ MultiSet

template<typename T , typename Predicate = std::less<T>>

using Foundation::Core::MultiSet = typedef std::multiset<T, Predicate, StlAllocator<T> >

std::multiset with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ Mutex

using Foundation::Core::Mutex = typedef std::mutex

◆ Optional

template<typename T >

using Foundation::Core::Optional = typedef std::optional<T>

Alias for std::optional

◆ Pair

template<typename First , typename Second >

using Foundation::Core::Pair = typedef std::pair<First, Second>

Alias for std::pair

◆ pointer

using Foundation::Core::pointer = typedef void*

◆ PriorityQueue

template<typename T , typename Predicate = std::less<T>, typename Container = Vector<T>>

using Foundation::Core::PriorityQueue = typedef std::priority_queue<T, Container, Predicate>

std::priority_queue with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ Promise

template<typename T = void>

using Foundation::Core::Promise = typedef std::promise<T>

◆ Queue

template<typename T , typename Container = Deque<T>>

using Foundation::Core::Queue = typedef std::queue<T, Container>

std::queue with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ Set

template<typename T , typename Predicate = std::less<T>>

using Foundation::Core::Set = typedef std::set<T, Predicate, StlAllocator<T> >

std::set with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ SharedPtr

template<typename T >

using Foundation::Core::SharedPtr = typedef std::shared_ptr<T>

std::shared_ptr with custom deleter that uses a Foundation::Core::Allocator to deallocate memory.

◆ size_type

using Foundation::Core::size_type = typedef std::size_t

◆ Span

template<typename T >

using Foundation::Core::Span = typedef std::span<T>

Alias for std::span

◆ String

using Foundation::Core::String = typedef std::basic_string<char>

Alias for std::basic_string<char>, without an explicit allocator constructor.

Allocation of strings on heap is done with the default global allocator.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ StringAlloc

using Foundation::Core::StringAlloc = typedef std::basic_string<char, std::char_traits<char>, StlAllocator<char> >

std::basic_string<char> with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

◆ StringView

using Foundation::Core::StringView = typedef std::basic_string_view<char>

Alias for std::basic_string_view<char>

◆ Thread

using Foundation::Core::Thread = typedef std::jthread

Alias of std::jthread.

Note: Thread is joinable by default, and will be joined in the destructor.

◆ Tuple

template<typename ... Args>

using Foundation::Core::Tuple = typedef std::tuple<Args...>

Alias for std::tuple

◆ UniquePtr

template<typename T , typename Deleter = StlDeleter<T>>

using Foundation::Core::UniquePtr = typedef std::unique_ptr<T, Deleter>

std::unique_ptr with custom deleter that uses a Foundation::Core::Allocator to deallocate memory.

Construction without a Foundation::Core::Allocator pointer is disallowed, and will result in a compile-time error.

◆ Vector

template<typename T >

using Foundation::Core::Vector = typedef std::vector<T, StlAllocator<T> >

std::vector with explicit Foundation::Core::StlAllocator constructor

Construction without an allocator is disallowed, and will result in a compile-time error.

Note: Thread-safety is not guaranteed as with other STL containers.

Function Documentation

◆ AlignDown()

constexpr uintptr_t Foundation::Core::AlignDown	(	const uintptr_t	value,
		const uintptr_t	alignment
	)

constexpr

◆ AlignUp()

constexpr uintptr_t Foundation::Core::AlignUp	(	const uintptr_t	value,
		const uintptr_t	alignment
	)

constexpr

◆ AsBytes()

template<typename T >

Span< const char > Foundation::Core::AsBytes ( Span< T > data )

◆ AsSpan()

template<typename T >
requires std::is_trivially_copyable_v<T>

Span< const T > Foundation::Core::AsSpan ( T const & data )

Helper to construct one const r-value as a single element span.

◆ Construct()

template<typename T , typename ... Args>

T * Foundation::Core::Construct	(	Allocator *	resource,
		Args &&...	args
	)

Convenience placement new with object of type T using a Foundation::Core::Allocator.

Note: Using delete, delete[] on the returned pointer is undefined behaviour. Destruct should ALWAYS be used for such purposes.

◆ ConstructBase()

template<typename Base , typename Derived , typename ... Args>

Base * Foundation::Core::ConstructBase	(	Allocator *	resource,
		Args &&...	args
	)

Placement new helper for constructing an object of type Derived (which can be a subclass of Base) using a Foundation::Core::Allocator.

Note: Using delete, delete[] on the returned pointer is undefined behaviour. Destruct should ALWAYS be used for such purposes.

◆ ConstructShared()

template<typename T , typename ... Args>

SharedPtr< T > Foundation::Core::ConstructShared	(	Allocator *	resource,
		Args &&...	args
	)

Convenience wrapper for calling ConstructSharedBase when Base and Derived are the same type.

Template Parameters

T	is the class type to be templated on.

◆ ConstructSharedBase()

template<typename Base , typename Derived , typename ... Args>

SharedPtr< Base > Foundation::Core::ConstructSharedBase	(	Allocator *	resource,
		Args &&...	args
	)

Helper function for constructing a ref-counted resource with a Foundation::Core::Allocator.

Template Parameters

Base	is the base class type be templated on.
Derived	can be a subclass of Base, with destruction handled correctly.

◆ ConstructSpan()

template<typename T , typename ... Args>

Span< T > Foundation::Core::ConstructSpan	(	Allocator *	resource,
		size_t	size,
		Args &&...	args
	)

Convenience function for constructing a Span with memory allocated from a Foundation::Core::Allocator. Possibly constructs objects in-place if they are not trivially constructible (e.g. non-PODs)

Note: Data is not guaranteed to be zero-initialized. Pass in constructor args if needed.; Constructor args are only used if T is not trivially constructible, or if more than 0 args are passed in.

◆ ConstructUnique()

template<typename T , typename ... Args>

UniquePtr< T > Foundation::Core::ConstructUnique	(	Allocator *	resource,
		Args &&...	args
	)

Convenience wrapper for calling ConstructUniqueBase when Base and Derived are the same type.

Template Parameters

T	is the class type to be templated on.

◆ ConstructUniqueBase()

template<typename Base , typename Derived , typename ... Args>

UniquePtr< Base > Foundation::Core::ConstructUniqueBase	(	Allocator *	resource,
		Args &&...	args
	)

Helper function for constructing a pinned resource with a Foundation::Core::Allocator.

Template Parameters

Base	is the base class type be templated on.
Derived	can be a subclass of Base, with destruction handled correctly.

◆ Destruct()

template<typename T >

void Foundation::Core::Destruct	(	Allocator *	resource,
		T *	obj
	)

Convenience destructor for objects allocated with Construct or ConstructBase.

◆ DestructSpan()

template<typename T >

void Foundation::Core::DestructSpan	(	Allocator *	resource,
		Span< T >	span
	)

Convenience function for destructing a Span allocated with ConstructSpan. Calls destructors in-place if the type is not trivially destructible (e.g. non-PODs)

◆ getGlobalAllocator()

Allocator * Foundation::Core::getGlobalAllocator ( )

extern

Implemented by AllocatorHeap

Variable Documentation

◆ kDefaultStackArenaSize

constexpr size_t Foundation::Core::kDefaultStackArenaSize = 12 * 1024

constexpr

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ Array

◆ Atomic

◆ Bitset

◆ CondVar

◆ Deque

◆ Future

◆ JobQueue

◆ List

◆ Map

◆ MultiMap

◆ MultiSet

◆ Mutex

◆ Optional

◆ Pair

◆ pointer

◆ PriorityQueue

◆ Promise

◆ Queue

◆ Set

◆ SharedPtr

◆ size_type

◆ Span

◆ String

◆ StringAlloc

◆ StringView

◆ Thread

◆ Tuple

◆ UniquePtr

◆ Vector

Function Documentation

◆ AlignDown()

◆ AlignUp()

◆ AsBytes()

◆ AsSpan()

◆ Construct()

◆ ConstructBase()

◆ ConstructShared()

◆ ConstructSharedBase()

◆ ConstructSpan()

◆ ConstructUnique()

◆ ConstructUniqueBase()

◆ Destruct()

◆ DestructSpan()

◆ getGlobalAllocator()

Variable Documentation

◆ kDefaultStackArenaSize