TaskGraph class

A directed acyclic graph (DAG) of background tasks.

Use TaskGraph when you need complex parallel → sequential workflows that go beyond a simple linear TaskChainBuilder.

Example: Parallel download → merge → upload

// A and B download in parallel.
// When both finish, C merges the results.
// When merge is done, D uploads.

final graph = TaskGraph(id: 'export-workflow')
  ..add(TaskNode(id: 'download-A', worker: HttpDownloadWorker(
      url: 'https://cdn.example.com/part-a.zip',
      savePath: '/tmp/part-a.zip')))
  ..add(TaskNode(id: 'download-B', worker: HttpDownloadWorker(
      url: 'https://cdn.example.com/part-b.zip',
      savePath: '/tmp/part-b.zip')))
  ..add(TaskNode(id: 'merge', worker: DartWorker(callbackId: 'mergeFiles'),
      dependsOn: ['download-A', 'download-B']))
  ..add(TaskNode(id: 'upload', worker: HttpUploadWorker(
      url: 'https://api.example.com/submit',
      filePath: '/tmp/merged.zip'),
      dependsOn: ['merge']));

final execution = await NativeWorkManager.enqueueGraph(graph);

// Monitor completion
execution.result.then((r) {
  if (r.success) print('All ${r.completedCount} tasks done!');
  else print('Failed: ${r.failedNodes}');
});

Constraints Per Node

final graph = TaskGraph(id: 'nightly-sync')
  ..add(TaskNode(
      id: 'heavy-compute',
      worker: DartWorker(callbackId: 'computeStats'),
      constraints: Constraints(requiresCharging: true)))
  ..add(TaskNode(
      id: 'upload-stats',
      worker: HttpUploadWorker(url: uploadUrl, filePath: statsFile),
      dependsOn: ['heavy-compute'],
      constraints: Constraints(requiresWifi: true)));

await NativeWorkManager.enqueueGraph(graph);

Failure Behavior

If a node fails, all downstream nodes that depend on it (directly or transitively) are cancelled. Nodes that do not depend on the failed node continue to execute.

Limitations

• The graph must be a DAG — cycles are detected during enqueueTaskGraph and throw an ArgumentError.
• All node IDs must be unique within the graph.
• The implementation uses the existing NativeWorkManager.events stream for fan-in synchronization, so the app must be running while the graph executes. For graphs that must survive app termination, use individual NativeWorkManager.enqueue calls with TaskTrigger instead.

Constructors

TaskGraph({required String id})

Properties

hashCode → int

The hash code for this object.

no setter, inherited

id → String

Unique ID for this graph execution. Used to namespace node task IDs.

final

nodes → List<TaskNode>

All nodes currently in the graph.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

add(TaskNode node) → TaskGraph

Add a TaskNode to the graph.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toMap() → Map<String, dynamic>

Convert to map for platform channel.

toString() → String

A string representation of this object.

inherited

validate() → void

Validate the graph: check for duplicate IDs, missing dependencies, and cycles.

Operators

operator ==(Object other) → bool

The equality operator.

inherited