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
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.