dispatch-module-architecture

Dispatch module architecture

Applicable scenarios

• Modify third-party build machine, Docker, or Kubernetes scheduling logic
• Handle queues, quotas, resource allocation, and build machine selection
• Troubleshoot task queuing, dispatch failures, or scheduling imbalance
• Extend new scheduling types or build resource types

Inapplicable scenarios

• Only modifying Agent daemon, heartbeat, or upgrade
• Only modifying Worker execution, logs, or variable reporting
• Only developing plugins or modifying task.json
• Only modifying pipeline business orchestration

Quick guidance

1. This skill focuses on "how tasks are allocated to a suitable execution environment".
2. The core of Dispatch is not executing tasks, but making choices, queuing, rate limiting, and advancing.
3. First enter the corresponding reference document by problem type:
   • Module structure and core objects:reference/1-dispatch-foundation.md
   • Queues, quotas, and scheduling policies:reference/2-queue-quota-scheduling.md
   • Resource type extension and troubleshooting:reference/3-resource-extension-debug.md
4. If the problem has already reached the build machine and started executing, switch to agent-module-architecture or worker-module-architecture。
5. If the problem is that the plugin itself is incompatible with the runtime environment, switch to pipeline-plugin-development。

High-signal rules

• Dispatch solves "where to run" and "when to run"
• Queues, quotas, resource types, and listener advancement are different facets of the same scheduling system
• For scheduling problems, first distinguish whether it is insufficient resources, policy mismatch, or execution-side abnormality
• When implementing a new scheduling type, the data model, listener chain, and resource constraints must be considered together

Key pitfalls

• Misjudging Agent / Worker execution failures as Dispatch problems
• Looking only at a single service method without looking at the complete advancement chain of listeners, queues, and quotas
• When adding a new scheduling type, only adding the entry point without adding rate limiting, state transitions, and cleanup logic
• When troubleshooting scheduling problems, only staring at code without first confirming resource pool and quota status

Further reading

• Module structure and core objects:reference/1-dispatch-foundation.md
• Queues, quotas, and scheduling policies:reference/2-queue-quota-scheduling.md
• Resource type extension and troubleshooting:reference/3-resource-extension-debug.md
• If you are modifying build machine host behavior: see also agent-module-architecture
• If you are modifying task execution: see also worker-module-architecture