Storage and lifecycle manager for internal job and parallel callback records. More...

#include <jobmanager.h>

Public Member Functions
JobContainer &	data (JobHandle jobHandle)
	Returns mutable internal storage for jobHandle.

const JobContainer &	data (JobHandle jobHandle) const
	Returns immutable internal storage for jobHandle.

GAIA_NODISCARD JobHandle	alloc_job (Job job)
	Allocates a new job container identified by a unique JobHandle.

GAIA_NODISCARD ParallelCallbackHandle	alloc_parallel_callback (JobArgsFunc callback, uint32_t refs)
	Allocates a shared callback record used by parallel jobs.

void	free_job (JobHandle jobHandle)
	Invalidates jobHandle by resetting its index in the job pool. Every time a job is deallocated its generation is increased by one.

void	free_parallel_callback (ParallelCallbackHandle handle)
	Releases a shared callback record.

void	reset ()
	Resets the job pool.

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

GAIA_NODISCARD bool	is_clear (JobHandle jobHandle) const
	Checks whether the job referenced by jobHandle is in the clear state.

void	invoke_parallel_callback (ParallelCallbackHandle handle, const JobArgs &args)
	Invokes the shared callback referenced by handle.

GAIA_NODISCARD bool	release_parallel_callback_ref (ParallelCallbackHandle handle)
	Releases one reference to the callback referenced by handle.

Static Public Member Functions
static void	run (JobContainer &jobData)
	Execute the functor associated with the job container.

static bool	signal_edge (JobContainer &jobData)
	Signals that one dependency edge of jobData has completed.

static void	free_edges (JobContainer &jobData)
	Releases heap storage used for the dependency list of jobData.

static uint32_t	submit (JobContainer &jobData)
	Marks a job as submitted.

static void	processing (JobContainer &jobData)
	Marks a job as queued for worker processing.

static void	executing (JobContainer &jobData, uint32_t workerIdx)
	Marks a job as executing on the worker identified by workerIdx.

static void	finalize (JobContainer &jobData)
	Marks a job as finished.

static void	reset_state (JobContainer &jobData)
	Resets a completed or never-submitted job back to the clear state.

static GAIA_NODISCARD bool	is_clear (JobContainer &jobData)
	Checks whether jobData is in the clear state.

static GAIA_NODISCARD bool	submitted (const JobContainer &jobData)
	Checks whether jobData has been submitted but not yet queued for execution.

static GAIA_NODISCARD bool	processing (const JobContainer &jobData)
	Checks whether jobData is queued for worker processing.

static GAIA_NODISCARD bool	busy (const JobContainer &jobData)
	Checks whether jobData currently is executing or queued for execution.

static GAIA_NODISCARD bool	done (const JobContainer &jobData)
	Checks whether jobData has finished executing.

Detailed Description

Storage and lifecycle manager for internal job and parallel callback records.

Member Function Documentation

◆ alloc_job()

GAIA_NODISCARD JobHandle gaia::mt::JobManager::alloc_job ( Job job )

inline

Allocates a new job container identified by a unique JobHandle.

Returns: JobHandle

Warning: Must be used from the main thread.

◆ alloc_parallel_callback()

GAIA_NODISCARD ParallelCallbackHandle gaia::mt::JobManager::alloc_parallel_callback	(	JobArgsFunc	callback,
		uint32_t	refs
	)

inline

Allocates a shared callback record used by parallel jobs.

Parameters

callback	Callback to invoke.
refs	Initial reference count.

Returns: Handle identifying the new callback record.

◆ busy()

static GAIA_NODISCARD bool gaia::mt::JobManager::busy ( const JobContainer & jobData )

inlinestatic

Checks whether jobData currently is executing or queued for execution.

Parameters

jobData Job to inspect.

Returns: True when the job is busy.

◆ data() [1/2]

JobContainer & gaia::mt::JobManager::data ( JobHandle jobHandle )

inline

Returns mutable internal storage for jobHandle.

Parameters

jobHandle Handle of the job to inspect.

◆ data() [2/2]

const JobContainer & gaia::mt::JobManager::data ( JobHandle jobHandle ) const

inline

Returns immutable internal storage for jobHandle.

Parameters

jobHandle Handle of the job to inspect.

◆ dep() [1/2]

void gaia::mt::JobManager::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::JobManager::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()

void gaia::mt::JobManager::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.

◆ done()

static GAIA_NODISCARD bool gaia::mt::JobManager::done ( const JobContainer & jobData )

inlinestatic

Checks whether jobData has finished executing.

Parameters

jobData Job to inspect.

Returns: True when the state bits equal JobState::Done.

◆ executing()

static void gaia::mt::JobManager::executing	(	JobContainer &	jobData,
		uint32_t	workerIdx
	)

inlinestatic

Marks a job as executing on the worker identified by workerIdx.

Parameters

jobData	Job to transition.
workerIdx	Worker executing the job.

◆ finalize()

static void gaia::mt::JobManager::finalize ( JobContainer & jobData )

inlinestatic

Marks a job as finished.

Parameters

jobData Job to transition.

◆ free_edges()

static void gaia::mt::JobManager::free_edges ( JobContainer & jobData )

inlinestatic

Releases heap storage used for the dependency list of jobData.

Parameters

jobData Job whose dependency edge storage should be released.

◆ free_job()

void gaia::mt::JobManager::free_job ( JobHandle jobHandle )

inline

Invalidates jobHandle by resetting its index in the job pool. Every time a job is deallocated its generation is increased by one.

Parameters

jobHandle Job handle.

Warning: Caller must serialize job-pool allocation/free access.

◆ free_parallel_callback()

void gaia::mt::JobManager::free_parallel_callback ( ParallelCallbackHandle handle )

inline

Releases a shared callback record.

Parameters

handle Handle of the callback record to free.

◆ invoke_parallel_callback()

void gaia::mt::JobManager::invoke_parallel_callback	(	ParallelCallbackHandle	handle,
		const JobArgs &	args
	)

inline

Invokes the shared callback referenced by handle.

Parameters

handle	Callback handle.
args	Arguments forwarded to the callback.

◆ is_clear() [1/2]

static GAIA_NODISCARD bool gaia::mt::JobManager::is_clear ( JobContainer & jobData )

inlinestatic

Checks whether jobData is in the clear state.

Parameters

jobData Job to inspect.

Returns: True when the packed state is zero.

◆ is_clear() [2/2]

GAIA_NODISCARD bool gaia::mt::JobManager::is_clear ( JobHandle jobHandle ) const

inline

Checks whether the job referenced by jobHandle is in the clear state.

Parameters

jobHandle Handle of the job to inspect.

Returns: True when the packed state is zero.

◆ processing() [1/2]

static GAIA_NODISCARD bool gaia::mt::JobManager::processing ( const JobContainer & jobData )

inlinestatic

Checks whether jobData is queued for worker processing.

Parameters

jobData Job to inspect.

Returns: True when the state bits equal JobState::Processing.

◆ processing() [2/2]

static void gaia::mt::JobManager::processing ( JobContainer & jobData )

inlinestatic

Marks a job as queued for worker processing.

Parameters

jobData Job to transition.

◆ release_parallel_callback_ref()

GAIA_NODISCARD bool gaia::mt::JobManager::release_parallel_callback_ref ( ParallelCallbackHandle handle )

inline

Releases one reference to the callback referenced by handle.

Parameters

handle Callback handle.

Returns: True when the released reference was the last one.

◆ reset_state()

static void gaia::mt::JobManager::reset_state ( JobContainer & jobData )

inlinestatic

Resets a completed or never-submitted job back to the clear state.

Parameters

jobData Job to reset.

◆ run()

static void gaia::mt::JobManager::run ( JobContainer & jobData )

inlinestatic

Execute the functor associated with the job container.

Parameters

jobData Container with internal job specific data

◆ signal_edge()

static bool gaia::mt::JobManager::signal_edge ( JobContainer & jobData )

inlinestatic

Signals that one dependency edge of jobData has completed.

Parameters

jobData Job whose dependency counter should be decremented.

Returns: True when the job has no remaining dependencies and can be processed.

◆ submit()

static uint32_t gaia::mt::JobManager::submit ( JobContainer & jobData )

inlinestatic

Marks a job as submitted.

Parameters

jobData Job to transition.

Returns: Updated packed state value after the transition.

◆ submitted()

static GAIA_NODISCARD bool gaia::mt::JobManager::submitted ( const JobContainer & jobData )

inlinestatic

Checks whether jobData has been submitted but not yet queued for execution.

Parameters

jobData Job to inspect.

Returns: True when the state bits equal JobState::Submitted.

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

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

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ alloc_job()

◆ alloc_parallel_callback()

◆ busy()

◆ data() [1/2]

◆ data() [2/2]

◆ dep() [1/2]

◆ dep() [2/2]

◆ dep_refresh()

◆ done()

◆ executing()

◆ finalize()

◆ free_edges()

◆ free_job()

◆ free_parallel_callback()

◆ invoke_parallel_callback()

◆ is_clear() [1/2]

◆ is_clear() [2/2]

◆ processing() [1/2]

◆ processing() [2/2]

◆ release_parallel_callback_ref()

◆ reset_state()

◆ run()

◆ signal_edge()

◆ submit()

◆ submitted()