xmake-docs/docs/api/scripts/extension-modules/async/jobgraph.md

async.jobgraph

This module provides a job graph (DAG) for advanced asynchronous job scheduling and dependency management in xmake Lua scripts.

jobgraph.new

• Create a new job graph instance.

Function Prototype

::: tip API

jobgraph.new()

:::

Parameter Description

No parameters required for this function.

Usage

import("async.jobgraph")
local jobs = jobgraph.new()

All following examples assume async.jobgraph has been imported.

jobgraph:add

• Add a job node to the job graph.

Function Prototype

::: tip API

jobgraph:add(name: <string>, jobfunc: <function>, options: <table>)

:::

Parameter Description

Parameter	Description
name	Job name string
jobfunc	Job function
options	Options table (optional)

Usage

local jobs = jobgraph.new()
jobs:add("job/root", function() print("root job") end)
jobs:add("job/child", function() print("child job") end)

You can also assign a job to a group or multiple groups using the groups option:

local jobs = jobgraph.new()

-- Add a job to a single group
jobs:add("foo/buildfiles", function(index, total, opt)
    -- build logic
end, {groups = "foo/buildfiles"})

-- Add a job to multiple groups
jobs:add("xxx", function(index, total, opt)
    -- ...
end, {groups = {"group1", "group2"}})

::: tip NOTE For batch group operations, it is generally more recommended and convenient to use jobgraph:group.

See: jobgraph:group :::

A typical use case in a rule:

rule("foo")
    on_build_files(function (target, jobgraph, sourcebatch, opt)
        local group_name = target:name() .. "/buildfiles"
        for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
            local job_name = target:name() .. "/" .. sourcefile
            jobgraph:add(job_name, function(index, total, opt)
                -- TODO: build file
            end, {groups = group_name})
        end
        -- add job orders, other target jobs -> this build group
        jobgraph:add_orders(other_target:name() .. "/buildfiles", group_name)
    end, {jobgraph = true})

jobgraph:add_orders

• Add dependency orders.

Function Prototype

::: tip API

jobgraph:add_orders(jobname: <string>, ...)

:::

Parameter Description

Parameter	Description
jobname	Job name string
...	Variable arguments for dependency jobs

Usage

local jobs = jobgraph.new()
jobs:add("job/root", function() print("root job") end)
jobs:add("job/child", function() print("child job") end)
jobs:add_orders("job/child", "job/root")

jobgraph:group

• Group jobs for batch dependency management. You can use a callback to add jobs to a group.

Function Prototype

::: tip API

jobgraph:group(groupname: <string>, callback: <function>)

:::

Parameter Description

Parameter	Description
groupname	Group name string
callback	Callback function to add jobs to group

Usage

local jobs = jobgraph.new()

jobs:add("job", function(index, total, opt)
    -- ...
end)

jobs:group("group1", function()
    for i = 0, N do
        jobs:add("group1/job" .. i, function(index, total, opt)
            -- TODO
        end)
    end
end)

jobs:group("group2", function()
    for i = 0, N do
        jobs:add("group2/job" .. i, function(index, total, opt)
            -- TODO
        end)
    end
end)

-- sort job orders after adding all these jobs
jobs:add_orders("job", "group1", "group2")

See also: async.runjobs