docs: better call out temporally overlapping usage is not allowed

Related to #182.

Author: indygreg

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

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