doc: The same JSON values must not be encoded in parallel

Closes GH-42.

diff --git a/doc/portability.rst b/doc/portability.rst
index 0a49e2e..dc6c5eb 100644 (file)
--- a/doc/portability.rst
+++ b/doc/portability.rst
@@ -20,6 +20,16 @@ such values, as containers manage the reference count of their
 contained values. Bugs involving concurrent incrementing or
 decrementing of deference counts may be hard to track.
 
 contained values. Bugs involving concurrent incrementing or
 decrementing of deference counts may be hard to track.
 

+The encoding functions (:func:`json_dumps()` and friends) track
+reference loops by modifying the internal state of objects and arrays.
+For this reason, encoding functions must not be run on the same JSON
+values in two separate threads at the same time. As already noted
+above, be especially careful if two arrays or objects share their
+contained values with another array or object.
+
+If you want to make sure that two JSON value hierarchies do not
+contain shared values, use :func:`json_deep_copy()` to make copies.
+

 Locale
 ------
 
 Locale
 ------