From cba19d7e23c7c6a74ee2c0eb2accaab2347e927f Mon Sep 17 00:00:00 2001
From: JoelKatz <DavidJoelSchwartz@GMail.com>
Date: Mon, 15 Dec 2014 07:23:10 -0800
Subject: [PATCH] Document and cleanup ledger advance logic * Don't acquire if
 validated ledger is old * Don't try to publish if no valid ledger * Update
 README.md file

---
 src/ripple/app/ledger/LedgerMaster.cpp |  9 +++++--
 src/ripple/app/ledger/README.md        | 33 ++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/src/ripple/app/ledger/LedgerMaster.cpp b/src/ripple/app/ledger/LedgerMaster.cpp
index fb9809d0a..5cfb39372 100644
--- a/src/ripple/app/ledger/LedgerMaster.cpp
+++ b/src/ripple/app/ledger/LedgerMaster.cpp
@@ -935,7 +935,8 @@ public:
             {
                 if (!standalone_ && !getApp().getFeeTrack().isLoadedLocal() &&
                     (getApp().getJobQueue().getJobCount(jtPUBOLDLEDGER) < 10) &&
-                    (mValidLedgerSeq == mPubLedgerSeq))
+                    (mValidLedgerSeq == mPubLedgerSeq) &&
+                    (getValidatedLedgerAge() < 60))
                 { // We are in sync, so can acquire
                     std::uint32_t missing;
                     {
@@ -1071,7 +1072,11 @@ public:
         std::list<Ledger::pointer> ret;
 
         WriteLog (lsTRACE, LedgerMaster) << "findNewLedgersToPublish<";
-        if (!mPubLedger)
+        if (mValidLedger.empty ())
+        {
+            // No valid ledger, nothing to do
+        }
+        else if (! mPubLedger)
         {
             WriteLog (lsINFO, LedgerMaster) << "First published ledger will be " << mValidLedgerSeq;
             ret.push_back (mValidLedger.get ());
diff --git a/src/ripple/app/ledger/README.md b/src/ripple/app/ledger/README.md
index ee851ba52..879c41cec 100644
--- a/src/ripple/app/ledger/README.md
+++ b/src/ripple/app/ledger/README.md
@@ -397,6 +397,39 @@ are occupied by the exchange rate.
 
 ---
 
+# Ledger Publication #
+
+## Overview ##
+
+The Ripple server permits clients to subscribe to a continuous stream of
+fully-validated ledgers. The publication code maintains this stream.
+
+The server attempts to maintain this continuous stream unless it falls
+too far behind, in which case it jumps to the current fully-validated
+ledger and then attempts to resume a continuous stream.
+
+## Implementation ##
+
+LedgerMaster::doAdvance is invoked when work may need to be done to
+publish ledgers to clients. This code loops until it cannot make further
+progress.
+
+LedgerMaster::findNewLedgersToPublish is called first. If the last
+fully-valid ledger's sequence number is greater than the last published
+ledger's sequence number, it attempts to publish those ledgers, retrieving
+them if needed.
+
+If there are no new ledgers to publish, doAdvance determines if it can
+backfill history. If the publication is not caught up, bakfilling is not
+attempted to conserve resources.
+
+If history can be backfilled, the missing ledger with the highest
+sequence number is retrieved first. If a historical ledger is retrieved,
+and its predecessor is in the database, tryFill is invoked to update
+the list of resident ledgers.
+
+---
+
 # The Ledger Cleaner #
 
 ## Overview ##