Writing Thread Safe Code for Android

I recognize that the above image has nothing to do with threads. But this is my website. So you're gonna have to deal.

What thread safe code actually means

1. Access state. Is the thread reading the latest value? Is it reading a value that's internally consistent with whatever else it might look at?

2. Mutate state. Does the write actually land? Does it stay consistent with the other writes happening alongside it?

3. Execute code. Does it run the right number of times? Once ever? Once at a time? Once per request?

📸 Image placeholder: Toolbox overview graphic. Could show the three pillars (Access, Mutate, Execute) as columns or layers, with the tools mapped underneath: @Volatile, Atomics, synchronized / ReentrantLock, double-checked locking, concurrent collections, Mutex, Actor + StateFlow, thread confinement. A "lightest to most structural" axis would help orient the reader for what's coming.

The canonical example: a lost update

var count = 0

fun increment() {
    count++
}

1. Read the current value of count

2. Add 1 to it

3. Write the new value back

📸 Image placeholder: Timeline-style interleaving diagram. Two parallel lanes (Thread A, Thread B) running left to right. Both lanes read count: 0, then both write count: 1. Show visually that the two reads happen before either write, so the second write overwrites the first. Would make the lost update click in a way the text version can't.

Thread A reads count: 0
Thread B reads count: 0   ← B reads before A writes back
Thread A writes count: 1
Thread B writes count: 1   ← B overwrites A's result

@Volatile : freshness

📸 Image placeholder: Two CPU cores side by side, each with its own cache holding a copy of the variable count. Core A writes count = 6 to its cache. Core B is still reading count = 5 from its own cache. Arrows showing the eventual (but not immediate) propagation down to main memory.

@Volatile
var isRunning = false

What @Volatile does NOT solve

@Volatile
var count = 0

fun main() {
    val t1 = Thread { repeat(1000) { count++ } }
    val t2 = Thread { repeat(1000) { count++ } }
    t1.start(); t2.start()
    t1.join(); t2.join()
    println(count) // Prints something like 1847, not 2000
}

Thread A reads count: 5      ← A sees the latest value (volatile works!)
Thread B reads count: 5      ← B also sees the latest value (volatile works!)
Thread A writes count: 6     ← A's write goes straight to memory
Thread B writes count: 6     ← B's write overwrites A, based on the stale read

Atomics : single-value mutation

val count = AtomicInteger(0)

fun main() {
    val t1 = Thread { repeat(1000) { count.incrementAndGet() } }
    val t2 = Thread { repeat(1000) { count.incrementAndGet() } }
    t1.start(); t2.start()
    t1.join(); t2.join()
    println(count.get()) // Always 2000
}

val cachedUser = AtomicReference<User?>(null)

// Safe to call from any thread
fun updateUser(user: User) = cachedUser.set(user)
fun getUser(): User? = cachedUser.get()

// Atomic conditional set: only writes if current value is null
fun initializeUser(user: User) = cachedUser.compareAndSet(null, user)

The limit of atomics

val userRef = AtomicReference<User?>(null)
val timestampRef = AtomicReference<Long?>(null)

// ❌ Two separate atomic operations, not one
fun updateUser(user: User) {
    userRef.set(user)
    // A thread reading here sees the new user but the old timestamp
    timestampRef.set(System.currentTimeMillis())
}

synchronized : protecting a section of code

val lock = Any()
var user: User? = null
var lastUpdated: Long = 0

fun updateUser(newUser: User) {
    synchronized(lock) {
        user = newUser
        lastUpdated = System.currentTimeMillis()
    } // Both fields updated together, no thread can read between them
}

fun getSnapshot(): Pair<User?, Long> {
    synchronized(lock) {
        return Pair(user, lastUpdated) // Reads both fields atomically
    }
}

Deadlocks

Thread A holds Lock 1, waiting for Lock 2
Thread B holds Lock 2, waiting for Lock 1
→ Neither can proceed. The app hangs forever.

val lock = Any()

fun methodA() {
    synchronized(lock) {
        methodB() // Same thread, same lock, no deadlock
    }
}

fun methodB() {
    synchronized(lock) {
        // do work
    }
}

ReentrantLock : same lock, more knobs

val lock = ReentrantLock()

fun doWork() {
    lock.withLock {       // Acquires on entry, releases on exit, even if an exception throws
        // critical section
    }
}

// Try to get the lock, but don't wait if it's taken
if (lock.tryLock()) {
    try {
        refreshCache()
    } finally {
        lock.unlock()
    }
} else {
    // Lock is busy, skip the refresh and try next time
}

// Or wait, but only up to a limit
if (lock.tryLock(100, TimeUnit.MILLISECONDS)) {
    try { doWork() } finally { lock.unlock() }
} else {
    handleTimeout()
}

Double-checked locking : execute exactly once

@Volatile
private var instance: Database? = null

fun getInstance(): Database {
    if (instance == null) {           // Fast path, no lock
        synchronized(this) {
            if (instance == null) {   // Re-check inside the lock
                instance = Database()
            }
        }
    }
    return instance!!
}

val database by lazy { Database() } // Double-checked locking under the hood
object Database { ... }             // JVM guarantees single initialization

Thread-safe collections

val cache = ConcurrentHashMap<String, User>()

cache["user_1"] = user                          // Thread-safe
val user = cache["user_1"]                      // Thread-safe
cache.computeIfAbsent("user_1") { fetchUser() } // Atomic get-or-compute

val list = Collections.synchronizedList(mutableListOf<String>())

// Must manually synchronize the entire iteration block
synchronized(list) {
    for (item in list) { process(item) }
}

val listeners = CopyOnWriteArrayList<EventListener>()
listeners.forEach { it.onEvent(event) } // Safe to iterate
listeners.add(newListener)               // Safe to modify concurrently

The coroutine problem

val lock = Any()

suspend fun fetchAndUpdate() {
    synchronized(lock) {
        val data = api.fetchData() // ❌ Compile error
        updateState(data)
    }
}

Mutex : the coroutine-aware lock

val mutex = Mutex()
var count = 0

suspend fun increment() {
    mutex.withLock {
        count++
    }
}

val mutex = Mutex()

suspend fun fetchAndUpdate() {
    mutex.withLock {
        val data = api.fetchData() // suspend, totally safe
        updateState(data)
    }
}

class UserRepository {
    private val mutex = Mutex()
    private var cachedUser: User? = null

    suspend fun getUser(id: String): User {
        mutex.withLock {
            cachedUser?.let { return it }  // Return cached value if available
            val user = api.fetchUser(id)
            cachedUser = user
            return user
        }
    }
}

Actor + StateFlow : eliminating the concerns entirely

sealed class UserEvent {
    data class Load(val id: String) : UserEvent()
    object Refresh : UserEvent()
    object Logout : UserEvent()
}

class UserViewModel(private val repo: UserRepository) : ViewModel() {
    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    private val events = Channel<UserEvent>()

    init {
        viewModelScope.launch {
            for (event in events) { // Process one event at a time, no concurrency on state
                handleEvent(event)
            }
        }
    }

    fun onEvent(event: UserEvent) {
        viewModelScope.launch { events.send(event) }
    }

    private suspend fun handleEvent(event: UserEvent) {
        when (event) {
            is UserEvent.Load -> {
                _uiState.value = UiState.Loading
                _uiState.value = try {
                    UiState.Success(repo.getUser(event.id))
                } catch (e: Exception) {
                    UiState.Error(e.message)
                }
            }
            is UserEvent.Refresh -> { /* ... */ }
            is UserEvent.Logout -> { _uiState.value = UiState.LoggedOut }
        }
    }
}

// Send events in
binding.refreshButton.setOnClickListener {
    viewModel.onEvent(UserEvent.Refresh)
}

// Collect state out
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect { state ->
            when (state) {
                is UiState.Loading -> showLoading()
                is UiState.Success -> showUser(state.user)
                is UiState.Error -> showError(state.message)
                is UiState.LoggedOut -> navigateToLogin()
            }
        }
    }
}

_uiState.update { currentState ->
    if (currentState is UiState.Success) {
        currentState.copy(isRefreshing = true)
    } else {
        currentState
    }
}

Thread confinement : the structural version

val singleThread = Executors.newSingleThreadExecutor().asCoroutineDispatcher()

class LocalCache {
    private val data = mutableMapOf<String, String>() // No sync needed

    suspend fun put(key: String, value: String) = withContext(singleThread) {
        data[key] = value
    }

    suspend fun get(key: String): String? = withContext(singleThread) {
        data[key]
    }
}

Bringing it back

The reach order

StateFlow / ViewModel         ← First choice in most Android code
Actor / Thread confinement    ← When one owner should manage state exclusively
Mutex                         ← Coroutine-safe lock
ReentrantLock                 ← Non-coroutine lock with tryLock or timeouts
synchronized                  ← Simple non-coroutine critical sections
ConcurrentHashMap etc.        ← Thread-safe collections
Atomics                       ← Single-variable atomic operations
@Volatile                     ← Visibility only, simple flags

The real lesson

1. What can threads access here, and do they need the freshest value, a consistent snapshot, or both?

2. What can threads mutate here, and is it a single field or a group of related ones?

3. What can threads trigger here, and how many times should that thing happen?