Implemented PrintBuffer class. (Whew).

luprex/core/cpp/printbuffer.hpp

@@ -0,0 +1,132 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// PRINTBUFFER
+//
+// Lua has a 'print' statement - in client-server mode, where does the output of
+// the 'print' statement go?  We need to be able to handle print-statements on
+// the server (and forward them to the client), and we need for predictive
+// prints to be handled gracefully.
+//
+// Class PrintBuffer is a buffer for storing the output of the print statement.
+// It is part of the actor tangible.  When a lua thread calls 'print', the print
+// goes into stringstream lthread_console.  When the thread stops or yields, the
+// contents of lthread_console are converted to lines and transferred to the
+// PrintBuffer of the actor. From there, it gets difference transmitted, and the
+// client can probe it.
+//
+// Suppose, for example, that the player logs in and invokes a plan that prints
+// six lines from a Robert Frost poem.  That plan is executed by both the master
+// model and the synchronous model.  When the thread finishes, the PrintBuffer
+// in the actor in the master model will contain this:
+//
+//    * Block 0: Whose woods these are I think I know.  [authoritative]
+//    * Block 1: His house is in the village though;    [authoritative]
+//    * Block 2: He will not see me stopping here       [authoritative]
+//    * Block 3: To watch his woods fill up with snow.  [authoritative]
+//    * Block 4: My little horse must think it queer    [authoritative]
+//    * Block 5: To stop without a farmhouse near.      [authoritative]
+//
+// Note that the buffer stores line numbers, which start from zero the moment
+// the player logs in.  In the master model, all lines are always authoritative
+// because everything in the master model is authoritative.  In the synchronous
+// model, the PrintBuffer is likely to contain the same strings, but the lines
+// will all be marked as [prediction] instead of [authoritative].
+//
+// When the server difference transmits, the difference transmission will fix up
+// any mistakes in the PrintBuffer in the synchronous model.  In the process, it
+// will also fix up any [prediction] changing it to [authoritative].
+//
+// Periodically, the oldest lines in the buffer will get discarded.  More on
+// this later.  When lines get discarded, the line numbers don't change.  For
+// example, if we were to discard three lines from the buffer above, this is
+// what would remain:
+//
+//    * Line 3: To watch his woods fill up with snow.  [authoritative]
+//    * Line 4: My little horse must think it queer    [authoritative]
+//    * Line 5: To stop without a farmhouse near.      [authoritative]
+//
+// The client will periodically probe the PrintBuffer.  Suppose it sees all six
+// lines of the Robert Frost poem.  The next time it probes the buffer, it will
+// still see those same six lines.  The client will continue to see those six
+// lines until it takes explicit steps.
+//
+// Here's how we keep the buffer from growing forever.  The client probes the
+// PrintBuffer, and sees some authoritative lines.  The client downloads and
+// stores those lines locally. Once the lines are stored locally in the client,
+// the client injects a command into the command stream: "delete from
+// PrintBuffer up to line N" into the command stream.  This will cause the
+// engine to discard the lines that the client no longer needs.
+//
+// Note that when the client injects a "delete from PrintBuffer" into the
+// command stream, that's an invoke-command that has to follow the same process
+// as any other client invoke command.  It can take time for it to get
+// processed. Therefore, the client must be prepared that it might see some
+// redundant lines for a little while.
+//
+////////////////////////////////////////////////////////////////////////////////
+
+
+#ifndef PRINTBUFFER_HPP
+#define PRINTBUFFER_HPP
+
+#include "streambuffer.hpp"
+#include "util.hpp"
+#include <deque>
+#include <string>
+#include <memory>
+
+class PrintBuffer {
+private:
+    // The most recent lines printed.
+    std::deque<std::string> lines_;
+
+    // Line number of the first line in the buffer.  From this, all other
+    // line numbers can be inferred.
+    int first_line_;
+
+    // Line number of the first unchecked line in the buffer.  All line
+    // numbers including this one and beyond are unchecked.
+    int first_unchecked_;
+    
+    // The world type of the enclosing model.  This is used to determine
+    // whether add_string increments the n_checked counter or not.
+    util::WorldType world_type_;
+
+    // Add a line of text (internal).  Line is expected to NOT contain
+    // a newline (or any other weird control characters).
+    void add_line(const char *line, int len);
+    
+    // Return the line number beyond the end of the buffer.
+    int last_line() const { return first_line_ + int(lines_.size()); }
+
+    // Get the specified line number.
+    const std::string &nth(int n) const { return lines_[n - first_line_]; }
+
+
+public:
+    PrintBuffer(util::WorldType wt);
+
+    // Add a string.  If the string doesn't end in a newline, a newline
+    // is added.  The string is broken into lines, and the lines are added
+    // to the PrintBuffer.
+    void add_string(const char *text, int len);
+    void add_string(const std::string &s);
+    
+    // Discard lines up to but not including line N.
+    void discard_upto(int n);
+
+    // Difference transmission
+    void diff(const PrintBuffer &auth, StreamBuffer *sb) const;
+    void patch(StreamBuffer *sb);
+
+    // Clear the buffer (for unit testing)
+    void clear();
+
+    // Print the entire contents of the buffer to a string (for unit testing).
+    std::string debug_string() const;
+};
+
+using UniquePrintBuffer = std::unique_ptr<PrintBuffer>;
+
+#endif // PRINTBUFFER_HPP
+