Background work
Background tasks handle short jobs that can wait, such as refreshing a cache or retrying a sync. A registered handler runs independently of a page, using persisted inputs and checking whether it has been asked to stop.
Add to your app
cargo add 'day-part-background@0.*'
Build with the Day CLI so the host includes native scheduling and process startup code. Declare permitted task identifiers on iOS as shown below.
API reference · Source and demo.
Choose a scheduler
capabilities
reports persistent and in-process scheduling separately.
| Need | Scheduler | Platforms |
|---|---|---|
| Retain a request after the app process exits | Persistent OS scheduling | iOS and Android |
| Run delayed work while the process remains alive | In-process scheduling | iOS, Android, macOS, Windows, and Linux |
Persistent scheduling never falls back to in-process work. Desktop persistent scheduling is unsupported; web and HarmonyOS support neither scheduler. In-process scheduling does not keep a suspended app running or restart a closed app.
Register a handler
Use a stable task identifier and a handler that does not need UI state:
use day_part_background::{Context, Outcome, Schedule};
day_part_background::register_task!("dev.example.refresh", refresh);
fn refresh(context: Context) -> Outcome {
if context.is_cancelled() { return Outcome::Retry; }
// Process a bounded chunk of persisted work; check cancellation between chunks.
Outcome::Success
}
async fn schedule_refresh() -> Result<(), day_part_background::Error> {
let mut request = Schedule::new("dev.example.refresh");
request.requires_network = true;
request.interval_secs = Some(15 * 60);
day_part_background::schedule(&request).await
}
register_task!
registers the handler before any page mounts. The handler runs on a worker thread. Persist its
inputs before scheduling, keep writes safe to repeat, and check the cancellation flag between
bounded units of work. Cancellation cannot forcibly terminate arbitrary Rust code.
Outcome
reports success, a transient failure to retry, or a permanent failure. The OS decides when to
run persistent work and can defer or stop it. Keep a foreground path for work users need now.
Persistent scheduling rules
schedule
submits a request to the OS. cancel
removes pending work and asks active handlers to stop.
- Scheduling replaces pending work with the same identifier. Android also cancels an executing instance; it may take time to observe the cancellation flag.
- Repeats request an interval of at least 15 minutes. A delay is a minimum, not a deadline. Network and charging constraints can postpone execution further.
- Payloads are UTF-8 strings of at most 4,096 bytes. Store larger data separately and pass an ID.
- Cancellation cannot undo results already written by a handler.
Work within the running process
Use the same registered handler with
in_process::schedule
for a delayed refresh or retry that can be discarded when the process exits:
fn schedule_in_process() -> Result<(), day_part_background::Error> {
let mut request = day_part_background::Schedule::new("dev.example.refresh");
request.delay_secs = 30;
day_part_background::in_process::schedule(&request)
}
in_process::cancel
affects only the in-process schedule with that identifier. Network and charging constraints
return an unsupported error. Repeats wait at least the requested interval after the handler
returns; retry waits 15 minutes, and permanent failure ends the schedule.
A replacement can begin before a cancelled handler returns. At most 64 worker threads can be active, including cancelled handlers that have not yet returned.
Native configuration
| Platform | Setup and limits |
|---|---|
| iOS / UIKit | Uses BGProcessingTaskRequest. List task identifiers in BGTaskSchedulerPermittedIdentifiers and include processing in UIBackgroundModes. Repeating tasks resubmit before execution. |
| Android / Material | Uses WorkManager, with dependencies and manifest permissions contributed by the package. A Worker can start the Rust handler without an Activity. Force-stop prevents execution until the user opens the app again. |
In the iOS host configuration, declare each registered identifier:
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array><string>dev.example.refresh</string></array>
<key>UIBackgroundModes</key>
<array><string>processing</string></array>
See Day’s native project configuration, Apple’s Background Tasks, and Android’s WorkManager guide. This package does not provide continuous execution, foreground services, or background file transfers. OS scheduling does not guarantee eventual execution.
Exercise a handler
Background Lab records a completion count. Schedule work, leave the app, then return and refresh
the count. Its Run handler now control invokes
run_now
for diagnostics; that synchronous call runs on the caller’s thread and does not test OS scheduling.
The portable walkthrough checks controls and cancellation. Unit tests cover schedule validation, replacement, retries, and cooperative cancellation. Process-restart behavior requires a separate native test.