job_system.h File Reference

#include "defines.h"

Go to the source code of this file.

Data Structures
struct	job_info
	Describes a job to be run. More...
struct	job_system_config

Typedefs
typedef b8(*	pfn_job_start) (void *, void *)
	A function pointer definition for jobs. More...
typedef void(*	pfn_job_on_complete) (void *)
	A function pointer definition for completion of a job. More...
typedef enum job_type	job_type
	Describes a type of job. More...
typedef enum job_priority	job_priority
	Determines which job queue a job uses. The high-priority queue is always exhausted first before processing the normal-priority queue, which must also be exhausted before processing the low-priority queue. More...
typedef struct job_info	job_info
	Describes a job to be run. More...
typedef struct job_system_config	job_system_config

Enumerations
enum	job_type { JOB_TYPE_GENERAL = 0x02 , JOB_TYPE_RESOURCE_LOAD = 0x04 , JOB_TYPE_GPU_RESOURCE = 0x08 }
	Describes a type of job. More...
enum	job_priority { JOB_PRIORITY_LOW , JOB_PRIORITY_NORMAL , JOB_PRIORITY_HIGH }
	Determines which job queue a job uses. The high-priority queue is always exhausted first before processing the normal-priority queue, which must also be exhausted before processing the low-priority queue. More...

Functions
b8	job_system_initialize (u64 *job_system_memory_requirement, void *state, void *config)
	Initializes the job system. Call once to retrieve job_system_memory_requirement, passing 0 to state. Then call a second time with allocated state memory block. More...
void	job_system_shutdown (void *state)
	Shuts the job system down. More...
b8	job_system_update (void *state, struct frame_data *p_frame_data)
	Updates the job system. Should happen once an update cycle. More...
KAPI void	job_system_submit (job_info info)
	Submits the provided job to be queued for execution. More...
KAPI job_info	job_create (pfn_job_start entry_point, pfn_job_on_complete on_success, pfn_job_on_complete on_fail, void *param_data, u32 param_data_size, u32 result_data_size)
	Creates a new job with default type (Generic) and priority (Normal). More...
KAPI job_info	job_create_type (pfn_job_start entry_point, pfn_job_on_complete on_success, pfn_job_on_complete on_fail, void *param_data, u32 param_data_size, u32 result_data_size, job_type type)
	Creates a new job with default priority (Normal). More...
KAPI job_info	job_create_priority (pfn_job_start entry_point, pfn_job_on_complete on_success, pfn_job_on_complete on_fail, void *param_data, u32 param_data_size, u32 result_data_size, job_type type, job_priority priority)
	Creates a new job with the provided priority. More...

Typedef Documentation

job_info

typedef struct job_info job_info

Describes a job to be run.

job_priority

typedef enum job_priority job_priority

Determines which job queue a job uses. The high-priority queue is always exhausted first before processing the normal-priority queue, which must also be exhausted before processing the low-priority queue.

job_system_config

typedef struct job_system_config job_system_config

job_type

typedef enum job_type job_type

Describes a type of job.

pfn_job_on_complete

typedef void(* pfn_job_on_complete) (void *)

A function pointer definition for completion of a job.

pfn_job_start

typedef b8(* pfn_job_start) (void *, void *)

A function pointer definition for jobs.

Enumeration Type Documentation

job_priority

enum job_priority

Determines which job queue a job uses. The high-priority queue is always exhausted first before processing the normal-priority queue, which must also be exhausted before processing the low-priority queue.

Enumerator
JOB_PRIORITY_LOW	The lowest-priority job, used for things that can wait to be done if need be, such as log flushing.
JOB_PRIORITY_NORMAL	A normal-priority job. Should be used for medium-priority tasks such as loading assets.
JOB_PRIORITY_HIGH	The highest-priority job. Should be used sparingly, and only for time-critical operations.

job_type

enum job_type

Describes a type of job.

Enumerator
JOB_TYPE_GENERAL	A general job that does not have any specific thread requirements. This means it matters little which job thread this job runs on.
JOB_TYPE_RESOURCE_LOAD	A resource loading job. Resources should always load on the same thread to avoid potential disk thrashing.
JOB_TYPE_GPU_RESOURCE	Jobs using GPU resources should be bound to a thread using this job type. Multithreaded renderers will use a specific job thread, and this type of job will run on that thread. For single-threaded renderers, this will be on the main thread.

Function Documentation

job_create()

KAPI job_info job_create	(	pfn_job_start	entry_point,
		pfn_job_on_complete	on_success,
		pfn_job_on_complete	on_fail,
		void *	param_data,
		u32	param_data_size,
		u32	result_data_size
	)

Creates a new job with default type (Generic) and priority (Normal).

Parameters

entry_point	A pointer to a function to be invoked when the job starts. Required.
on_success	A pointer to a function to be invoked when the job completes successfully. Optional.
on_fail	A pointer to a function to be invoked when the job fails. Optional.
param_data	Data to be passed to the entry point upon execution.
param_data_size	The data to be passed on to entry_point callback. Pass 0 if not used.
result_data_size	The size of result data to be passed on to success callback. Pass 0 if not used.

Returns

The newly created job information to be submitted for execution.

job_create_priority()

KAPI job_info job_create_priority	(	pfn_job_start	entry_point,
		pfn_job_on_complete	on_success,
		pfn_job_on_complete	on_fail,
		void *	param_data,
		u32	param_data_size,
		u32	result_data_size,
		job_type	type,
		job_priority	priority
	)

Creates a new job with the provided priority.

Parameters

entry_point	A pointer to a function to be invoked when the job starts. Required.
on_success	A pointer to a function to be invoked when the job completes successfully. Optional.
on_fail	A pointer to a function to be invoked when the job fails. Optional.
param_data	Data to be passed to the entry point upon execution.
param_data_size	The data to be passed on to entry_point callback. Pass 0 if not used.
result_data_size	The size of result data to be passed on to success callback. Pass 0 if not used.
type	The type of job. Used to determine which thread the job executes on.
priority	The priority of this job. Higher priority jobs obviously run sooner.

Returns

The newly created job information to be submitted for execution.

job_create_type()

KAPI job_info job_create_type	(	pfn_job_start	entry_point,
		pfn_job_on_complete	on_success,
		pfn_job_on_complete	on_fail,
		void *	param_data,
		u32	param_data_size,
		u32	result_data_size,
		job_type	type
	)

Creates a new job with default priority (Normal).

Parameters

entry_point	A pointer to a function to be invoked when the job starts. Required.
on_success	A pointer to a function to be invoked when the job completes successfully. Optional.
on_fail	A pointer to a function to be invoked when the job fails. Optional.
param_data	Data to be passed to the entry point upon execution.
param_data_size	The data to be passed on to entry_point callback. Pass 0 if not used.
result_data_size	The size of result data to be passed on to success callback. Pass 0 if not used.
type	The type of job. Used to determine which thread the job executes on.

Returns

The newly created job information to be submitted for execution.

job_system_initialize()

b8 job_system_initialize	(	u64 *	job_system_memory_requirement,
		void *	state,
		void *	config
	)

Initializes the job system. Call once to retrieve job_system_memory_requirement, passing 0 to state. Then call a second time with allocated state memory block.

Parameters

job_system_memory_requirement	A pointer to hold the memory required for the job system state in bytes.
state	A block of memory to hold the state of the job system.
config	A pointer to the configuration (job_system_config) of this system.

Returns

True if the job system started up successfully; otherwise false.

job_system_shutdown()

void job_system_shutdown

(

void *

state

)

Shuts the job system down.

job_system_submit()

KAPI void job_system_submit

(

job_info

info

)

Submits the provided job to be queued for execution.

Parameters

info	The description of the job to be executed.

job_system_update()

b8 job_system_update	(	void *	state,
		struct frame_data *	p_frame_data
	)

Updates the job system. Should happen once an update cycle.