From: Francis Dupont <fdupont@isc.org>
Date: Wed, 6 Nov 2019 13:08:26 +0000 (+0100)
Subject: [947-mt-compatibility-for-hooks] Checkpoint: hook library done, hooks to do
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d7ab1ea0d4d3abf1fca2f5252ee7c3d4c5570777;p=thirdparty%2Fkea.git

[947-mt-compatibility-for-hooks] Checkpoint: hook library done, hooks to do
---

diff --git a/src/lib/hooks/hooks.h b/src/lib/hooks/hooks.h
index 39b2e17b3b..aef2ebe3f1 100644
--- a/src/lib/hooks/hooks.h
+++ b/src/lib/hooks/hooks.h
@@ -12,8 +12,8 @@
 
 namespace {
 
-// Version 10 of the hooks framework, set for Kea 1.7.1
-const int KEA_HOOKS_VERSION = 11;
+// Version 10 of the hooks framework, set for Kea 1.7.2
+const int KEA_HOOKS_VERSION = 12;
 
 // Names of the framework functions.
 const char* const LOAD_FUNCTION_NAME = "load";
diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox
index b9da7552be..35cbf1faf8 100644
--- a/src/lib/hooks/hooks_user.dox
+++ b/src/lib/hooks/hooks_user.dox
@@ -262,15 +262,22 @@ erver multi-threading configuration. The value 0 means not compatible
 and is the default when the function is not implemented. not 0 values
 mean compatible.
 
+If your code implements it and returns the value 0 it is recommended
+to document the reason so someone revisiting the code will not by
+accident change the code.
+
 To be compatible means:
 - the code associated with DHCP packet processing callouts e.g.
-pkt4_receive or pkt6_send must be reentrant so the multi-threaded DHCP service
-can simultaneously calls more than once on of these callouts.
-- commands a library registers must be reentrant
-- when a library implements a backend API (e.g. host data source) the service
-methods must be reentrant
-- (shall be modified later) a library must not modify the internal
-configuration of the server, e.g. create or delete a subnet.
+pkt4_receive or pkt6_send must be thread safe so the multi-threaded
+DHCP service can simultaneously calls more than once on of these callouts.
+- commands a library registers are not required to be thread safe because
+commands are executed by the main thread. Now it is a good idea to make
+them thread safe and to document cases where they are not.
+- when a library implements a thread safe backend API (e.g. host data
+ource) the service methods must be thread safe.
+- a library which modifies the internal configuration of the server,
+e.g. create or delete a subnet, must enter a critical section using
+the @c isc::dhcp::MultiThreadingCriticalSection RAII class.
 
 In the tutoral, we'll put "multi_threading_compatible" in its own file,
 multi_threading_compatible.cc. The contents are:
@@ -287,6 +294,23 @@ int multi_threading_compatible() {
 }
 @endcode
 
+and for a command creating a new subnet:
+
+@code
+#include <dhcpsrv/multi_threading_utils.h>
+
+int commandHandler(CalloutHandle& handle) {
+    ...
+    {
+        // Enter the critical section.
+        MultiThreadingCriticalSection ct;
+        <add the subnet>
+        // Leave the critical section.
+    }
+    ...
+}
+@endcode
+
 @subsection hooksdgCallouts Callouts
 
 Having sorted out the framework, we now come to the functions that