Documentation
Playground GitHub

$dispatch / $periodic

Schedule background work that survives app restarts.

$dispatch - One-Time Work

Run a suspend function in the background:

// Simple dispatch
$dispatch(api.syncData)

// With constraints
$dispatch(api.uploadPhotos, constraints: ["wifi"])

// With delay
$dispatch(api.sendReminder, delay: { mins: 5 })

// Named (for later retrieval)
$dispatch(api.uploadPhoto, name: "upload-${photoId}")

$periodic - Recurring Work

Run work periodically:

// Run every hour
$periodic(api.refreshFeed, every: { hours: 1 })

// With constraints and name
$periodic(api.syncData, every: { mins: 60 }, name: "data-sync", constraints: ["wifi", "charging"])

Android enforces a minimum 15-minute interval for periodic work.

See it happen

One-time and recurring work compile to different scheduling calls; a delay adds one more argument to either.

Sync.wh 
var syncing = false

fun sync() {
  syncing = true
  $dispatch(api.syncData, constraints: ["wifi"])
}

<Button onClick={sync}>
  <Text>Sync</Text>
</Button>
Kotlin waiting
Scroll into view to compile.

$dispatch compiles to a single scheduleDispatch call, keyed by the constraints you gave it — no WorkRequest builder to write by hand.

Constraints

Specify conditions for work execution:

  • "network" - Any network connection
  • "wifi" - WiFi connection required
  • "batteryOk" - Battery not low
  • "charging" - Device charging
  • "idle" - Device idle (Doze mode)
  • "storageOk" - Storage not low
  • "expedited" - Run as soon as possible
$dispatch(api.uploadVideo, constraints: ["wifi", "charging", "batteryOk"])

Duration Syntax

delay: { hours: 1 }
delay: { mins: 30 }
delay: { seconds: 45 }
delay: { hours: 1, mins: 30 }

every: { hours: 2 }
every: { mins: 60 }

Work Status

Track work progress:

fun startUpload() {
  val upload = $dispatch(api.uploadFile, name: "upload-123")

  // Check status
  val status = upload.status
  // "pending" | "running" | "succeeded" | "failed" | "cancelled"

  // Cancel work
  upload.cancel()
}

Retrieve Work by Name

@prop val photoId: String

var upload: DispatchHandle? = null

fun checkUpload() {
  upload = $work("upload-${photoId}")
}

<Column>
  <Button onClick={checkUpload}>
    <Text>Check status</Text>
  </Button>
  @if (upload != null) {
    <Text>Status: {upload?.status}</Text>
    <Button onClick={() => upload?.cancel()}>
      <Text>Cancel</Text>
    </Button>
  }
</Column>

Run Periodic Work Immediately

$onMount {
  $periodic(api.syncData, every: { hours: 1 }, name: "sync")
}

fun runNow() {
  $work("sync")?.runNow()
}

<Button onClick={runNow}>
  <Text>Sync Now</Text>
</Button>

Sequential Work

Wait for work to complete before starting the next:

suspend fun syncAll() {
  $await $dispatch(api.syncUsers)
  $await $dispatch(api.syncOrders)
  $await $dispatch(api.syncProducts)
}

Complete Example

// Background sync with UI control
$onMount {
  $periodic(api.syncData, every: { hours: 1 }, name: "background-sync", constraints: ["wifi"])
}

fun syncNow() {
  $work("background-sync")?.runNow()
}

fun cancelSync() {
  $work("background-sync")?.cancel()
}

<Column class="gap-16 p-16">
  <Button onClick={syncNow}>
    <Text>Sync Now</Text>
  </Button>

  <Button onClick={cancelSync}>
    <Text>Cancel Background Sync</Text>
  </Button>
</Column>

Photo Upload Example

fun uploadPhoto(photoId: String) {
  $dispatch(api.uploadPhoto, name: "upload-$photoId", constraints: ["wifi", "batteryOk"])
}

// Check upload status
fun isUploading(photoId: String): Boolean {
  return $work("upload-$photoId")?.status == "running"
}

Behind the Scenes

Whitehall uses WorkManager for background work:

  • Work survives app restarts
  • Respects system constraints (battery, network, etc.)
  • Guaranteed execution (eventually)
  • Handles retries automatically

Use workers for operations that should complete even if the app is closed, like uploads, sync, and scheduled tasks. For immediate work, use regular coroutines with $onMount or launch.

See Also