openharmonyinsight/taskpool-dependency-analysis

Taskpool Dependency Analysis Skill

This skill helps you systematically diagnose and fix taskpool dependency problems in the static ArkTS runtime. It walks you through building a dependency graph from user code, detecting cycles, identifying illegal API call sequences, tracing notification/activation paths, and recommending fixes.

Why this skill exists

Taskpool dependencies are not "just deadlock detection" — they are a bespoke task dependency model with its own state machine, notification mechanism, task-type restrictions, and cancel propagation rules. A task that depends on another task blocks via waitForDependencies() until its taskDependenciesCount reaches zero; when a prerequisite task finishes, it calls notifyDependencies() which decrements counters and re-enqueues ready dependents via tryActivatePendingDependencyTask. If any step in this chain breaks, dependent tasks silently hang or never execute, and the root cause is often not where the symptom appears.

Source code bindings

When using this skill, read these source files for the authoritative implementation:

• Static stdlib: runtime_core/static_core/plugins/ets/stdlib/std/concurrency/taskpool.ets

  • Task.addDependency (line ~1238): validates task types, checks circular dependency via hasTaskDFS, builds edge in dependentTasks set
  • Task.removeDependency (line ~1284): validates state, removes edge, adjusts taskDependenciesCount
  • Task.hasTaskDFS (line ~1371): DFS cycle detection traversing dependentTasks
  • InternalTask.waitForDependencies (line ~718): blocks on taskMutex/condVar until taskDependenciesCount == 0
  • InternalTask.notifyDependencies (line ~731): decrements each dependent's count, signals condvar, activates ready tasks
  • tryActivatePendingDependencyTask (line ~3014): re-enqueues a task whose dependencies are all satisfied
  • moveToPendingDependencyQueue (line ~2993): stores task+priority in pending map when dequeued but still blocked

• Dynamic reference: commonlibrary/ets_utils/js_concurrent_module/taskpool/task.cpp and task_manager.cpp

  • Task::AddDependency, Task::RemoveDependency, Task::CheckAddDependency
  • TaskManager::StoreTaskDependency, TaskManager::CheckCircularDependency, TaskManager::NotifyDependencyTaskInfo, TaskManager::RemoveTaskDependency, TaskManager::ClearDependentTask

• Test reference: runtime_core/static_core/plugins/ets/tests/ets-common-tests/taskpool/common_tasks.ets

  • dependentTasksTest, circularDependencyTest, dependencyExecutedTaskTest, dependencyCancelTaskTest, doubleCancelByDependencyTest

For detailed reference on data structures, error codes, and the full lifecycle, read references/dependency_reference.md in this skill's directory.

Analysis workflow

Follow these steps in order. Do not skip steps or merge them.

Step 1: Classify the problem

Read the user's description or the failing test case and classify into one of these categories:

| Category | Typical symptoms | Error codes | |----------|-----------------|-------------| | Circular dependency | addDependency throws immediately | 10200026 | | Missing/nonexistent dependency | removeDependency throws | 10200027, 10200097 | | Dependent task never wakes | Task submitted but never executes; hangs silently | None (no error thrown) | | Cancel propagation failure | Canceling a prerequisite doesn't cancel dependents, or vice versa | None | | Illegal API sequence | addDependency/removeDependency on wrong task type | 10200070, 10200071, 10200073, 10200074, 10200079, 10200113 | | Re-execution after dependency | Re-executing a task that already ran with dependencies | 10200072 | | Timeout + dependency conflict | execute(task, {timeout}) on task with dependency | Custom error |

If the user provides a test case (.ets file), read it first and extract: task creation order, addDependency calls, execute calls, and expected vs actual behavior.

Step 2: Build the dependency graph from user code

From the user's code or test case, extract every Task creation, addDependency, removeDependency, and execute call in order. Build a directed graph:

• Nodes: each Task instance (label with variable name + taskId if available)
• Edges: each addDependency creates an edge dependent → prerequisite (the dependent waits for the prerequisite)
• Edge deletions: each removeDependency removes that edge
• Execution state: mark nodes as unexecuted, submitted, running, finished, canceled based on execute/cancel calls

Represent the graph as text, e.g.:

task1 ──depends on──> task2 ──depends on──> task3
task4 ──depends on──> task2

If the graph has been modified by removeDependency, show the graph at each significant state change.

Step 3: Detect cycles and illegal edges

Run these checks on the graph:

3a: Cycle detection

Use DFS from each node. If any path returns to the starting node, it's a cycle. Report the exact cycle path:

Cycle detected: task1 → task2 → task3 → task1
Introduced by: task3.addDependency(task1) at line X

The static implementation uses hasTaskDFS which traverses the dependentTasks (reverse direction: from prerequisite towards its dependents). Make sure your cycle detection matches this traversal direction.

3b: Illegal task-type edges

Check each node against these rules (these are the exact checks in addDependency and removeDependency):

| Task type | Can call addDependency? | Can be a dependency target? | Can call removeDependency? | |-----------|------------------------|----------------------------|---------------------------| | Unexecuted (TASK) | Yes | Yes | Yes (if isDependent) | | Executed (COMMON_TASK, after execute) | No (10200070) | No (10200079) | No (10200071) | | Periodic task | No (10200113) | No (10200113) | No (10200113) | | Group task | No (10200073) | No (10200074) | N/A | | SeqRunner task | No (10200070) | No (10200079) | No (10200071) | | AsyncRunner task | No (10200070) | No (10200079) | No (10200071) | | Timeout task | No | No | N/A |

Report any violations with the specific error code.

3c: Missing dependency edges

For removeDependency errors: verify that the edge actually exists in the graph at the time of removal. If the user code calls removeDependency(taskX) but taskX is not a prerequisite of the caller, that's error 10200027.

Step 4: Trace the notification/activation path

This is the most important step for "dependent task never wakes" problems. Trace the full path from when a prerequisite task finishes to when the dependent task should execute:

Prerequisite finishes
  → InternalTask.execute() finally block
    → notifyDependencies() called
      → Iterates over prerequisite.dependentTasks
        → For each dependent:
          - Locks dependent.taskMutex
          - Decrements dependent.taskDependenciesCount
          - Signals dependent.condVar
          - If taskDependenciesCount == 0:
            → tryActivatePendingDependencyTask(dependent)
              - Takes priority from pendingDependencyTasks map
              - Re-enqueues dependent into globalTaskQueue
              - Signals global condvar to wake a worker

Check each step for potential failure:

| Failure point | Symptom | Root cause pattern | |---------------|---------|--------------------| | notifyDependencies not called | Dependent never wakes | Task type is not COMMON_TASK (dynamic: TriggerTask only calls NotifyDependencyTaskInfo for common tasks); or task was canceled (isCancel=true skips notification) | | dependentTasks set is empty | No dependents notified | Edge was removed before execution, or addDependency was called after execute | | taskDependenciesCount doesn't reach 0 | Dependent wakes but re-waits | Some prerequisite finished without decrementing this dependent's count (race: count was incremented after the notification ran) | | pendingDependencyTasks has no entry for the dependent | tryActivatePendingDependencyTask returns false | Task was never moved to pending queue (e.g., it was dequeued and started waitForDependencies before all prerequisites finished) | | Task is CANCELED in tryActivatePendingDependencyTask | Promise rejected with cancel error | Another thread/task canceled the dependent between notification and activation | | Global condvar not signaled | Worker doesn't pick up re-enqueued task | Race between enqueue and worker sleep |

When diagnosing "never wakes" issues, add logging at these points:

1. notifyDependencies: log each dependent task's taskId and the new taskDependenciesCount
2. tryActivatePendingDependencyTask: log whether priority was found, whether task is CANCELED, whether re-enqueue succeeded
3. waitForDependencies: log when entering wait and when exiting (with final taskDependenciesCount)
4. moveToPendingDependencyQueue: log when a task is moved to pending vs when it's skipped (dependencies already cleared)

Step 5: Trace cancel propagation

When a task is canceled, its dependents should also be canceled. Trace this path:

cancel(task) called
  → task state -> CANCELED (CAS)
  → tryCancelDependentTasks(task)
    → Iterates over InternalTask.of(task).dependentTasks
      → For each dependent:
        - calls cancel(dependent) (silently catches errors)
  → cleanupCanceledPendingDependencyTask(task)
    → Takes priority from pendingDependencyTasks
    → If found: finishCanceledPendingDependencyTask (rejects promises)

Check for:

• Dependents not canceled: dependentTasks set was empty or the edge was already removed
• Dependents stuck in WAITING state: They were in the global queue and cancel didn't remove them (this should be handled by RemoveDependTaskByTaskId in dynamic, tryCancelDependentTasks in static)
• Double cancel race: Two tasks in the same dependency chain are canceled concurrently — check whether cancel() has proper CAS on state transition

Step 6: Produce the diagnostic report

Output a structured report with these sections:

Dependency Graph

Nodes: [task1 (unexecuted), task2 (finished), task3 (submitted, isDependent=true)]
Edges:
  task3 → task2  (task3 depends on task2)
  task1 → task3  (task1 depends on task3)

Issues Found

For each issue, provide:

• Issue type: circular / illegal-edge / missing-edge / notification-failure / cancel-failure
• Error code (if applicable)
• Exact source location (file:line)
• The affected edge or path
• Root cause explanation

Recommended Fix

For each issue, recommend one of:

• Reorder addDependency calls: declare all dependencies before execute
• Remove the problematic edge: use removeDependency before the task type changes
• Split the task: create a new unexecuted task instead of reusing an executed one
• Replace task type: don't use periodic/group/seqRunner/asyncRunner where dependencies are needed
• Add synchronization: if the issue is a race in notification/activation, identify the specific race window and the fix (do not suggest sleep/retry/timeout)
• Fix the notification path: if notifyDependencies is not being called, identify why and fix the condition

Refactored Code Sketch

If the user's code has structural issues (e.g., adding dependencies after execute, self-referencing cycles, group tasks in dependency chains), provide a sketch of the corrected code showing the proper order of operations.

Key invariant checklist

When analyzing any taskpool dependency problem, verify these invariants hold. If any is violated, that's your root cause or contributing factor:

1. Edge direction invariant: addDependency(taskA, taskB) means taskA waits for taskB. The edge is stored in taskB.dependentTasks (reverse mapping). If you traverse dependentTasks, you're going from prerequisite towards dependents, not from dependents towards prerequisites.

2. taskDependenciesCount invariant: For any task T, T.taskDependenciesCount must equal the number of prerequisite edges pointing into T. If taskDependenciesCount > 0, T must be in pendingDependencyTasks (if dequeued from global queue) or in the global queue (if just submitted). If taskDependenciesCount == 0, T must NOT be in pendingDependencyTasks.

3. Task type restriction invariant: Only unexecuted TASK type and FUNCTION_TASK can participate in addDependency. Periodic, group, seqRunner, asyncRunner, and executed (COMMON_TASK) types are prohibited in both directions.

4. Notification invariant: When a COMMON_TASK finishes (not canceled), notifyDependencies() must be called, and it must traverse ALL entries in this.dependentTasks. If any entry is missing, some dependent will never wake.

5. Cancel propagation invariant: When a task is canceled, ALL tasks in its dependentTasks must also be canceled (recursively). If any dependent is not canceled, it will either hang forever (waiting for a canceled prerequisite) or execute with missing prerequisite results.

6. Single-instance invariant: waitForDependencies() checks isRunning after dependencies are satisfied. If another instance of the same task is running, the current instance waits. notifyDependencies() sets isRunning = false and signals condVar to unblock the next instance.

7. Pending-queue consistency: A task moves from global queue → pendingDependencyTasks (when dequeued but blocked) → global queue (when re-enqueued by tryActivatePendingDependencyTask). It must not be in both the global queue and pendingDependencyTasks simultaneously. The removePendingDependencyTask call at the start of execute() ensures cleanup.

Anti-patterns to watch for

These patterns in user code are almost always bugs. Flag them immediately:

1. addDependency after execute: task.addDependency(other) after taskpool.execute(task) — throws 10200070
2. Self-dependency: task.addDependency(task) — throws 10200026
3. Periodic task in dependency chain: periodicTask.addDependency(x) or x.addDependency(periodicTask) — throws 10200113
4. Group task in dependency chain: group tasks cannot add or receive dependencies — throws 10200073/10200074
5. Missing prerequisite notification: if a prerequisite is executed via seqRunner/asyncRunner/group, it will never call notifyDependencies, so dependents hang forever
6. Re-execution after dependency completion: taskpool.execute(task) after the task already ran with dependencies — throws 10200072
7. removeDependency on wrong task: removing a dependency that doesn't exist — throws 10200027
8. Cancel without propagation: canceling a prerequisite but expecting dependents to still run — they will be canceled too

Error code quick reference

| Code | Constant | Meaning | Typical fix | |------|----------|---------|-------------| | 10200026 | CIRCULAR_DEPENDENCY | Cycle in dependency graph | Remove the edge that closes the cycle | | 10200027 | DEPENDENCY_NOT_EXIST | removeDependency on non-edge | Only remove edges that were actually added | | 10200070 | EXECUTED_TASK_ADD_DEPENDENCY | addDependency on executed/runner task | Declare dependencies before execute | | 10200071 | EXECUTED_TASK_REMOVE_DEPENDENCY | removeDependency on executed task | Don't modify dependencies after execution | | 10200073 | GROUP_TASK_ADD_DEPENDENCY | Group task calling addDependency | Remove group task from dependency chain | | 10200074 | GROUP_TASK_RELIED_ON | Group task as dependency target | Use regular task instead of group task | | 10200079 | SEQ/ASYNC_RUNNER_TASK_RELIED_ON | SeqRunner/AsyncRunner as dependency target | Use regular task instead | | 10200097 | NO_DEPENDENCY | removeDependency on task with no deps | Ensure addDependency was called first | | 10200101 | NO_PARAMS | addDependency/removeDependency with no args | Provide task arguments | | 10200113 | PERIODIC_TASK_ADD_DEPENDENCY | Periodic task in dependency | Remove periodic task from dependency chain |