From: Bob Halley <halley@dnspython.org>
Date: Sun, 10 Oct 2021 22:15:14 +0000 (-0700)
Subject: add some doc on thread safety
X-Git-Tag: v2.2.0rc1~57
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=31c71ecb42a6dca595ad8804985fd058761bd883;p=thirdparty%2Fdnspython.git

add some doc on thread safety
---

diff --git a/doc/manual.rst b/doc/manual.rst
index ecf41673..0ebbd03c 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -16,3 +16,4 @@ Dnspython Manual
    exceptions
    utilities
    typing
+   threads
diff --git a/doc/threads.rst b/doc/threads.rst
new file mode 100644
index 00000000..670fb54f
--- /dev/null
+++ b/doc/threads.rst
@@ -0,0 +1,30 @@
+.. _threads:
+
+Using Dnspython with Threads
+----------------------------
+
+The dnspython ``Name`` and ``Rdata`` types are immutable, and thus thread-safe.
+
+Container objects like ``Message``, ``Node``, ``Rdataset``, ``RRset``,
+and ``Zone`` are not thread-safe, as they are mutable and not locked.
+It is up to the caller to ensure safety if they are shared between
+threads.
+
+The ``VersionedZone``, however, is thread-safe.  VersionedZones offer 
+read-only and read-write transactions.  Read-only transactions access an
+immutable version, and all the objects returned, including containers, are
+immutable.  Read-write transactions are only visible to their creator until
+they are committed.  Transaction creation and commit are thread-safe.
+Transaction objects should not be shared between threads.
+
+The ``Resolver`` is not thread-safe with regards to configuration, but it is
+safe for many threads to call the ``resolve()`` method of a resolver.
+The cache implementations for the resolver are also thread-safe, so if a
+web-crawling application associates an ``LRUCache`` with a Resolver, it will
+be safe to have many crawler threads doing resolutions.
+
+The ``dns.query`` methods are also thread-safe.  One caveat with these
+functions is that if a socket or other context (e.g. a Requests
+session or an SSL context) is passed to the function instead of
+allowing the function to create it, then it is up to the application to
+ensure thread safety if the context could be used by multiple threads.