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	DynamicPool
	Mutex-protected, dynamically sized object pool with stable object pointers. More...

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

class	JobGraph
	A small, transient CPU job graph layered on top of ThreadPool. More...

struct	JobHandle
	Opaque handle to a node in a JobGraph. Returned by the `Add*` builders and passed to JobGraph::DependsOn / JobGraph::Wait. More...

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

class	MemoryMappedFile

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

struct	ParallelForAsyncJob
	One worker of a ParallelForAsyncState: drains the shared cursor and, when it is the last running worker, satisfies the promise and frees the shared state. More...

struct	ParallelForAsyncState
	Heap-resident shared state for a non-blocking ThreadPool::ParallelForAsync. More...

struct	ParallelForJob
	Self-draining for-loop job used by ThreadPool::ParallelFor. 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	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< Job > >
	Backing job queue type for ThreadPool.

using	JobQueues = std::array< JobQueue, kJobPriorityCount >

Enumerations
enum class	MemoryMappedAccess { ReadOnly , ReadWrite }

enum class	JobPriority : size_t { Low , Normal , High }

enum class	ExecutionPolicy { Seq , Par }
	Runtime execution policy for ThreadPool::ParallelFor, mirroring std::execution's seq/par — but chosen at runtime, so a caller can downgrade to serial with a one-argument change (debugging, determinism, or tiny workloads) instead of a compile-time switch. More...

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 >
T	InterlockedMin (Atomic< T > &atomic, T value, std::memory_order order=std::memory_order_seq_cst)

template<typename T >
T	InterlockedMax (Atomic< T > &atomic, T value, std::memory_order order=std::memory_order_seq_cst)

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)

void	PathsInit (const char *argv0)

void	PathsInitFromDir (const char *exeDir)

String	PathsResolve (StringView relPath)

template<typename Fn , typename Arg >
void	ParallelForInvoke (Fn &fn, Arg &&arg, size_t workerId)
	Invokes a ThreadPool::ParallelFor body for one item, passing the worker id only if the functor accepts it. `arg` is the index (index form) or the dereferenced element (iterator form), so callers may write `fn(x)` or `fn(x, workerId)` as they like.

Variables
constexpr size_t	kDefaultStackArenaSize = 12 * 1024

static std::filesystem::path	sExeDir

constexpr size_t	kJobPriorityCount = static_cast<size_t>(JobPriority::High) + 1

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<Job> >

Backing job queue type for ThreadPool.

◆ JobQueues

using Foundation::Core::JobQueues = typedef std::array<JobQueue, kJobPriorityCount>

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

Enumeration Type Documentation

◆ ExecutionPolicy

enum class Foundation::Core::ExecutionPolicy

strong

Runtime execution policy for ThreadPool::ParallelFor, mirroring std::execution's seq/par — but chosen at runtime, so a caller can downgrade to serial with a one-argument change (debugging, determinism, or tiny workloads) instead of a compile-time switch.

Enumerator
Seq
Par

◆ JobPriority

enum class Foundation::Core::JobPriority : size_t

strong

Enumerator
Low
Normal
High

◆ MemoryMappedAccess

enum class Foundation::Core::MemoryMappedAccess

strong

Enumerator
ReadOnly
ReadWrite

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

◆ InterlockedMax()

template<typename T >

T Foundation::Core::InterlockedMax	(	Atomic< T > &	atomic,
		T	value,
		std::memory_order	order = `std::memory_order_seq_cst`
	)

◆ InterlockedMin()

template<typename T >

T Foundation::Core::InterlockedMin	(	Atomic< T > &	atomic,
		T	value,
		std::memory_order	order = `std::memory_order_seq_cst`
	)

◆ ParallelForInvoke()

template<typename Fn , typename Arg >

void Foundation::Core::ParallelForInvoke	(	Fn &	fn,
		Arg &&	arg,
		size_t	workerId
	)

inline

Invokes a ThreadPool::ParallelFor body for one item, passing the worker id only if the functor accepts it. arg is the index (index form) or the dereferenced element (iterator form), so callers may write fn(x) or fn(x, workerId) as they like.

◆ PathsInit()

void Foundation::Core::PathsInit ( const char * argv0 )

◆ PathsInitFromDir()

void Foundation::Core::PathsInitFromDir ( const char * exeDir )

◆ PathsResolve()

String Foundation::Core::PathsResolve ( StringView relPath )

Variable Documentation

◆ kDefaultStackArenaSize

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

constexpr

◆ kJobPriorityCount

constexpr size_t Foundation::Core::kJobPriorityCount = static_cast<size_t>(JobPriority::High) + 1

inlineconstexpr

◆ sExeDir

std::filesystem::path Foundation::Core::sExeDir

static

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Array

◆ Atomic

◆ Bitset

◆ CondVar

◆ Deque

◆ Future

◆ JobQueue

◆ JobQueues

◆ List

◆ Map

◆ MultiMap

◆ MultiSet

◆ Mutex

◆ Optional

◆ Pair

◆ pointer

◆ PriorityQueue

◆ Promise

◆ Queue

◆ Set

◆ SharedPtr

◆ size_type

◆ Span

◆ String

◆ StringAlloc

◆ StringView

◆ Thread

◆ Tuple

◆ UniquePtr

◆ Vector

Enumeration Type Documentation

◆ ExecutionPolicy

◆ JobPriority

◆ MemoryMappedAccess

Function Documentation

◆ AlignDown()

◆ AlignUp()

◆ AsBytes()

◆ AsSpan()

◆ Construct()

◆ ConstructBase()

◆ ConstructShared()

◆ ConstructSharedBase()

◆ ConstructSpan()

◆ ConstructUnique()

◆ ConstructUniqueBase()

◆ Destruct()

◆ DestructSpan()

◆ getGlobalAllocator()

◆ InterlockedMax()

◆ InterlockedMin()

◆ ParallelForInvoke()

◆ PathsInit()

◆ PathsInitFromDir()

◆ PathsResolve()

Variable Documentation

◆ kDefaultStackArenaSize

◆ kJobPriorityCount

◆ sExeDir