Public Member Functions
void	make_main_thread ()
	Make the calling thread the effective main thread from the thread pool perspective.

GAIA_NODISCARD uint32_t	workers () const
	Returns the number of frame worker threads.

GAIA_NODISCARD uint32_t	background_workers () const
	Returns the number of background worker threads.

void	set_max_workers (uint32_t count, uint32_t countHighPrio)
	Set the maximum number of frame execution contexts for this system.

void	set_workers_high_prio_inter (uint32_t &workerIdx, uint32_t count)
	Updates the number of worker threads participating at high priority workloads.

void	set_workers_low_prio_inter (uint32_t &workerIdx, uint32_t count)
	Updates the number of worker threads participating at low priority workloads.

void	set_workers_high_prio (uint32_t count)
	Updates the number of worker threads participating at high priority workloads.

void	set_workers_low_prio (uint32_t count)
	Updates the number of worker threads participating at low priority workloads.

void	set_background_workers (uint32_t count)
	Updates the number of worker threads dedicated to background jobs. Background workers run jobs submitted through sched_background() and are not used by update(). They share the MaxWorkers limit with frame workers.

void	dep (JobHandle jobFirst, JobHandle jobSecond)
	Makes jobSecond depend on jobFirst. This means jobSecond will not run until jobFirst finishes.

void	dep (std::span< JobHandle > jobsFirst, JobHandle jobSecond)
	Makes jobSecond depend on the jobs listed in jobsFirst. This means jobSecond will not run until all jobs from jobsFirst finish.

void	dep_refresh (JobHandle jobFirst, JobHandle jobSecond)
	Makes jobSecond depend on jobFirst. This means jobSecond will not run until jobFirst finishes.

void	dep_refresh (std::span< JobHandle > jobsFirst, JobHandle jobSecond)
	Makes jobSecond depend on the jobs listed in jobsFirst. This means jobSecond will not run until all jobs from jobsFirst finish.

template<typename TJob >
JobHandle	add (TJob job)
	Creates a threadpool job from job.

void	del (JobHandle jobHandle)
	Deletes a job handle jobHandle from the threadpool.

void	submit (std::span< JobHandle > jobHandles)
	Pushes jobHandles into the internal queue so worker threads can pick them up and execute them. If there are more jobs than the queue can handle it puts the calling thread to sleep until workers consume enough jobs.

void	submit (JobHandle jobHandle)
	Pushes jobHandle into the internal queue so worker threads can pick it up and execute it. If there are more jobs than the queue can handle it puts the calling thread to sleep until workers consume enough jobs.

void	reset_state (std::span< JobHandle > jobHandles)

void	reset_state (JobHandle jobHandle)

void	reset (std::span< JobHandle > jobHandles)
	Waits for jobHandles to finish and resets them to a reusable state.

void	reset (JobHandle jobHandle)
	Waits for jobHandle to finish and resets it to a reusable state.

JobHandle	sched (Job job)
	Schedules a job to run on a worker thread.

JobHandle	sched_background (Job job)
	Schedules a job to run on background workers. Background jobs are not drained by update() and may span multiple frames. If no background workers are configured, wait() is the explicit fallback path that can execute queued background work on the calling thread.

JobHandle	sched (Job job, JobHandle dependsOn)
	Schedules a job to run on a worker thread.

JobHandle	sched_par (JobParallel job, uint32_t itemsToProcess, uint32_t groupSize)
	Schedules a job to run on worker threads in parallel.

JobHandle	sched_par (JobParallelRef job, uint32_t itemsToProcess, uint32_t groupSize)
	Schedules a non-owning parallel job descriptor on worker threads.

void	wait (JobHandle jobHandle)
	Wait until a job associated with the jobHandle finishes executing. Cleans up any job allocations and dependencies associated with jobHandle. The calling thread participates in frame job processing until jobHandle is done. For background jobs, the calling thread only runs background work when no background workers are configured.

void	update ()
	Uses the main thread to help with frame job processing. Background jobs are intentionally excluded from update().

Static Public Member Functions
static ThreadPool &	get ()

static GAIA_NODISCARD uint32_t	hw_thread_cnt ()
	Returns the number of HW threads available on the system. 1 is minimum.

static GAIA_NODISCARD uint32_t	hw_efficiency_cores_cnt ()
	Returns the number of efficiency cores of the system.

Friends
class	JobManager

Member Function Documentation

◆ add()

template<typename TJob >

JobHandle gaia::mt::ThreadPool::add ( TJob job )

inline

Creates a threadpool job from job.

Warning: Must be used from the main thread.; Frame jobs should be created before frame work is submitted. It is valid to create new frame jobs while unrelated background jobs are running.

Returns: Job handle of the scheduled job.

◆ del()

void gaia::mt::ThreadPool::del ( JobHandle jobHandle )

inline

Deletes a job handle jobHandle from the threadpool.

Warning: Job handle must not be used by any worker thread and can not be used by any active job handles as a dependency.

◆ dep() [1/2]

void gaia::mt::ThreadPool::dep	(	JobHandle	jobFirst,
		JobHandle	jobSecond
	)

inline

Makes jobSecond depend on jobFirst. This means jobSecond will not run until jobFirst finishes.

Parameters

jobFirst	The job that must complete first.
jobSecond	The job that will run after jobFirst.

Warning: This must be called before any of the listed jobs are scheduled.

◆ dep() [2/2]

void gaia::mt::ThreadPool::dep	(	std::span< JobHandle >	jobsFirst,
		JobHandle	jobSecond
	)

inline

Makes jobSecond depend on the jobs listed in jobsFirst. This means jobSecond will not run until all jobs from jobsFirst finish.

Parameters

jobsFirst	Jobs that must complete first.
jobSecond	The job that will run after jobsFirst.

Warning: This must must to be called before any of the listed jobs are scheduled.

◆ dep_refresh() [1/2]

void gaia::mt::ThreadPool::dep_refresh	(	JobHandle	jobFirst,
		JobHandle	jobSecond
	)

inline

Makes jobSecond depend on jobFirst. This means jobSecond will not run until jobFirst finishes.

Parameters

jobFirst	The job that must complete first.
jobSecond	The job that will run after jobFirst.

Note: Unlike dep() this function needs to be called when job handles are reused.

Warning: This must be called before any of the listed jobs are scheduled.; This must be called from the main thread.

◆ dep_refresh() [2/2]

void gaia::mt::ThreadPool::dep_refresh	(	std::span< JobHandle >	jobsFirst,
		JobHandle	jobSecond
	)

inline

Makes jobSecond depend on the jobs listed in jobsFirst. This means jobSecond will not run until all jobs from jobsFirst finish.

Parameters

jobsFirst	Jobs that must complete first.
jobSecond	The job that will run after jobsFirst.

Note: Unlike dep() this function needs to be called when job handles are reused.

Warning: This must be called before any of the listed jobs are scheduled.; This must be called from the main thread.

◆ hw_efficiency_cores_cnt()

static GAIA_NODISCARD uint32_t gaia::mt::ThreadPool::hw_efficiency_cores_cnt ( )

inlinestatic

Returns the number of efficiency cores of the system.

Returns: The number of efficiency cores. 0 if failed, or if there are no such cores.

◆ hw_thread_cnt()

static GAIA_NODISCARD uint32_t gaia::mt::ThreadPool::hw_thread_cnt ( )

inlinestatic

Returns the number of HW threads available on the system. 1 is minimum.

Returns: The number of hardware threads or 1 if failed.

◆ reset()

void gaia::mt::ThreadPool::reset ( std::span< JobHandle > jobHandles )

inline

Waits for jobHandles to finish and resets them to a reusable state.

Warning: Handles that were auto-deleted (non-manual jobs) are skipped.

◆ sched() [1/2]

JobHandle gaia::mt::ThreadPool::sched ( Job job )

inline

Schedules a job to run on a worker thread.

Parameters

job	Job descriptor

Warning: Must be used from the main thread.; Dependencies can't be modified for this job.

Returns: Job handle of the scheduled job.

◆ sched() [2/2]

JobHandle gaia::mt::ThreadPool::sched	(	Job	job,
		JobHandle	dependsOn
	)

inline

Schedules a job to run on a worker thread.

Parameters

job	Job descriptor
dependsOn	Job we depend on

Warning: Must be used from the main thread.; Dependencies can't be modified for this job.

Returns: Job handle of the scheduled job.

◆ sched_background()

JobHandle gaia::mt::ThreadPool::sched_background ( Job job )

inline

Schedules a job to run on background workers. Background jobs are not drained by update() and may span multiple frames. If no background workers are configured, wait() is the explicit fallback path that can execute queued background work on the calling thread.

Parameters

job	Job descriptor.

Warning: Must be used from the main thread.; Dependencies can't be modified for this job.

Returns: Job handle of the scheduled background job.

◆ sched_par() [1/2]

JobHandle gaia::mt::ThreadPool::sched_par	(	JobParallel	job,
		uint32_t	itemsToProcess,
		uint32_t	groupSize
	)

inline

Schedules a job to run on worker threads in parallel.

Parameters

job	Job descriptor
itemsToProcess	Total number of work items
groupSize	Group size per created job. If zero the threadpool decides the group size.

Warning: Must be used from the main thread.; Dependencies can't be modified for this job.

Returns: Job handle of the scheduled batch of jobs.

◆ sched_par() [2/2]

JobHandle gaia::mt::ThreadPool::sched_par	(	JobParallelRef	job,
		uint32_t	itemsToProcess,
		uint32_t	groupSize
	)

inline

Schedules a non-owning parallel job descriptor on worker threads.

Parameters

job	Non-owning job descriptor.
itemsToProcess	Total number of work items.
groupSize	Group size per created job. If zero the threadpool decides the group size.

Warning: Must be used from the main thread.; The pointed-to context must remain alive until the returned handle completes.

Returns: Job handle of the scheduled batch of jobs.

◆ set_background_workers()

void gaia::mt::ThreadPool::set_background_workers ( uint32_t count )

inline

Updates the number of worker threads dedicated to background jobs. Background workers run jobs submitted through sched_background() and are not used by update(). They share the MaxWorkers limit with frame workers.

Parameters

count Requested number of background worker threads.

Warning: All jobs are finished first before threads are recreated.

◆ set_max_workers()

void gaia::mt::ThreadPool::set_max_workers	(	uint32_t	count,
		uint32_t	countHighPrio
	)

inline

Set the maximum number of frame execution contexts for this system.

Parameters

count	Requested frame execution contexts, including the main thread. The number of spawned frame worker threads is one less.
countHighPrio	Number of high-priority frame execution contexts. Values larger than count are clamped.

Warning: All jobs are finished first before threads are recreated.

◆ set_workers_high_prio()

void gaia::mt::ThreadPool::set_workers_high_prio ( uint32_t count )

inline

Updates the number of worker threads participating at high priority workloads.

Warning: All jobs are finished first before threads are recreated.

◆ set_workers_high_prio_inter()

void gaia::mt::ThreadPool::set_workers_high_prio_inter	(	uint32_t &	workerIdx,
		uint32_t	count
	)

inline

Updates the number of worker threads participating at high priority workloads.

Parameters

[out]	workerIdx	Number of high priority workers.
	count	Requested number of high priority workers.

Warning: All jobs are finished first before threads are recreated.

◆ set_workers_low_prio()

void gaia::mt::ThreadPool::set_workers_low_prio ( uint32_t count )

inline

Updates the number of worker threads participating at low priority workloads.

Warning: All jobs are finished first before threads are recreated.

◆ set_workers_low_prio_inter()

void gaia::mt::ThreadPool::set_workers_low_prio_inter	(	uint32_t &	workerIdx,
		uint32_t	count
	)

inline

Updates the number of worker threads participating at low priority workloads.

Parameters

[out]	workerIdx	Number of low priority workers.
	count	Requested number of low priority workers.

Warning: All jobs are finished first before threads are recreated.

◆ submit() [1/2]

void gaia::mt::ThreadPool::submit ( JobHandle jobHandle )

inline

Pushes jobHandle into the internal queue so worker threads can pick it up and execute it. If there are more jobs than the queue can handle it puts the calling thread to sleep until workers consume enough jobs.

Warning: Once submitted, dependencies can't be modified for this job.

◆ submit() [2/2]

void gaia::mt::ThreadPool::submit ( std::span< JobHandle > jobHandles )

inline

Pushes jobHandles into the internal queue so worker threads can pick them up and execute them. If there are more jobs than the queue can handle it puts the calling thread to sleep until workers consume enough jobs.

Warning: Once submitted, dependencies can't be modified for this job.

◆ wait()

void gaia::mt::ThreadPool::wait ( JobHandle jobHandle )

inline

Wait until a job associated with the jobHandle finishes executing. Cleans up any job allocations and dependencies associated with jobHandle. The calling thread participates in frame job processing until jobHandle is done. For background jobs, the calling thread only runs background work when no background workers are configured.

Parameters

jobHandle Job handle to wait for

The documentation for this class was generated from the following file:

/home/runner/work/gaia-ecs/gaia-ecs/include/gaia/mt/threadpool.h

Public Member Functions

Static Public Member Functions

Friends

Member Function Documentation

◆ add()

◆ del()

◆ dep() [1/2]

◆ dep() [2/2]

◆ dep_refresh() [1/2]

◆ dep_refresh() [2/2]

◆ hw_efficiency_cores_cnt()

◆ hw_thread_cnt()

◆ reset()

◆ sched() [1/2]

◆ sched() [2/2]

◆ sched_background()

◆ sched_par() [1/2]

◆ sched_par() [2/2]

◆ set_background_workers()

◆ set_max_workers()

◆ set_workers_high_prio()

◆ set_workers_high_prio_inter()

◆ set_workers_low_prio()

◆ set_workers_low_prio_inter()

◆ submit() [1/2]

◆ submit() [2/2]

◆ wait()