Skip to content

docs: document in-degree counter pattern in DAG.Engine and Task.Process #19

@kination

Description

@kination

Summary

The in-degree counter pattern is already implemented across DAG.Engine and Task.Process, but it's not documented explicitly. Future contributors may not immediately understand the readiness tracking mechanism.

How It Currently Works

  1. At run start, DAG.Engine calls build_dep_counts/1 to compute the initial in-degree (number of unresolved dependencies) for each task.
  2. Each Task.Process starts with deps_remaining = in_degree[task_id].
  3. When the Engine receives {:task_done, run_id, task_id}, it calls Graph.immediate_dependents/2 and sends :dep_done to each dependent's Task.Process.
  4. Task.Process decrements its deps_remaining counter. When it hits 0, the process transitions :pending → :queued automatically and dispatches to a worker.

This means task readiness is evaluated eagerly after each completion — not in waves. As soon as all deps for a task complete, it starts.

Action Items

  • Add a module-level @moduledoc to DAG.Engine explaining the in-degree counter flow
  • Add a module-level @moduledoc to Task.Process explaining the deps_remaining counter
  • Add a sequence diagram to docs/plans/2026-03-05-levicon-mvp.md showing the full task lifecycle

References

  • lib/levicon/dag/engine.exbuild_dep_counts/1, handle_info({:task_done})
  • lib/levicon/task/process.exdeps_remaining, :dep_done cast handler

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions