add some doc on thread safety

diff --git a/doc/manual.rst b/doc/manual.rst
index ecf416732b3b25592de228c6921b4cc496af685f..0ebbd03cc319e605ddaef315304b48def13dc5bf 100644 (file)
--- 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 (file)
index 0000000..670fb54
--- /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.