22 files changed, 371 insertions, 13 deletions

diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index fbde96d59e..c51eca4c97 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -108,7 +108,10 @@
  * - @subpage perfdhcpInternals
  *
  * @section libraries Kea libraries
+ * - @subpage libutil
+ * - @subpage libasiolink
  * - @subpage libcc
+ * - @subpage libdatabase
  * - @subpage libdhcp
  *   - @subpage libdhcpIntro
  *   - @subpage libdhcpRelay
@@ -116,6 +119,7 @@
  *   - @subpage libdhcpPktFilter
  *   - @subpage libdhcpPktFilter6
  *   - @subpage libdhcpErrorLogging
+ * - @subpage libstats
  * - @subpage libdhcp_ddns
  * - @subpage libdhcpsrv
  *   - @subpage leasemgr
@@ -132,6 +136,7 @@
  *   - @subpage cpl
  *   - @subpage cplSignals
  * - @subpage libyang
+ * - @subpage libhttp
  *
  * @section miscellaneousTopics Miscellaneous Topics
  * - @subpage terminology
diff --git a/src/lib/asiolink/Makefile.am b/src/lib/asiolink/Makefile.am
index 08e23db430..9729ad6fef 100644
--- a/src/lib/asiolink/Makefile.am
+++ b/src/lib/asiolink/Makefile.am
@@ -5,6 +5,8 @@ AM_CPPFLAGS += $(BOOST_INCLUDES)
 
 AM_CXXFLAGS = $(KEA_CXXFLAGS) -Wno-non-virtual-dtor
 
+EXTRA_DIST = asiolink.dox
+
 CLEANFILES = *.gcno *.gcda
 
 # This is a wrapper library.
diff --git a/src/lib/asiolink/asiolink.dox b/src/lib/asiolink/asiolink.dox
new file mode 100644
index 0000000000..09443f2b20
--- /dev/null
+++ b/src/lib/asiolink/asiolink.dox
@@ -0,0 +1,61 @@
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libasiolink libkea-asiolink - Kea Boost ASIO Library
+
+@section asiolinkUtilities Boost ASIO Utilities
+
+The asiolink library (libkea-asiolink) encapsulates Boost ASIO tools:
+
+ - addr utilities: prefix (IOAddress and length pair) tools.
+
+ - dummy I/O callback.
+
+ - interval timer.
+
+ - I/O acceptor: asynchronous server ASIO socket (base class).
+
+ - I/O address: ASIO IP address.
+
+ - I/O ASIO socket (derived from I/O socket).
+
+ - I/O endpoint: ASIO IP endpoint (abstraction of a socket address).
+
+ - I/O error: @c isc::asiolink::IOError exception declaration.
+
+ - I/O service: ASIO I/O service (named I/O context in recent versions).
+
+ - I/O socket: ASIO I/O socket base class.
+
+ - TCP acceptor: TCP derivation of I/O acceptor.
+
+ - TCP endpoint: TCP derivation of I/O endpoint.
+
+ - TCP socket: TCP derivation of I/O socket.
+
+ - UDP endpoint: UDP derivation of I/O endpoint.
+
+ - UDP socket: UDP derivation of I/O socket.
+
+ - Unix domain socket: Unix socket (AF_LOCAL) derivation of I/O socket.
+
+ - Unix domain acceptor: Unix socket (AF_LOCAL) derivation of I/O acceptor.
+
+ - Unix domain endpoint: Unix socket (AF_LOCAL) derivation of I/O endpoint.
+
+@section asiolinkMTConsiderations Multi-Threading Consideration for Boost ASIO Utilities
+
+By default Boost ASIO utilities are not thread safe even Boost ASIO tools
+themselves are. When there is no state and the encapsulation is direct
+the thread safety property is preserved. Exceptions to the by default
+no thread safe are:
+
+ - I/O address (direct encapsulation) is thread safe.
+
+ - interval timer setup and cancel methods are thread safe.
+
+*/
diff --git a/src/lib/cc/cc.dox b/src/lib/cc/cc.dox
index 2bce970923..223cc2790b 100644
--- a/src/lib/cc/cc.dox
+++ b/src/lib/cc/cc.dox
@@ -96,4 +96,12 @@ ParamsList is a simple vector<string>. There will be more specific
 methods implemented in the future, but for the time being only
 @ref isc::data::SimpleParser::deriveParams is implemented.
 
+@subsection ccMTConsiderations Multi-Threading Consideration for Configuration Utilities
+
+No configuration utility is thread safe. For instance stamped values are
+not thread safe so any read access must be done in a context where write
+access at the same time is not possible. Note that configuration is
+performed by the main thread with service threads stopped so this constraint
+is fulfilled.
+
 */
diff --git a/src/lib/config/command-socket.dox b/src/lib/config/command-socket.dox
index 4c3a23f051..8ee40f8361 100644
--- a/src/lib/config/command-socket.dox
+++ b/src/lib/config/command-socket.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2015-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2015-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -175,5 +175,14 @@ main loop must contain calls to @ref isc::asiolink::IOService::run or
 @ref isc::asiolink::IOService::poll or their variants to invoke Command
 Manager's handlers as required for processing control requests.
 
+@section ctrlSocketMTConsiderations Multi-Threading Consideration for Control Channel
+
+The control channel utilities are not thread safe but they are used only
+by the main thread so in most cases it does not matter. For instance
+the assumption that only at most one command can be executed at a given
+time can be done. Of course this has its limit: when the command changes
+the configuration or is incompatible with a simultaneous packet
+processing the multi-threading mode must be checked and service threads
+stopped.
 
 */
diff --git a/src/lib/database/Makefile.am b/src/lib/database/Makefile.am
index 1251bef127..f20a897b49 100644
--- a/src/lib/database/Makefile.am
+++ b/src/lib/database/Makefile.am
@@ -6,7 +6,7 @@ AM_CPPFLAGS += $(BOOST_INCLUDES)
 AM_CXXFLAGS = $(KEA_CXXFLAGS)
 
 # Ensure that the message file is included in the distribution
-EXTRA_DIST = db_messages.mes
+EXTRA_DIST = database.dox db_messages.mes
 
 CLEANFILES = *.gcno *.gcda
 
diff --git a/src/lib/database/database.dox b/src/lib/database/database.dox
new file mode 100644
index 0000000000..57d2fd7dc4
--- /dev/null
+++ b/src/lib/database/database.dox
@@ -0,0 +1,25 @@
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libdatabase libkea-database - Kea Database Library
+
+@section databaseMTConsiderations Multi-Threading Consideration for Database
+
+MySQL and PostgreSQL provide connection pools which is used to make
+lease, host and legal log backends thread safe. Cassandra/CQL is
+thread safe by design.
+
+MySQL and PostgreSQL are inter-process safe only when transactions are used
+(including the MySQL auto-transaction mode which includes queries into
+a transaction). For MySQL this means that transactions must be supported
+by the database engine (the engine selection is done in the schema).
+
+Note the InnoDB engine used by Kea for MySQL databases cancels a transaction
+when a deadlock is detected (rare but possible event) and leaves the charge
+to retry the transaction to the caller.
+
+*/
diff --git a/src/lib/dhcp/libdhcp++.dox b/src/lib/dhcp/libdhcp++.dox
index 08f279e6f1..bd42ee5b1f 100644
--- a/src/lib/dhcp/libdhcp++.dox
+++ b/src/lib/dhcp/libdhcp++.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -260,4 +260,18 @@ error string as an argument. The handler function may use its logging
 mechanism to log this error message. In particular, the DHCP server
 will use BINDX logger to log the error message.
 
+@section libdhcpMTConsiderations Multi-Threading Consideration for DHCP library
+
+By default APIs provided by the DHCP library are not thread safe.
+For instance packets or options are not thread safe. Exception are:
+
+ - external sockets are thread safe (the container used to manage external
+  socket is thread safe so one can for instance delete an external socket
+  at any time).
+
+ - interface send method is thread safe (mainly because it does not change
+  any internal state).
+
+ - packet queue ring is thread safe.
+
 */
diff --git a/src/lib/dhcp_ddns/libdhcp_ddns.dox b/src/lib/dhcp_ddns/libdhcp_ddns.dox
index c03e30c778..c285fd8f6c 100644
--- a/src/lib/dhcp_ddns/libdhcp_ddns.dox
+++ b/src/lib/dhcp_ddns/libdhcp_ddns.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -51,4 +51,11 @@ and isc::dhcp_ddns::NameChangeUDPListener.  The implementation is strictly
 unidirectional: there is no explicit acknowledgment of receipt of a
 request so, as it is UDP, no guarantee of delivery.
 
+@section libdhcp_ddnsMTConsiderations Multi-Threading Consideration for DHCP_DDNS Request I/O Library
+
+By default this library is not thread safe (it uses asynchronous I/O) at
+the exception of the Name Change Request sender class (@c
+isc::dhcp_ddns::NameChangeSender) which is Kea thread safe (i.e. it is
+thread safe when the multi-threading mode is true).
+
 */
diff --git a/src/lib/dhcpsrv/database_backends.dox b/src/lib/dhcpsrv/database_backends.dox
index efe1171059..0a9897f82c 100644
--- a/src/lib/dhcpsrv/database_backends.dox
+++ b/src/lib/dhcpsrv/database_backends.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2019 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -198,4 +198,28 @@
   this property should not be used because it limits negative cache
   addition to only be performed by the host manager.
 
+@section dhcpDatabaseBackendsMTConsiderations Multi-Threading Consideration for DHCP Database Backends
+
+Lease and host database backends including the memfile for leases are Kea
+(i.e. when the multi-threading mode is true) thread safe. This extends
+to legal / forensic log backends but not to config backends which is
+used only for configuration by the main thread with packet processing
+threads stopped so has no thread safety requirements.
+
+There are exceptions:
+
+ - memfile constructor (including loading of leases from files) is not
+  thread safe.
+
+ - lfc handling in memfile is not thread safe: instead it is required
+  to be called from the main thread.
+
+ - wipe lease methods are either not thread safe or not implemented.
+
+Note for statistics queries it does not make sense to call them with
+running packet processing threads so they have no thread safety guarantees.
+
+Note too the memfile backend is not inter-process safe so must be kept
+private to the Kea server using it.
+
   */
diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox
index 3ab8e354f9..6024ae6590 100644
--- a/src/lib/dhcpsrv/libdhcpsrv.dox
+++ b/src/lib/dhcpsrv/libdhcpsrv.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2018 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -461,5 +461,21 @@ is used by DHCPv4 and DHCPv6 components.
 
 DHCPv4-over-DHCPv6 which are relayed by a DHCPv6 relay are not yet supported.
 
+@section libdhcpsrvMTConsiderations Multi-Threading Consideration for Server DHCP Library
+
+Note that for backends specific consideration is in @ref
+dhcpDatabaseBackendsMTConsiderations.
+
+Below Kea thread safe means thread safe when the multi-threading mode is
+true (when it is false packets are processed by the main thread).
+
+By default this library is not thread safe, in particular all classes used
+for configuration are not thread safe. Exceptions are:
+
+ - allocation engine allocator is Kea thread safe.
+
+ - resource handler is thread safe.
+
+ - last allocated members of subnets are Kea thread safe.
 
 */
diff --git a/src/lib/eval/eval.dox b/src/lib/eval/eval.dox
index bb7e1ff178..066f1a9320 100644
--- a/src/lib/eval/eval.dox
+++ b/src/lib/eval/eval.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2015-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -176,4 +176,10 @@ instantiated with the appropriate value and put onto the expression vector.
 
 More operators are expected to be implemented in upcoming releases.
 
+@section dhcpEvalMTConsiderations Multi-Threading Consideration for Expression Evaluation Library
+
+This library is not thread safe, for instance @ref isc::dhcp::evaluateBool
+or @ref isc::dhcp::evaluateString must not be called in different threads
+on the same packet.
+
 */
diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox
index d7d2cc6b10..55096ecf1a 100644
--- a/src/lib/hooks/hooks_user.dox
+++ b/src/lib/hooks/hooks_user.dox
@@ -1649,7 +1649,22 @@ Some other Kea APIs are intrinsically thread safe because they do not
 involve a shared structure so for instance despite of its name the
 interface manager send methods are generic thread safe.
 
-Per library documentation will be updated to detail thread safety to help
-hooks writers and to provide an exhaustive list of Kea thread safe APIs.
+Per library documentation details thread safety to help hooks writers
+and to provide an exhaustive list of Kea thread safe APIs:
+ - @ref utilMTConsiderations
+ - @ref logMTConsiderations
+ - @ref asiolinkMTConsiderations
+ - @ref ccMTConsiderations
+ - @ref databaseMTConsiderations
+ - @ref ctrlSocketMTConsiderations
+ - @ref libdhcpMTConsiderations
+ - @ref statsMTConsiderations
+ - @ref yangMTConsiderations
+ - @ref libdhcp_ddnsMTConsiderations
+ - @ref dhcpEvalMTConsiderations
+ - @ref cplMTConsiderations
+ - @ref dhcpDatabaseBackendsMTConsiderations
+ - @ref libdhcpsrvMTConsiderations
+ - @ref httpMTConsiderations
 
 */
diff --git a/src/lib/http/Makefile.am b/src/lib/http/Makefile.am
index a658b66f95..d16794f22b 100644
--- a/src/lib/http/Makefile.am
+++ b/src/lib/http/Makefile.am
@@ -4,8 +4,10 @@ AM_CPPFLAGS  = -I$(top_builddir)/src/lib -I$(top_srcdir)/src/lib
 AM_CPPFLAGS += $(BOOST_INCLUDES)
 AM_CXXFLAGS  = $(KEA_CXXFLAGS)
 
+EXTRA_DIST = http.dox
+
 # Ensure that the message file is included in the distribution
-EXTRA_DIST = http_messages.mes
+EXTRA_DIST += http_messages.mes
 
 CLEANFILES = *.gcno *.gcda
 
diff --git a/src/lib/http/http.dox b/src/lib/http/http.dox
new file mode 100644
index 0000000000..4636a7401a
--- /dev/null
+++ b/src/lib/http/http.dox
@@ -0,0 +1,24 @@
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libhttp libkea-http - Kea HTTP Library
+
+@section httpMTConsiderations Multi-Threading Consideration for HTTP Library
+
+By default this library is not thread safe, for instance HTTP listeners
+and HTTP messages are not thread safe. Exceptions are:
+
+ - HTTP client is Kea (i.e. when the multi-threading mode is treu)
+  thread safe.
+
+ - date time is thread safe (mainly because its encapsulated POSIX time
+  is private and read-only, or because all methods are instance const methods
+  or class methods).
+
+ - URL is thread safe (all public methods are const methods).
+
+*/
diff --git a/src/lib/log/logging.dox b/src/lib/log/logging.dox
index 1ccc5db2c4..b0e990e7bc 100644
--- a/src/lib/log/logging.dox
+++ b/src/lib/log/logging.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2019 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -682,4 +682,17 @@ loggers.  As the loggers are independent and the severity levels
 independent, fine-tuning of what and what is not recorded can be achieved.</li>
 
 </ol>
+
+@section logMTConsiderations Multi-Threading Consideration for Logging
+
+Logging is thread safe: messages emitted at the same time do not mix.
+
+When the KEA_LOCKFILE_DIR environment variable is not set to none
+Logging to files is multi-process safe too: for instance two servers
+can be configured to put log messages in the same file.
+
+The @c isc::log::Logger class initializes its implementation in a lazy
+(i.e. on demand) but thread safe way so it is always initialized at most
+once even in a multi-threaded environment.
+
 */
diff --git a/src/lib/process/libprocess.dox b/src/lib/process/libprocess.dox
index ff2056fbdc..d8cedec681 100644
--- a/src/lib/process/libprocess.dox
+++ b/src/lib/process/libprocess.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2016-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2016-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -173,4 +173,9 @@ during startup and the subsequent receipt of a SIGHUP:
 
 @image html cpl_signal_sequence.svg "CPL Signal Handling Sequence"
 
+@section cplMTConsiderations Multi-Threading Consideration for Controllable Process Layer
+
+By default this library is not thread safe and currently there is no known
+exception.
+
 */
diff --git a/src/lib/stats/Makefile.am b/src/lib/stats/Makefile.am
index d58ad2c422..b995658a81 100644
--- a/src/lib/stats/Makefile.am
+++ b/src/lib/stats/Makefile.am
@@ -17,6 +17,8 @@ libkea_stats_la_LIBADD += $(top_builddir)/src/lib/util/libkea-util.la
 libkea_stats_la_LIBADD += $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
 libkea_stats_la_LIBADD += $(BOOST_LIBS)
 
+EXTRA_DIST = stats.dox
+
 libkea_stats_includedir = $(pkgincludedir)/stats
 libkea_stats_include_HEADERS = \
 	context.h \
diff --git a/src/lib/stats/stats.dox b/src/lib/stats/stats.dox
new file mode 100644
index 0000000000..7d4d3b5a48
--- /dev/null
+++ b/src/lib/stats/stats.dox
@@ -0,0 +1,16 @@
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libstats libkea-stats - Kea Statistics Library
+
+@section statsMTConsiderations Multi-Threading Consideration for Statistics
+
+The statistic manager (@c isc::stats::StatsMgr singleton) is Kea thread safe
+i.e. it is thread safe when the multi-threading mode is true (when the
+multi-threading mode is false Kea main thread processes packets).
+
+*/
diff --git a/src/lib/util/Makefile.am b/src/lib/util/Makefile.am
index 331d52abd6..14319e9e9d 100644
--- a/src/lib/util/Makefile.am
+++ b/src/lib/util/Makefile.am
@@ -48,6 +48,8 @@ libkea_util_la_LIBADD = $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
 
 libkea_util_la_LDFLAGS  = -no-undefined -version-info 14:0:0
 
+EXTRA_DIST = util.dox
+
 CLEANFILES = *.gcno *.gcda
 
 # Specify the headers for copying into the installation directory tree.
diff --git a/src/lib/util/util.dox b/src/lib/util/util.dox
new file mode 100644
index 0000000000..8a38e7bb8b
--- /dev/null
+++ b/src/lib/util/util.dox
@@ -0,0 +1,96 @@
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libutil libkea-util - Kea Utilities Library
+
+@section utilUtilities Utilities
+
+The utilities library (libkea-util) provides generic and Kea utilities:
+
+ - boost time: boost Posix time and duration to text conversions.
+
+ - buffer (header only): input and output buffers.
+
+ - csv file: comma-separated values (CSV) files.
+
+ - double: test utility for checking double equivalence (vs. strict
+  equality).
+
+ - encode: base16, base32, base64 and hexadecimal conversions.
+
+ - filename: filename manipulation (avoid dependency on boost).
+
+ - hash: Fowler-Noll-Vo 64 bit hash function.
+
+ - io: test utils for file descriptors and sockets.
+
+ - io utilities (header only): reads and writes integers from / to buffers.
+
+ - labeled values: labeled constants and label constant sets.
+
+ - multi threading manager (in the util library to be available in the
+  whole Kea code).
+
+ - optional: optional values.
+
+ - pid file: process id files.
+
+ - pointer util: test utility to compare smart pointers.
+
+ - process spawn.
+
+ - random: pseudo-random number generator for query ids (please use
+  the cryptolink random generator when security matters).
+
+ - range utilities.
+
+ - read-write mutex (header only).
+
+ - signal set: signal handling (please @c isc::process::IOSignalSet instead).
+
+ - staged values.
+
+ - state model: event-driven deterministic finite state automaton
+  (to accept a regular language).
+
+ - stop watch: to measure code execution time.
+
+ - string util: various string common tools.
+
+ - thread pool.
+
+ - time utilities: DNSSEC time conversions from and to text.
+
+ - unittests (directory): tools for google test unit tests.
+
+ - unlock guard: RAII helper to unlock a mutex in a limited scope.
+
+ - versioned csv file: csv files with multiple versions of file schema.
+
+ - watched socket (required as select() or poll() do not support condition
+  variables).
+
+ - watched threads: threads using ready, error and terminate watched socket.
+
+@section utilMTConsiderations Multi-Threading Consideration for Utilities
+
+By default utilities are not thread safe, for instance CSV files and
+qid random generators are not thread safe. Exceptions are:
+
+ - multi threading manager is thread safe.
+
+ - read-write mutex is thread safe.
+
+ - state model is thread safe.
+
+ - thread pool is thread safe.
+
+ - unlock guard is thread safe.
+
+ - watched threads are thread safe.
+
+*/
diff --git a/src/lib/yang/yang.dox b/src/lib/yang/yang.dox
index d2ee88e970..57959a1f47 100644
--- a/src/lib/yang/yang.dox
+++ b/src/lib/yang/yang.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
+K// Copyright (C) 2018-2020 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -181,4 +181,10 @@ to verify that your environment is ready. If there is anything
 wrong, it will enumerate the problems and will suggest how to solve
 them.
 
+@section yangMTConsiderations Multi-Threading Consideration for YANG Utilities
+
+The YANG utilities are not thread safe. Note as they are used only in a
+configuration context it is not a problem, and the yang / sysrepo libraries
+are multi-threaded so their APIs are thread safe.
+
 */