From 61b98db9b0ac48674983d216797be1a811267c0e Mon Sep 17 00:00:00 2001
From: jyelon <jyelon@gmail.com>
Date: Sat, 21 Feb 2026 20:48:02 -0500
Subject: [PATCH] Add more documentation to printbuffer.h

---
 luprex/cpp/core/printbuffer.cpp | 20 ++++++++++----------
 luprex/cpp/core/printbuffer.hpp | 21 +++++++++++++++++++++
 2 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/luprex/cpp/core/printbuffer.cpp b/luprex/cpp/core/printbuffer.cpp
index 68b4d491..c6532b6d 100644
--- a/luprex/cpp/core/printbuffer.cpp
+++ b/luprex/cpp/core/printbuffer.cpp
@@ -24,14 +24,14 @@ struct PrintBufferCore  : public eng::opnew {
     PrintBufferCore() : first_line_(0), first_unchecked_(0) {}
 };
 
-static PrintBufferCore shared_core;
+static PrintBufferCore empty_core_;
 
 PrintBuffer::PrintBuffer() {
-    core_ = &shared_core;
+    core_ = &empty_core_;
 }
 
 PrintBuffer::~PrintBuffer() {
-    if (core_ != &shared_core) delete core_;
+    if (core_ != &empty_core_) delete core_;
 }
 
 int PrintBuffer::first_line() const {
@@ -64,9 +64,9 @@ eng::string PrintBuffer::debug_string() const {
 }
 
 void PrintBuffer::clear() {
-    if (core_ != &shared_core) {
+    if (core_ != &empty_core_) {
         delete core_;
-        core_ = &shared_core;
+        core_ = &empty_core_;
     }
 }
 
@@ -78,7 +78,7 @@ static int first_line_len(const char *text, int len) {
 }
 
 static void add_line(PrintBufferCore *core, const char *text, int len, bool auth) {
-    assert(core != &shared_core);
+    assert(core != &empty_core_);
     core->lines_.emplace_back(text, len);
     if (auth) {
         core->first_unchecked_ = core->first_line_ + int(core->lines_.size());
@@ -88,7 +88,7 @@ static void add_line(PrintBufferCore *core, const char *text, int len, bool auth
 void PrintBuffer::add_string(const eng::string &s, bool auth) {
     const char *text = s.c_str();
     int len = s.size();
-    if (core_ == &shared_core) core_ = new PrintBufferCore;
+    if (core_ == &empty_core_) core_ = new PrintBufferCore;
     while (true) {
         int fll = first_line_len(text, len);
         if (fll == len) {
@@ -105,7 +105,7 @@ void PrintBuffer::add_string(const eng::string &s, bool auth) {
 }
 
 void PrintBuffer::discard_upto(int n) {
-    if (core_ == &shared_core) return;
+    if (core_ == &empty_core_) return;
     while ((!core_->lines_.empty()) && (core_->first_line_ < n)) {
         core_->lines_.pop_front();
         core_->first_line_ += 1;
@@ -134,7 +134,7 @@ void PrintBuffer::deserialize(StreamBuffer *sb) {
     if (never_printed) {
         clear();
     } else {
-        if (core_ == &shared_core) core_ = new PrintBufferCore;
+        if (core_ == &empty_core_) core_ = new PrintBufferCore;
         core_->first_line_ = sb->read_uint32();
         core_->first_unchecked_ = sb->read_uint32();
         int nlines = sb->read_uint32();
@@ -163,7 +163,7 @@ void PrintBuffer::diff(const PrintBuffer &auth, StreamBuffer *sb) const {
 
 void PrintBuffer::patch(StreamBuffer *sb, DebugCollector *dbc) {
     DebugBlock dbb(dbc, "PrintBuffer::patch");
-    if (core_ == &shared_core) core_ = new PrintBufferCore;
+    if (core_ == &empty_core_) core_ = new PrintBufferCore;
     int auth_first = sb->read_int32();
     int auth_last = sb->read_int32();
     core_->lines_.resize(core_->first_unchecked_ - core_->first_line_);
diff --git a/luprex/cpp/core/printbuffer.hpp b/luprex/cpp/core/printbuffer.hpp
index a927cd7b..cf2a3746 100644
--- a/luprex/cpp/core/printbuffer.hpp
+++ b/luprex/cpp/core/printbuffer.hpp
@@ -91,6 +91,27 @@ struct PrintBufferCore;
 
 class PrintBuffer : public eng::nevernew {
 private:
+    // A pointer to a PrintBufferCore that stores the data.
+    //
+    // This pointer can be in two states: it can point
+    // to a heap-allocated PrintBufferCore which is owned,
+    // or it can point to a global variable "empty_core"
+    // which is always empty.  
+    //
+    // Any attempt to write into the printbuffer will
+    // first check if this points to empty_core.  If so,
+    // a PrintBufferCore will be allocated and stored
+    // here, only then will the write happen.
+    //
+    // Clearing the printbuffer will cause any owned
+    // PrintBufferCore to be freed, and the pointer to
+    // empty_core will be restored.
+    //
+    // The advantage of this design is that the empty state
+    // is stored very efficiently, but it's not a null
+    // pointer: it's still a valid core.  You never have
+    // to check for nullptr here.
+    //
     PrintBufferCore *core_;
 
 public: