Start describing design considerations for the startup (and teardown) order

1 files changed, 23 insertions, 0 deletions

diff --git a/DESIGN b/DESIGN
index f058fe0..eb5d1e1 100644
--- a/DESIGN
+++ b/DESIGN
@@ -81,6 +81,29 @@ finish a sweep in OT_CLEAN_INTERVAL_MINUTES. At the default bucket count that
 is one bucket every 117 ms.
 
 
+Startup and teardown order
+--------------------------
+
+Nothing that consults the access list runs before the list has been read.
+The loader used to do its first read inside its own thread, so whatever ran
+next saw an empty list: a state file read with -l was checked against it and
+a blacklist build restored torrents it should have refused, a whitelist build
+restored none at all. Announces arriving in the same window went the same
+way, 3089 of them refused over 373 ms against a two million entry whitelist.
+The first read is therefore synchronous in accesslist_init, and the thread
+only handles reloads.
+
+Teardown stops the cleaner first. It is the one worker that calls into other
+modules, accesslist_cleanup and stats_cleanup, so stopping it after them left
+it locking a mutex accesslist_deinit had already destroyed: five shutdowns in
+sixty at a bucket count low enough to make the window easy to hit.
+
+Signal handlers are installed before the first thread exists. A thread
+created earlier runs with whatever disposition a signal still has, and
+SIGUSR1, the one that wakes a blocked worker, terminates a process by
+default.
+
+
 Paths not taken
 ---------------