wehub-resource-sync
53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# Task Lifecycle
|
|
|
|
This page focuses on Tasks, Activities, Back fallback, and lifetime rules. For cross-app launch traces, see [cross-app-launch.md](cross-app-launch.md). For the broader OS layer, see [overview.md](overview.md).
|
|
|
|
> **Which "task"?** "Task" throughout this document means the Android-aligned OS construct — an Activity stack belonging to one running app, mirroring Android's Task / back-stack model. This is **unrelated** to the benchmark evaluation tasks under `bench_env/task/<suite>/` (parameterised Python classes with `setup` + judge), which happen to share the name.
|
|
|
|
## Model
|
|
|
|
```ts
|
|
type Task = {
|
|
taskId: string;
|
|
rootAppId: AppId;
|
|
stack: ActivityInstance[];
|
|
launchedByTaskId?: string;
|
|
wasExternallyRouted?: boolean;
|
|
};
|
|
```
|
|
|
|
Each Task has a stack of Activity instances. Backgrounded apps stay mounted but hidden with `display:none`, so React state survives task switches.
|
|
|
|
## Core Operations
|
|
|
|
| Operation | Behavior |
|
|
|---|---|
|
|
| `LAUNCH_APP` (new Task) | Create a Task. Record `launchedByTaskId` if there's an active caller Task. |
|
|
| `LAUNCH_APP` (reactivate existing Task) | Reactivate without modifying `launchedByTaskId`, **except** when there's no caller (user tapped from the Launcher) **and** `wasExternallyRouted=false` — then clear `launchedByTaskId` to `undefined`. This is the one-shot rule: Launcher reactivation of an in-app-created Task severs the original caller link; Launcher reactivation of an externally-routed Task preserves it. |
|
|
| `PUSH_ACTIVITY` | Push a new Activity onto the current or target Task. |
|
|
| `POP_ACTIVITY` | Pop the top Activity when `stack.length > 1`. |
|
|
| `finishActivity` | Pop top Activity if `stack > 1` (and activate `launchedByTaskId` if the popped Activity had one); if `stack == 1` activate `launchedByTaskId` when present, else call `goHome()`. **Never destroys the Task** — that requires explicit `closeApp` / Recents swipe. |
|
|
| `MARK_EXTERNAL_ROUTE` | Mark a newly created Task as externally routed by `openApp(appId, route)`. Current role is narrow: see the `LAUNCH_APP` reactivation rule above. |
|
|
| `consumeLaunchedBy` | Clear the one-shot caller pointer after returning to the caller Task. |
|
|
| `setActivityIntent(activityId, payload)` | Store a new intent payload on an existing Activity. Apps **poll** this via `os.getIntentPayload(activityId)`; there is no `onNewIntent`-style callback. |
|
|
|
|
## Back Fallback
|
|
|
|
Back is first offered to app and Activity navigators. If they return false:
|
|
|
|
1. `os.finishTopActivity` pops the top Activity when the Task has more than one Activity.
|
|
2. `os.returnToLauncherTask` reactivates `launchedByTaskId` and consumes that pointer.
|
|
3. `os.goHomeFallback` returns to the launcher while keeping the Task in Recents.
|
|
|
|
Ordinary Back fallback does not destroy Tasks. Closing is explicit via Recents swipe-away or `__OS__.closeApp(appId)`.
|
|
|
|
## Route Reset on Caller Return
|
|
|
|
Before returning to a caller Task, the OS resets the current app route to `/`. This keeps transient routes such as payment confirmation or SMS compose from being the screen shown when the Task is later reopened from Recents.
|
|
|
|
## Related Docs
|
|
|
|
- OS overview → [overview.md](overview.md)
|
|
- Cross-app launch traces → [cross-app-launch.md](cross-app-launch.md)
|
|
- Intent system → [intent-system.md](intent-system.md)
|