From 1688c020716da20df1ef622bfd99367be58e995d Mon Sep 17 00:00:00 2001 From: Nathan Goldbaum Date: Thu, 21 May 2026 10:38:17 -0600 Subject: [PATCH] Add readme section on thread safety --- README.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.rst b/README.rst index e28c3a8..9fe84a4 100644 --- a/README.rst +++ b/README.rst @@ -261,6 +261,25 @@ and `bitrate_mode` is 'VARIABLE', 'CONSTANT', or 'AVERAGE'. # minimum mp3 compression results in 3.5 Mb file sf.write('min_compression_vbr.mp3', data, samplerate, bitrate_mode='VARIABLE', compression_level=0) +Thread Safety +------------- + +The ``soundfile`` module is a thin wrapper around the low-level ``libsndfile`` C +library. As such, ``soundfile`` provides the same thread safety guarantees as +the underlying C library. See `this libsndfile issue +`_ for more details. + +In short, multithreaded use is safe as long as handles for readers or writers +are not shared between threads. It is safe to concurrently open and read the +same file through unique per-thread handles. It is not safe to concurrently +write to the same file or share reader or writer handles. You may see garbage +results or crashes if you do this. + +See the advice in the Free-threaded Python guide on `thread-safe Python +programming +`_ +for suggestions on how to synchronize access to a thread-unsafe object. + Known Issues ------------