Configuring Session-State Updates for Concurrent Requests in Streamlit

Answer

The safest and most reliable approach is to use a single global lock that guards every mutation of st.session_state. This guarantees atomicity across all keys and prevents race conditions when multiple browser tabs issue concurrent requests.

Why a global lock?

• Streamlit runs user code in a single thread per session, but HTTP requests from different tabs can trigger parallel Python threads. The GIL does not protect the shared in‑memory dictionary.
• A global lock is simple to implement and hard to misuse; it eliminates the risk of subtle deadlocks that can arise with per‑key locks.
• Fine‑grained locks only reduce contention if every access pattern is coordinated. In practice, most apps modify several keys in a single request, so the benefit is minimal.

Implementation sketch

# lock.py
import threading
session_lock = threading.RLock()

# app.py
import streamlit as st
from lock import session_lock

with session_lock:
    # read or write session_state
    st.session_state.counter = st.session_state.get("counter", 0) + 1
    st.write("Counter:", st.session_state.counter)

Use a context manager (the with statement) so the lock is always released, even if an exception occurs.

Verification steps

1. Baseline latency: Open two tabs, click a button that increments a counter, and note the response times.
2. Add the global lock as above.
3. Repeat the test and compare the timings. The latency spikes caused by competing updates should disappear.
4. Insert time.time() prints before and after the with session_lock block to confirm that no two threads overlap inside the critical section.
5. Optionally, add a health‑check page that shows session_lock.locked() and the number of waiting threads via threading.active_count() to monitor contention.

When to consider per‑key locks

If profiling shows the global lock is a bottleneck and you have well‑understood, independent key access patterns, you can switch to per‑key locks. In that case:

• Maintain a lock dictionary: key_locks = defaultdict(threading.RLock).
• Always acquire locks in a consistent key order to avoid deadlocks.
• Never hold a key lock while performing I/O or long computations.

However, for most Streamlit apps a global lock is sufficient and far less error‑prone.