# Meet Meeseeks
Source: https://docs.meeseeks.mattramotar.dev/introduction
Meeseeks is a Kotlin Multiplatform library for scheduling and managing background tasks across Android, JVM, native (iOS), and JS (Web). Whether your tasks are simple or complex, for one user or hundreds of millions, Meeseeks can help.
## I'm Mr. Meeseeks! Look at me!
***Meeseeks*** is a Kotlin Multiplatform library for effortless background task scheduling. It's inspired by the [Meeseeks](https://rickandmorty.fandom.com/wiki/Mr._Meeseeks) beings, who are friendly and cheerful and motivated to help. They are summoned to complete a task and they disappear after it's done. This is the goal of the Meeseeks library: handle anything from simple one-off jobs to complex periodic workflows so you can focus on building great features, not wrestling with scheduling code.
## Why Meeseeks?
Whether you need to periodically sync data, schedule local notifications, or run computational tasks behind the scenes, Meeseeks provides:
Summoning a Meeseeks is easy. No more fiddling with complicated job schedulers
or manual timers. Drop in a few lines of code, and let Meeseeks do the rest.
Backed by
[WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager)
on Android, [Quartz Job Scheduling](https://www.quartz-scheduler.org/) on JVM, [BGTaskScheduler](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler) on native (iOS), and [Background Synchronization API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Synchronization_API) on JS (Web). Even if the app closes or the device restarts, your tasks persist.
Because not all tasks are created equal. Choose from exponential backoff,
fixed intervals, or custom strategies to ensure your tasks complete
successfully.
Write once, run anywhere. Bring the power of Meeseeks to Android, iOS, web,
desktop, and beyond using a single Kotlin codebase.
## This is a Meeseeks box
A *[Meeseeks Box](https://rickandmorty.fandom.com/wiki/Mr._Meeseeks_Box)* lets you summon a Meeseeks to complete a task. Once the Meeseeks completes its task, it disappears. Here's a primer from [Rick](https://rickandmorty.fandom.com/wiki/Rick_Sanchez):
## Let me show you how it works
With just a few lines, you can register your task types and summon Meeseeks:
```kotlin
val bgTaskManager = Meeseeks.initialize(applicationContext) {
register(SyncPayload.stableId) { SyncWorker(applicationContext) }
}
```
```kotlin
val taskHandle = bgTaskManager.oneTime(SyncPayload(...))
```
```kotlin
taskHandle.observe().collect { status ->
// Pending -> Running -> Finished
}
```
## Next steps
Dive into Meeseeks' core architecture and how it handles tasks behind the scenes.
Learn how to get up and running with Meeseeks in just a few minutes.
Browse real-world examples and recipes for common scheduling scenarios.
## Built with ❤️ by
The solution for working with data in Kotlin. Whether you’re building alone or
with a team of thousands, Store can help.
The solution for working with data in Kotlin. Whether you’re building alone or
with a team of thousands, Store can help.
Improving engineering for large-scale mobile applications.
Protect, promote and advance the development of the Kotlin programming
language.
# Quickstart
Source: https://docs.meeseeks.mattramotar.dev/quickstart
Set up and summon your first Meeseeks.
This guide helps you install and configure Meeseeks as quickly as possible.
To integrate Meeseeks into your project, add the dependency.
```toml Gradle Version Catalogs
[versions]
meeseeks = "0.6.0-alpha02"
[libraries]
meeseeks-runtime = { group = "dev.mattramotar.meeseeks", name = "runtime", version.ref = "meeseeks" }
```
```kotlin Kotlin DSL
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(libs.meeseeks.runtime)
// or
implementation("dev.mattramotar.meeseeks:runtime:0.6.0-alpha02")
}
}
}
}
```
```groovy Groovy DSL
implementation "dev.mattramotar.meeseeks:runtime:0.6.0-alpha02"
```
In your `Info.plist` file, add the following:
```xml
BGTaskSchedulerPermittedIdentifiers
dev.mattramotar.meeseeks.task.refresh
dev.mattramotar.meeseeks.task.processing
```
```kotlin Android
class App: Application(), Configuration.Provider {
val bgTaskManager by lazy {
Meeseeks.initialize(applicationContext) {
minBackoff(20.seconds)
maxRetryCount(3)
maxParallelTasks(5)
allowExpedited()
register(SyncPayload.stableId) { SyncWorker(applicationContext) }
register(RefreshPayload.stableId) { RefreshWorker(applicationContext) }
}
}
override val workManagerConfiguration: Configuration by lazy {
val delegating = DelegatingWorkerFactory().apply {
addFactory(MeeseeksWorkerFactory(bgTaskManager))
}
Configuration.Builder().setWorkerFactory(delegating).build()
}
}
```
```java JVM
public class Main {
public static void main(String[] args) {
Meeseeks.initialize(
new ApplicationContext(),
configure -> {
configure.register(SyncPayload.stableId, SyncWorker::new);
configure.register(RefreshPayload.stableId, RefreshWorker::new);
}
);
}
}
```
```swift Native (iOS)
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
Meeseeks.companion.initialize(
context: self,
) { configure in
configure.register(stableId: SyncPayload.stableId) { ctx in
SyncWorker(ctx)
}
configure.register(stableId: RefreshPayload.stableId) { ctx in
RefreshWorker(ctx)
}
}
BGTaskScheduler.shared.register(
forTaskWithIdentifier: "dev.mattramotar.meeseeks.task.refresh",
using: nil
) { id in
BGTaskRunner.run(id: id) { ... }
}
BGTaskScheduler.shared.register(
forTaskWithIdentifier: "dev.mattramotar.meeseeks.task.processing",
using: nil
) { id in
BGTaskRunner.run(id: id) { ... }
}
}
return true
}
}
```
```kotlin JS (Web)
object BrowserContext : AppContext
fun main() {
Meeseeks.initialize(
context = BrowserContext
) {
register(SyncPayload.stableId, ::SyncWorker)
register(RefreshPayload.stableId, ::RefreshWorker)
}
if (js("('serviceWorker' in navigator)") as Boolean) {
window.navigator.serviceWorker
.register("/service-worker.js")
.then { console.log("Service Worker registered!") }
.catch { err -> console.warn("SW registration failed: ${err}") }
}
}
```
If your browser supports [Background Sync](https://developer.mozilla.org/en-US/docs/Web/API/Background_Sync_API) or [Periodic Background Sync](https://developer.mozilla.org/en-US/docs/Web/API/Web_Periodic_Background_Synchronization_API), you can handle tasks even when the tab isn't active.
Example `service-worker.js`:
```js
self.addEventListener('sync', event => {
if (event.tag && event.tag.startsWith("meeseeks-")) {
event.waitUntil(handleSync(event.tag));
}
});
self.addEventListener('periodicsync', event => {
if (event.tag && event.tag.startsWith("meeseeks-")) {
event.waitUntil(handleSync(event.tag));
}
});
async function handleSync(tag) {
if (self.BGTaskRunner && self.BGTaskRunner.run) {
await self.BGTaskRunner.run(tag);
}
};
```
If a browser doesn't support service workers or background sync, Meeseeks falls back to in-memory scheduling that runs only while the page is open.
The `BGTaskManager` is essentially the `MeeseeksBox`. It is the global manager of all scheduled tasks. It is what you need to schedule a task (summon a `MrMeeseeks`).
```kotlin
val bgTaskManager = Meeseeks.initialize(applicationContext) {...}
```
```kotlin One-Time Task
bgTaskManager.oneTime(SyncPayload(...)) {
requireNetwork(true)
requireCharging(false)
requireBatteryNotLow(true)
highPriority()
retryWithExponentialBackoff(
initialDelay = 1.minutes,
maxAttempts = 3
)
}
```
```kotlin Periodic Task
bgTaskManager.periodic(SyncPayload(...), every = 5.minutes) {
requireNetwork(true)
requireCharging(false)
requireBatteryNotLow(true)
highPriority()
retryWithExponentialBackoff(
initialDelay = 1.minutes,
maxAttempts = 3
)
}
```
```kotlin
taskHandle.observe().collect { status ->
// Pending -> Running -> Finished
}
```
***
Explore advanced usage in the{" "}
Advanced Docs.
## Frequently asked questions
Meeseeks uses a local SQLDelight database to store all task data (including
parameters, schedule, status, logs). Each platform has a driver for that database, so your tasks are persisted across
app restarts or process deaths.
Because tasks and their metadata live in a local database, Meeseeks can
reconstruct and re-schedule them when your app restarts.
* `Android`: `WorkManager` automatically
re-schedules tasks after a reboot if you configure it to do so.
* `JVM`: Tasks are re-scheduled with `Quartz` the next time your application launches and re-initializes Meeseeks.
* `Native (iOS)`: Tasks are re-scheduled with `BGTaskScheduler` the next time your application launches and re-initializes Meeseeks.
* `JS (Web)`: If you used `SyncManager` or `PeriodicSyncManager`, the browser may continue to run tasks via the `ServiceWorker` in the background (user permissions and browser support permitting). Otherwise, tasks do not continue to run after the page is closed, but will be re-scheduled when the page is opened again.
* `Android`: Concurrency is delegated to `WorkManager` which manages parallel
tasks according to OS constraints.
* `JVM`: Concurrency is similarly delegated to `Quartz`.
* `Native (iOS)`: Uses `BGTaskScheduler` for periodic and one-time tasks. Tasks are canceled or updated locally in the DB, and on iOS 16+ can be canceled programmatically via `cancelTaskRequestWithIdentifier`.
* `JS (Web)`: Uses `ServiceWorker` `sync`/`periodicsync` if available, otherwise in-memory timers.
You can call `MeeseeksBox.sendBackToBox(id)` to cancel a task by its
`MrMeeseeksId`. This removes or cancels its scheduled job and updates the
database so it will not be run again. For updating a task’s data (such as
its schedule or priority), you will need to cancel the existing one and
summon a new Meeseeks with the updated `Task`.
Meeseeks provides APIs to query a task's current status at any time:
* `MeeseeksBox.getStatus(taskId)` returns the `TaskStatus` of a single task, or `null` if that task does not exist.
* `MeeseeksBox.getAllTasks()` returns a list of `ScheduledTask` objects, each containing the task’s `MrMeeseeksId`, `TaskStatus`, and other metadata (like run attempt count).
* `MeeseeksBox.watchStatus(taskId)` provides a reactive stream of `TaskStatus` changes.
Tasks specify a `TaskSchedule`, which can be:
* `TaskSchedule.OneTime`
* `TaskSchedule.Periodic`
On Android, `PeriodicWorkRequests` are used under the hood. On iOS, `BGAppRefreshTaskRequest` and `BGProcessingTaskRequest` are used under the hood.
```kotlin
val oneTimeSyncTask = Task(
MeeseeksType.SYNC,
schedule = TaskSchedule.OneTime(
initialDelay = 0
)
)
val meeseeksId = MeeseeksBox.value.summon(oneTimeSyncTask)
```
Periodic tasks on some platforms require a minimum interval. For example on
Android, [WorkManager has a minimum interval of 15
minutes](https://developer.android.com/develop/background-work/background-tasks/persistent/getting-started/define-work#schedule_periodic_work).
```kotlin
val periodicSyncTask = Task(
MeeseeksType.SYNC,
schedule = TaskSchedule.Periodic(
interval = 15.minutes,
flexWindow = 60.seconds
)
)
val meeseeksId = MeeseeksBox.value.summon(periodicSyncTask)
```
It depends on your `TaskPreconditions`. For instance, if `requiresNetwork =
true`, the task will not be run unless a network is available.
* Use exponential backoff (`TaskRetryPolicy.ExponentialBackoff`) for
network-related tasks. This prevents tight loops and reduces server/battery
load.
* Limit max retries to avoid infinite attempts.
* Use fixed intervals (`TaskRetryPolicy.FixedInterval`) if you’re sure the operation should repeat in consistent time blocks.
* Log failed attempts thoroughly so you can identify repeated failures.
Because Meeseeks is a Kotlin Multiplatform library, you can implement a
`MeeseeksFactory` that provides platform-specific code. For example, if you
need iOS-specific APIs, you could use `expect/actual` classes or call Swift
code from your iOS target. The library only orchestrates scheduling and
persistence. What the `MrMeeseeks` does inside `execute()` is up to you.
Meeseeks uses `TaskStatus` to represent the lifecycle of tasks:
* **Pending**: The task is scheduled but not currently running.
* **Running**: The task is actively executing.
* **Finished**: A terminal state indicating no further runs. It may be:
* **Completed** (successful)
* **Cancelled** (manually cancelled or platform removed it)
* **Failed** (permanently failed)
When a task runs, if it returns:
* `TaskResult.Success`: Meeseeks sets the task status to `Finished.Completed`.
* `TaskResult.Retry` or `TaskResult.Failure.Transient`: Meeseeks reverts the task status to `Pending` so that it can be retried later (respecting any backoff or retry policy).
* `TaskResult.Failure.Permanent`: Meeseeks sets the task status to `Finished.Failed`, meaning no more attempts will be scheduled.
Conceptually, you can visualize these transitions:
If a task is canceled via `MeeseeksBox.sendBackToBox`, it transitions to `Finished.Cancelled`. For tasks that fail with a transient error (e.g., network unavailable), the status simply goes back to `Pending` until the next run attempt.
## Next steps
Yes siree! You've successfully initialized Meeseeks, configured your first
tasks, and seen how to track results. Use the resources below to keep
learning.
Learn how tasks, scheduling, concurrency, and logging really work under the
hood.
Build custom Meeseeks, handle special concurrency cases, or dive into
debugging tasks.
Contribute, ask questions, or file issues on our GitHub repo.
