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.
 
+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
 ------