问题现象与影响
在streamlit应用中，开发者经常需要处理大量数据，并希望通过进度条向用户展示操作进度。stqdm库提供了一个极佳的解决方案，它能将tqdm的进度条无缝集成到streamlit界面中，尤其是在与pandas的apply或progress_apply方法结合使用时。然而，一个常见且令人头疼的问题是，当使用stqdm.pandas.progress_apply执行耗时操作时，如果用户在操作完成前关闭浏览器标签页、刷新应用或streamlit服务意外中断，应用程序可能会在下次运行时陷入无限循环或完全冻结，唯一的解决办法往往是重启streamlit服务。
考虑以下代码示例，它模拟了一个耗时的数据帧操作：
import streamlit as st
from time import sleep
import pandas as pd
import numpy as np
from stqdm import stqdm
def something_heavy(x):
"""模拟一个耗时操作"""
sleep(1) # 暂停1秒
return x * 100
# 创建一个示例DataFrame
df = pd.DataFrame(np.random.randint(0, 100, size=(10, 2)), columns=list('AB'))
# 注册stqdm到pandas，并显示进度条
stqdm.pandas(desc='正在执行繁重操作')
df['C'] = df.progress_apply(lambda row: something_heavy(row['A']), axis=1)
st.write(df)
当上述代码运行时，进度条会正常显示。但如果在df.progress_apply完成之前，Streamlit应用被中断，例如关闭浏览器窗口，那么在下次尝试运行该应用时，它很可能会卡住，无法继续执行。
问题根源分析
根据社区讨论，此问题主要与Streamlit和tqdm（以及stqdm作为其Streamlit封装）之间的锁定机制冲突有关。具体来说，当progress_apply操作在多线程或多进程环境下执行时，如果其内部的锁（lock）没有被正确释放或处理，并在意外中断后保持一个不一致的状态，那么在应用下次启动时，可能会因为尝试获取一个已被锁住但又无法释放的资源而导致死锁或冻结。这种现象在Windows操作系统上尤为常见。
解决方案：引入可重入锁
解决此问题的关键在于替换stqdm内部使用的默认锁机制，引入一个可重入锁（Reentrant Lock, RLock）。RLock允许同一个线程多次获取同一个锁，而不会导致死锁，只要每次获取都对应一次释放。这在某些复杂的并发场景中可以避免因自身尝试获取已持有的锁而导致的阻塞。虽然此问题的根本原因可能更为复杂，但使用RLock作为stqdm的锁机制，能够有效规避因中断导致的状态不一致问题。
下载 Comet AI 浏览器，体验由 Perplexity AI 驱动的革命性上网方式。内置 AI 助手可实时总结网页、跨标签页对比信息、自动执行任务。告别繁琐操作，让 AI 成为你的浏览副驾，大幅提升研究与工作效率。支持 Windows、macOS、Android 和 iOS。
要应用此解决方案，只需在Streamlit脚本的开头，导入RLock并将其设置为stqdm的锁。
代码实践
以下是应用解决方案后的代码示例：
import streamlit as st
from time import sleep
import pandas as pd
import numpy as np
from stqdm import stqdm
from threading import RLock # 导入RLock
# 在脚本开头设置stqdm的锁为RLock
stqdm.set_lock(RLock())
def something_heavy(x):
"""模拟一个耗时操作"""
sleep(1) # 暂停1秒
return x * 100
# 创建一个示例DataFrame
df = pd.DataFrame(np.random.randint(0, 100, size=(10, 2)), columns=list('AB'))
# 注册stqdm到pandas，并显示进度条
stqdm.pandas(desc='正在执行繁重操作')
df['C'] = df.progress_apply(lambda row: something_heavy(row['A']), axis=1)
st.write(df)
通过在脚本顶部添加 from threading import RLock 和 stqdm.set_lock(RLock()) 这两行代码，即使在progress_apply执行过程中应用被中断，下次运行时也能正常启动，避免了冻结问题。
注意事项
- 放置位置： 务必将 stqdm.set_lock(RLock()) 放在Streamlit脚本的顶部，在任何可能调用 stqdm 或 stqdm.pandas 之前。这是为了确保在stqdm初始化其内部锁机制时，就使用我们指定的RLock。
- 平台差异： 尽管此问题在Windows系统上更为突出，但为了应用的健壮性，建议在所有部署环境中都采用此解决方案。
- 理解RLock： RLock是Python threading模块中的一个同步原语，它是一个可重入的互斥锁。这意味着同一个线程可以多次获取同一个RLock而不会死锁，但每次获取都必须有对应的释放操作。在这种特定情况下，它似乎能够更好地处理stqdm在Streamlit环境下的中断和恢复。
总结
stqdm库为Streamlit应用带来了极佳的用户体验，但在处理长时间运行的Pandas操作时，其与Streamlit的集成可能会在应用意外中断后导致冻结问题。通过在脚本开头简单地设置stqdm.set_lock(RLock())，我们可以有效地规避这一问题，确保Streamlit应用的稳定性和可靠性。这是一个简单而强大的修复，对于任何在Streamlit中使用stqdm.pandas的开发者来说都至关重要。
