API for a multi-threading job system. More...

#include <atomic>
#include <cstdint>
#include <new>
#include <utility>

Classes
struct	job::Counter
	The only syncronization mechanism. Allows you to wait on tasks you asssociated with this counter. More...

struct	job::Ctx

struct	job::JobSystemCreateOptions
	The runtime configuration for the Job System. More...

struct	job::JobSystemMemoryRequirements
	The memory requirements for a given configuration `JobSystemCreateOptions`. More...

struct	job::internal::PrivateCtx

struct	job::Splitter

Namespaces
namespace	job

namespace	job::internal

Macros
#define	JOB_SYS_ASSERTIONS 1
	Should be turned on during development as it catches API misuse, then for release switched off. More...

#define	JobAssert(expr, msg) (::job::internal::AssertHandler)((expr), __FILE__, __LINE__, msg)

Typedefs
using	job::WorkerID = std::uint16_t
	The id type of each worker thread. More...

using	job::internal::JobFn = void(*)(const PrivateCtx &ctx)

Enumerations
enum class	job::QueueMode : std::uint8_t { job::Default , job::WorkerOnly }
	Determines which threads the task will be allowed to run on. More...

Functions
std::size_t	job::NumSystemThreads () noexcept
	Makes system calls to grab the number threads / processors on the device. This function can be called by any thread concurrently. More...

void	job::Initialize (const JobSystemMemoryRequirements &memory_requirements={}, void *const memory=nullptr) noexcept
	Sets up the Job system and creates all the worker threads. The thread that calls 'job::Initialize' is considered the main thread. More...

const char *	job::ProcessorArchitectureName () noexcept
	An implementation defined name for the CPU architecture of the device. This function can be called by any thread concurrently. More...

std::uint16_t	job::NumWorkers () noexcept
	Returns the number of workers created by the system. This function can be called by any thread concurrently. More...

WorkerID	job::CurrentWorker () noexcept
	The current id of the current thread. This function can be called by any thread concurrently. More...

bool	job::IsMainThread () noexcept
	Allows for querying if we are currently executing in the main thread. More...

void	job::Shutdown () noexcept
	This will deallocate any memory used by the system and shutdown any threads created by 'bfjob::initialize'. More...

template<typename Closure >
void	job::Dispatch (const char const name, Counter const counter, const Closure &Callback, const QueueMode queue=QueueMode::Default) noexcept
	Main API entrypoint, Pushes a task onto the queue. More...

void	job::WaitOn (const Counter &counter) noexcept
	Blocks until all tasks associated with `counter` are done while This function will block but do work while being blocked. More...

void	job::PauseProcessor () noexcept
	CPU pause instruction to indicate when you are in a spin wait loop. More...

void	job::YieldTimeSlice () noexcept
	Asks the OS to yield this threads execution to another thread on the current cpu core. More...

void	job::internal::AssertHandler (const bool condition, const char const filename, const int line_number, const char const msg)

void	job::internal::DispatchImpl (const char const name, Counter const counter, const QueueMode queue, const JobFn func, const std::size_t user_data_size, const std::size_t user_data_alignment, const void const user_data, void(InitUserData)(void const user_data, const void const in_user_data)) noexcept

template<typename F , typename S >
void	job::ParallelFor (const char const name, Counter const counter, const std::size_t start, const std::size_t count, S &&splitter, F &&fn, const QueueMode queue=QueueMode::Default)
	Parallel for algorithm, splits the work up recursively splitting based on the `splitter` passed in. More...

template<typename T , typename F , typename S >
void	job::ParallelFor (const char const name, Counter const counter, T *const data, const std::size_t count, S &&splitter, F &&fn, const QueueMode queue=QueueMode::Default)

template<typename... F>
void	job::ParallelInvoke (const char const name, Counter const counter, const QueueMode queue, F &&... fns)
	Invokes each passed in function object in parallel. More...

template<typename Splitter , typename Reducer >
void	job::ParallelReduce (const char const name, Counter const counter, const std::size_t start, const std::size_t count, Splitter &&splitter, Reducer &&reduce, const QueueMode queue=QueueMode::Default)

Detailed Description

API for a multi-threading job system.

Author: Shareef Raheem (https://blufedora.github.io/)

References: [https://blog.molecular-matters.com/2015/08/24/job-system-2-0-lock-free-work-stealing-part-1-basics/] [https://manu343726.github.io/2017-03-13-lock-free-job-stealing-task-system-with-modern-c/] [https://github.com/cdwfs/cds_job/blob/master/cds_job.h] [https://github.com/cyshi/logbook/blob/master/src/common/work_stealing_queue.h] [https://fabiensanglard.net/doom3_bfg/threading.php] [https://gdcvault.com/play/1022186/Parallelizing-the-Naughty-Dog-Engine]

Copyright: Copyright (c) 2020-2026 Shareef Abdoul-Raheem

Definition in file job_api.hpp.

Class Documentation

◆ job::Counter

struct job::Counter

The only syncronization mechanism. Allows you to wait on tasks you asssociated with this counter.

See also: job::WaitOn

Definition at line 48 of file job_api.hpp.

Class Members
atomic_uint64_t	unfinished_tasks

◆ job::JobSystemCreateOptions

struct job::JobSystemCreateOptions

The runtime configuration for the Job System.

Definition at line 87 of file job_api.hpp.

Class Members
uint16_t	num_threads	Use 0 to indicate using the number of cores available on the system.
uint16_t	normal_queue_size	Number of tasks in each worker's `QueueType::Default` queue. (Must be power of two)
uint16_t	worker_queue_size	Number of tasks in each worker's `QueueType::WorkerOnly` queue. (Must be power of two)
uint64_t	job_steal_rng_seed	The RNG for work queue stealing will be seeded with this value.

Macro Definition Documentation

◆ JOB_SYS_ASSERTIONS

#define JOB_SYS_ASSERTIONS 1

Should be turned on during development as it catches API misuse, then for release switched off.

Definition at line 28 of file job_api.hpp.

◆ JobAssert

#define JobAssert	(	expr,
		msg
	)	(::job::internal::AssertHandler)((expr), __FILE__, __LINE__, msg)

Definition at line 32 of file job_api.hpp.

Classes

Namespaces

Macros

Typedefs

Enumerations