ExistingTaskPolicy enum

Policy for handling existing tasks with the same ID.

When scheduling a task with an ID that already exists, this policy determines whether to keep the existing task or replace it with the new one.

Keep Existing Task

// Schedule initial sync
await NativeWorkManager.enqueue(
  taskId: 'daily-sync',
  trigger: TaskTrigger.periodic(Duration(hours: 24)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  existingPolicy: ExistingTaskPolicy.keep,  // Prevent duplicate
);

// Later, user changes settings - but keep the original task running
await NativeWorkManager.enqueue(
  taskId: 'daily-sync',  // Same ID
  trigger: TaskTrigger.periodic(Duration(hours: 12)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  existingPolicy: ExistingTaskPolicy.keep,  // Original 24h task continues
);

Replace Existing Task

// Schedule initial sync
await NativeWorkManager.enqueue(
  taskId: 'daily-sync',
  trigger: TaskTrigger.periodic(Duration(hours: 24)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
);

// User changes settings - update the task immediately
await NativeWorkManager.enqueue(
  taskId: 'daily-sync',  // Same ID
  trigger: TaskTrigger.periodic(Duration(hours: 12)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  existingPolicy: ExistingTaskPolicy.replace,  // Cancels 24h, starts 12h
);

When to Use Keep

Use ExistingTaskPolicy.keep when:

  • Task is idempotent (safe to run multiple times)
  • You want to ensure at least one execution happens
  • Avoiding duplicate work is critical (e.g., expensive API calls)
  • Initial scheduling during app install

Example: One-time data migration

await NativeWorkManager.enqueue(
  taskId: 'v2-migration',
  trigger: TaskTrigger.oneTime(),
  worker: DartWorker(callbackId: 'migrateData'),
  existingPolicy: ExistingTaskPolicy.keep,  // Don't duplicate if already scheduled
);

When to Use Replace

Use ExistingTaskPolicy.replace when:

  • User changed settings/preferences
  • Task configuration needs updating
  • Old parameters are no longer valid
  • Cancelling and rescheduling is intentional

Example: User changes sync frequency

// User updates setting: hourly → every 6 hours
await NativeWorkManager.enqueue(
  taskId: 'background-sync',
  trigger: TaskTrigger.periodic(newInterval),
  worker: NativeWorker.httpSync(url: syncUrl),
  existingPolicy: ExistingTaskPolicy.replace,  // Apply new frequency immediately
);

Comparison

Scenario Keep Replace
Task already exists New request ignored Old task cancelled, new scheduled
Task not found New task scheduled New task scheduled
Typical use case Prevent duplicates Update configuration

Default Behavior

If policy is not specified, ExistingTaskPolicy.replace is used by default. This ensures the latest configuration is always applied.

See also: NativeWorkManager.enqueue

Inheritance
Available extensions

Values

keep → const ExistingTaskPolicy

Keep the existing task, ignore the new one.

If a task with the same ID already exists, the new enqueue request is silently ignored. The existing task continues unchanged.

Useful when you want to prevent duplicate tasks from being scheduled.

replace → const ExistingTaskPolicy

Replace the existing task with the new one.

If a task with the same ID already exists, it is cancelled and replaced with the new task. Use this when updating task configuration.

Properties

hashCode → int
The hash code for this object.
no setterinherited
index → int
A numeric identifier for the enumerated value.
no setterinherited
name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

values → const List<ExistingTaskPolicy>
A constant List of the values in this enum, in order of their declaration.