From 31c71ecb42a6dca595ad8804985fd058761bd883 Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Sun, 10 Oct 2021 15:15:14 -0700 Subject: add some doc on thread safety --- doc/manual.rst | 1 + doc/threads.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 doc/threads.rst (limited to 'doc') diff --git a/doc/manual.rst b/doc/manual.rst index ecf4167..0ebbd03 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 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. -- cgit v1.2.1