A Detailed Guide to Activity Launch Modes in Android

Word count: 588Reading time: 3 min

 2019/09/01

Android Activities have several critical launch modes: standard, singleTop, singleTask, and singleInstance. Each serves a specific architectural purpose. In this post, I’ll demonstrate their behaviors using a demo and visualizing the Activity Stack at each step.

An Activity Stack is a Last-In-First-Out (LIFO) data structure. Paying attention to the “Stack Content” column in the examples below will help you grasp how these modes differ in practice.

The demo code is available on GitLab: AndroidLaunchModeTest.

standard Mode

1	android:launchMode="standard"

The default mode. A new instance of the Activity is created every time it is started.

Test Trace:

Launch MainActivity
- Stack: MainActivity
Launch StandardActivity
- Stack: StandardActivity -> MainActivity
Launch StandardActivity again
- Stack: StandardActivity (new) -> StandardActivity -> MainActivity

singleTop Mode

1	android:launchMode="singleTop"

If an instance of the Activity already exists at the top of the current stack, the system routes the intent to that instance via onNewIntent(). Otherwise, a new instance is created.

Test 1: singleTopActivity is NOT at the top

MainActivity -> StandardActivity
- Stack: StandardAntivity, MainActivity
Launch singleTopActivity
- Stack: singleTopActivity, StandardActivity, MainActivity
Launch StandardActivity
- Stack: StandardActivity, singleTopActivity, StandardActivity, MainActivity
Launch singleTopActivity
- Stack: singleTopActivity (new), StandardActivity, singleTopActivity, StandardActivity, MainActivity
- Note: Because StandardActivity was at the top, a new instance was created.

Test 2: singleTopActivity IS at the top

Stack: singleTopActivity, StandardActivity, MainActivity
Launch singleTopActivity again
- Stack: singleTopActivity (reused), StandardActivity, MainActivity
- Note: am_new_intent is triggered instead of onCreate.

singleTask Mode

1	android:launchMode="singleTask"

Task Reuse: If an instance exists anywhere in the task, the system brings it to the front and calls onNewIntent().
Clear-Top: All Activities sitting on top of the reused singleTask Activity are destroyed.
Affinity: By default, it stays in the same task. If taskAffinity is specified, it might start in a new task.

Test 1: singleTask (Default Affinity)

Stack: StandardActivity, singleTaskActivity, StandardActivity, MainActivity
Launch singleTaskActivity
- Stack: singleTaskActivity (reused), StandardActivity, MainActivity
- Note: The intermediate StandardActivity was cleared.

Test 2: singleTask (With taskAffinity)
If android:taskAffinity="" is set, singleTask will launch into a new task.

Launch singleTaskWithAffinity
- Task 1: singleTaskWithAffinity
- Task 0: StandardActivity, MainActivity
Launch StandardActivity (from Task 1)
- Task 1: StandardActivity, singleTaskWithAffinity
Launch singleTaskWithAffinity again
- Task 1: singleTaskWithAffinity (reused)
- Note: Both activities exist in separate stacks/tasks in the Recent Apps view.

singleInstance Mode

1	android:launchMode="singleInstance"

As the name suggests, this is a truly unique instance. The system creates a dedicated task for this Activity, and it is the only Activity in that task.

Test 1: singleInstance (Default Affinity)

Stack 0: StandardActivity, MainActivity
Launch singleInstanceActivity
- Stack 1: singleInstanceActivity
- Stack 0: StandardActivity, MainActivity
Launch StandardActivity (from Stack 1)
- Stack 1: singleInstanceActivity
- Stack 0: StandardActivity (new), StandardActivity, MainActivity
- Note: The new Activity is pushed back to the previous “home” task, leaving singleInstanceActivity alone in its task.

Summary:

singleInstance creates a new task but doesn’t necessarily show up as a separate item in “Recents” unless a unique taskAffinity is also set.
It is globally unique.

Key Concepts

TaskAffinity

The task an Activity “prefers” to belong to. Activities with the same affinity belong to the same parent task. Defaults to the package name. Used with singleTask or allowTaskReparenting.

Relationships: ActivityRecord, TaskRecord, ActivityStack

ActivityRecord: Represents a single Activity instance. One Activity defined in XML can have multiple ActivityRecords if started multiple times.
TaskRecord: A “task” or “stack” of ActivityRecords (LIFO).
ActivityStack: Manages multiple TaskRecords. Usually, a system has a “Home Stack” and an “App Stack.”