CapGdlrJobs

Inherits: GdlrCapability < RefCounted < Object

Capability that runs jobs and tracks their status.

Description

A job is a unit of work described by a CapGdlrJobs.JobSpec. Jobs can require other jobs, and Godular runs the requirements first. Each job runs once until reset_job() clears it.

Import the bundled jobs module to get this capability, then register specifications through CapGdlrJobsRegistry:

const JobsModule = preload("res://addons/godular/built_ins/modules/jobs/md_jobs.gd")

static var IMPORTS = [JobsModule]

var jobs_registry: CapGdlrJobsRegistry
var jobs: CapGdlrJobs

func register() -> void:
    jobs_registry.register_job(LoadSaveJob.new())

func enable() -> void:
    var save_data = await jobs.ensure_job(LoadSaveJob.KEY).await_resolved()

The jobs module exports CapGdlrJobs as a tree export, so scene code can also call GdlrModuleManager.request() with it.

Tutorials

• Jobs

Methods

GdbPromise	run_job(key: StringName, args: Dictionary = {}) abstract
GdbPromise	ensure_job(key: StringName) abstract
GdbPromise	reset_job(key: StringName, abort_started: bool = false) abstract
Variant	get_job_output(key: StringName) abstract
JobStatus	get_job_status(key: StringName) abstract
bool	has_job(key: StringName) abstract

---

Enumerations

enum JobStatus: 🔗

JobStatus NONE = -1

No job with that key has run. See get_job_status().

JobStatus WAITING_FOR_START = 0

The job waits for run_job().

JobStatus WAITING_FOR_REQUIREMENTS = 1

The job waits for its requirements.

JobStatus RUNNING = 2

The job runs.

JobStatus COMPLETED = 3

The job completed. get_job_output() returns its output.

JobStatus FAILED = 4

The job failed or was aborted.

---

enum JobRunPolicy: 🔗

JobRunPolicy WHEN_REQUIRED = 0

The job starts when ensure_job() first requests it.

JobRunPolicy MANUAL = 1

The job starts only through run_job(). ensure_job() waits for that call.

---

Method Descriptions

GdbPromise run_job(key: StringName, args: Dictionary = {}) abstract 🔗

Starts a MANUAL job and returns a promise of its output. The promise rejects when the job is not manual. A job that already ran returns its existing promise.

---

GdbPromise ensure_job(key: StringName) abstract 🔗

Returns a promise of the output of the job with key. Creates the job on the first call. A WHEN_REQUIRED job starts immediately. A MANUAL job starts on run_job().

---

GdbPromise reset_job(key: StringName, abort_started: bool = false) abstract 🔗

Clears the job with key so that it can run again. A job that waits for its start, completed, or failed is cleared at once. For a job that waits for requirements or runs, the method fails unless abort_started is true. Then it calls CapGdlrJobs.JobSpec.abort_current_run(), marks the job as failed, and clears it.

---

Variant get_job_output(key: StringName) abstract 🔗

Returns the output of the completed job with key. Fails when no job with that key ran.

---

JobStatus get_job_status(key: StringName) abstract 🔗

Returns the status of the job with key. When no job with that key ran, the method reports an error and returns NONE.

---

bool has_job(key: StringName) abstract 🔗

Returns true when a job with key exists.