various doc updates ahead of 1.5.0

[public-inbox.git] / Documentation / technical / data_structures.txt

diff --git a/Documentation/technical/data_structures.txt b/Documentation/technical/data_structures.txt
index 4de83a77b44d377c7f1a82c25664c4a08a533237..8776a67b969500db69bd858ef9e7da214f7d0566 100644 (file)
--- a/Documentation/technical/data_structures.txt
+++ b/Documentation/technical/data_structures.txt
@@ -28,14 +28,13 @@ Outside of tests, this is typically a singleton.
 Per-message classes
 -------------------
 
-* PublicInbox::MIME - Email::MIME subclass
-  Common abbreviation: $mime
+* PublicInbox::Eml - Email::MIME-like class
+  Common abbreviation: $mime, $eml
   Used by: PublicInbox::WWW, PublicInbox::SearchIdx
 
-  An representation of an entire email, multipart or not.  It's
-  a subclass of Email::MIME to workaround bugs in old
-  Email::MIME versions.  An option to use libgmime or libmailutils
-  may be supported in the future for performance and memory use.
+  An representation of an entire email, multipart or not.
+  An option to use libgmime or libmailutils may be supported
+  in the future for performance and memory use.
 
   This can be a memory hog with big messages and giant
   attachments, so our PublicInbox::WWW interface only keeps
@@ -47,7 +46,13 @@ Per-message classes
   Our PublicInbox::V2Writable class may have two objects of this
   type in memory at-a-time for deduplication.
 
-* PublicInbox::SearchMsg - small message skeleton
+  In public-inbox 1.4 and earlier, Email::MIME and its subclass,
+  PublicInbox::MIME were used.  Despite still slurping,
+  PublicInbox::Eml is faster and uses less memory due to
+  lazy header parsing and lazy subpart instantiation with
+  shorter object lifetimes.
+
+* PublicInbox::Smsg - small message skeleton
   Used by: PublicInbox::{NNTP,WWW,SearchIdx}
   Common abbreviation: $smsg
 
@@ -61,15 +66,13 @@ Per-message classes
   There may be hundreds or thousands of these objects in memory
   at-a-time, so fields are pruned if unneeded.
 
-* PublicInbox::SearchThread::Msg - container for message threading
+* PublicInbox::SearchThread::Msg - subclass of Smsg
   Common abbreviation: $cont or $node
   Used by: PublicInbox::WWW
 
-  The container we use for a non-recursive[1] variant of
+  The structure we use for a non-recursive[1] variant of
   JWZ's algorithm: <https://www.jwz.org/doc/threading.html>.
-  This holds a $smsg and is only used for message threading.
-  This wrapper class may go away in the future and handled
-  directly by PublicInbox::SearchMsg to save memory.
+  Nowadays, this is a re-blessed $smsg with additional fields.
 
   As with $smsg objects, there may be hundreds or thousands
   of these objects in memory at-a-time.