From: Evan Hunt <each@isc.org>
Date: Fri, 28 May 2021 20:47:59 +0000 (-0700)
Subject: document isc__trampoline
X-Git-Tag: v9.17.17~25^2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4f6e2317e91a239decd0819047f7b344e1605701;p=thirdparty%2Fbind9.git

document isc__trampoline

Added some header file documentation to the isc__trampoline
implementation in trampoline_p.h.
---

diff --git a/lib/isc/trampoline_p.h b/lib/isc/trampoline_p.h
index 12bc6ad0e71..910fdd34bd9 100644
--- a/lib/isc/trampoline_p.h
+++ b/lib/isc/trampoline_p.h
@@ -13,6 +13,30 @@
 
 #include <isc/thread.h>
 
+/*! \file isc/trampoline_p.h
+ * \brief isc__trampoline: allows safe reuse of thread ID numbers.
+ *
+ * The 'isc_hp' hazard pointer API uses an internal thread ID
+ * variable ('tid_v') that is incremented for each new thread that uses
+ * hazard pointers. This thread ID is then used as an index into a global
+ * shared table of hazard pointer state.
+ *
+ * Since the thread ID is only incremented and never decremented, the
+ * table can overflow if threads are frequently created and destroyed.
+ *
+ * A trampoline is a thin wrapper around any function to be called from
+ * a newly launched thread. It maintains a table of thread IDs used by
+ * current and previous threads; when a thread is destroyed, its slot in
+ * the trampoline table becomes available, and the next thread to occupy
+ * that slot can use the same thread ID that its predecessor did.
+ *
+ * The trampoline table initially has space for 64 worker threads in
+ * addition to the main thread. if more threads than that in concurrent
+ * concurrently, the table is reallocated with twice as much space.
+ * (Note that the number of concurrent threads is currently capped at
+ * 128 by the queue and hazard pointer implementations.)
+ */
+
 typedef struct isc__trampoline isc__trampoline_t;
 
 void