diff --git a/docs/api_usage.rst b/docs/api_usage.rst index 0a0e3f68..a634f43a 100644 --- a/docs/api_usage.rst +++ b/docs/api_usage.rst @@ -88,8 +88,14 @@ There is potential for long pauses as data is read or written from the underlying stream (say from interacting with a filesystem or network). This could add considerable overhead. -Thread Safety -============= +Thread and Object Reuse Safety +============================== + +Unless stated otherwise, ``ZstdCompressor`` and ``ZstdDecompressor`` instances +cannot be used for temporally overlapping (de)compression operations. i.e. +if you start a (de)compression operation on an instance or a helper object +derived from it, it isn't safe to start another (de)compression operation +from the same instance until the first one has finished. ``ZstdCompressor`` and ``ZstdDecompressor`` instances have no guarantees about thread safety. Do not operate on the same ``ZstdCompressor`` and diff --git a/zstandard/backend_cffi.py b/zstandard/backend_cffi.py index f03bbcd5..fca2cfc0 100644 --- a/zstandard/backend_cffi.py +++ b/zstandard/backend_cffi.py @@ -1751,6 +1751,16 @@ class ZstdCompressor(object): ``write_checksum``, ``write_content_size``, ``write_dict_id``, and ``threads``. + Assume that each ``ZstdCompressor`` instance can only handle a single + logical compression operation at the same time. i.e. if you call a method + like ``stream_reader()`` to obtain multiple objects derived from the same + ``ZstdCompressor`` instance and attempt to use them simultaneously, errors + will likely occur. + + If you need to perform multiple logical compression operations and you + can't guarantee those operations are temporally non-overlapping, you need + to obtain multiple ``ZstdCompressor`` instances. + Unless specified otherwise, assume that no two methods of ``ZstdCompressor`` instances can be called from multiple Python threads simultaneously. In other words, assume instances are not thread safe @@ -3645,6 +3655,16 @@ class ZstdDecompressor(object): The interface of this class is very similar to :py:class:`zstandard.ZstdCompressor` (by design). + Assume that each ``ZstdDecompressor`` instance can only handle a single + logical compression operation at the same time. i.e. if you call a method + like ``decompressobj()`` to obtain multiple objects derived from the same + ``ZstdDecompressor`` instance and attempt to use them simultaneously, errors + will likely occur. + + If you need to perform multiple logical decompression operations and you + can't guarantee those operations are temporally non-overlapping, you need + to obtain multiple ``ZstdDecompressor`` instances. + Unless specified otherwise, assume that no two methods of ``ZstdDecompressor`` instances can be called from multiple Python threads simultaneously. In other words, assume instances are not thread safe