[#1264] First attempt

diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox
index bdcd9093f448430b34da6d9acb5543ff2d5c2dc7..468108caa14f9f2e2c7a51d5dd48915dfaa88754 100644 (file)
--- a/src/lib/hooks/hooks_user.dox
+++ b/src/lib/hooks/hooks_user.dox
@@ -65,8 +65,10 @@ in the compiled version of the software, hence the need for a rebuild.
 
 The core of Kea is written in C++.  While it is the intention to
 provide interfaces into user code written in other languages, the initial
-versions of the Hooks system requires that user code be written in C++.
-All examples in this guide are in that language.
+versions of the Hooks system required that user code be written in C++.
+It is no longer the case and there are examples of hooks written for
+instance in Python but this guide does not document how to do that.
+All examples in this guide are in C++.
 
 
 @subsection hooksdgTerminology Terminology
@@ -1521,4 +1523,43 @@ which are dedicated to isc::data::Element testing and src/lib/hooks/tests/callou
 which is an example library used in testing. This library expects exactly 3 parameters:
 svalue (which is a string), ivalue (which is an integer) and bvalue (which is a boolean).
 
+@subsection hooksMultiThreading Multi-Threading Considations for Hooks Writers
+
+Multi-threading programming in C++ is not easy. For instance STL containers
+do not support simultaneous read and write accesses. Kea is written in C++
+so a priori for all Kea features one should never assume thread safety.
+
+This stands both for internal multi-threading inside a hook library or
+when a hook is called from a callout point in the multi-threaded packet
+processing. When the problem can't be solved the hook must be marked
+as not compatible with multi-threading.
+
+Some Kea APIs were made thread safe mainly because they are used by the
+packet processing:
+ - logging is thread safe and even multi process safe i.e. messages logged
+  into a file or by syslog from multiple processes do not mixed.
+ - statistics update is thread safe.
+ - lease and host database backends are thread safe. Note if you need to
+  perform a direct MySQL or PostgreSQL query you must use the connection pool.
+ - state model and watched thread are thread safe (libkea-util)
+ - interval timer setup and cancel are thread safe (libkea-asiolink)
+ - parking lots are thread safe (libkea-hooks)
+ - external sockets are thread safe (libkea-dhcp++)
+ - http client is thread safe (libkea-http)
+
+In some cases thread safety is not required for instance for the code which
+is executed by the main thread:
+ - (re)configuration is performed by the main thread with the packet
+  processing stopped
+ - io service (io context is recent boost versions) is polled by the main
+  thread
+ - external context callbacks are executed by the main thread
+Note in the last two cases the packet processing is not stopped: the
+external socket being thread safe only means one may at any moment for
+instance delete an external socket, not that the callback has an exclusive
+access to Kea internal objects.
+ 
+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.
+
 */