From 8a5c0e6df2f0766bee847d3ce1134d7c9baac074 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Thu, 9 Mar 2023 19:28:39 +0000 Subject: doc: technical: document weird stuff in our codebase Hopefully this makes things less surprising to new hackers. --- Documentation/technical/weird-stuff.txt | 22 ++++++++++++++++++++++ MANIFEST | 1 + 2 files changed, 23 insertions(+) create mode 100644 Documentation/technical/weird-stuff.txt diff --git a/Documentation/technical/weird-stuff.txt b/Documentation/technical/weird-stuff.txt new file mode 100644 index 00000000..0c8d6891 --- /dev/null +++ b/Documentation/technical/weird-stuff.txt @@ -0,0 +1,22 @@ +There's a lot of weird code in public-inbox which may be daunting +to new hackers. + +* The event loop (PublicInbox::DS) is an evolution of a fairly standard + C10K event loop. See ds.txt in this directory for more. + +Things got weirder in 2021: + +* The lei command-line tool is backed by a daemon. This was done to + improve startup time for shell completion and manage git/SQLite/Xapian + single-writer during long, parallel imports. It may eventually become + a read-write IMAP/JMAP server. + +* SOCK_SEQPACKET is used extensively in lei, and will likely make its + way into more places, still. + +And even more so in 2022: + +* public-inbox-clone / PublicInbox::LeiMirror relies on ->DESTROY + for make-like dependency management while providing parallelism. + +More to come, lei will expose Maildirs via FUSE 3... diff --git a/MANIFEST b/MANIFEST index 7437bb54..bc652e21 100644 --- a/MANIFEST +++ b/MANIFEST @@ -99,6 +99,7 @@ Documentation/standards.perl Documentation/technical/data_structures.txt Documentation/technical/ds.txt Documentation/technical/memory.txt +Documentation/technical/weird-stuff.txt Documentation/technical/whyperl.txt Documentation/txt2pre HACKING -- cgit v1.2.3-24-ge0c7