deploy: 8f35f8148e

develop/development/synapse_architecture/streams.html

@@ -186,16 +186,22 @@ will be inserted with that ID.</p>
 <h3 id="current-stream-id"><a class="header" href="#current-stream-id">Current stream ID</a></h3>
 <p>For any given stream reader (including writers themselves), we may define a per-writer current stream ID:</p>
 <blockquote>
-<p>The current stream ID <em>for a writer W</em> is the largest stream ID such that
+<p>A current stream ID <em>for a writer W</em> is the largest stream ID such that
 all transactions added by W with equal or smaller ID have completed.</p>
 </blockquote>
 <p>Similarly, there is a &quot;linear&quot; notion of current stream ID:</p>
 <blockquote>
-<p>The &quot;linear&quot; current stream ID is the largest stream ID such that
+<p>A &quot;linear&quot; current stream ID is the largest stream ID such that
 all facts (added by any writer) with equal or smaller ID have completed.</p>
 </blockquote>
 <p>Because different stream readers A and B learn about new facts at different times, A and B may disagree about current stream IDs.
 Put differently: we should think of stream readers as being independent of each other, proceeding through a stream of facts at different rates.</p>
+<p>The above definition does not give a unique current stream ID, in fact there can
+be a range of current stream IDs. Synapse uses both the minimum and maximum IDs
+for different purposes. Most often the maximum is used, as its generally
+beneficial for workers to advance their IDs as soon as possible. However, the
+minimum is used in situations where e.g. another worker is going to wait until
+the stream advances past a position.</p>
 <p><strong>NB.</strong> For both senses of &quot;current&quot;, that if a writer opens a transaction that never completes, the current stream ID will never advance beyond that writer's last written stream ID.</p>
 <p>For single-writer streams, the per-writer current ID and the linear current ID are the same.
 Both senses of current ID are monotonic, but they may &quot;skip&quot; or jump over IDs because facts complete out of order.</p>
@@ -238,7 +244,7 @@ We only ever treat this as a multiple single-writer streams as there is no impor
 <li>track their current position (i.e. its own per-writer stream ID).</li>
 <li>their facts currently awaiting completion.</li>
 </ul>
-<p>At startup, </p>
+<p>At startup,</p>
 <ul>
 <li>the current position of that writer can be found by querying the database (which suggests that facts need to be written to the database atomically, in a transaction); and</li>
 <li>there are no facts awaiting completion.</li>

develop/print.html

@@ -18349,16 +18349,22 @@ will be inserted with that ID.</p>
 <h3 id="current-stream-id"><a class="header" href="#current-stream-id">Current stream ID</a></h3>
 <p>For any given stream reader (including writers themselves), we may define a per-writer current stream ID:</p>
 <blockquote>
-<p>The current stream ID <em>for a writer W</em> is the largest stream ID such that
+<p>A current stream ID <em>for a writer W</em> is the largest stream ID such that
 all transactions added by W with equal or smaller ID have completed.</p>
 </blockquote>
 <p>Similarly, there is a &quot;linear&quot; notion of current stream ID:</p>
 <blockquote>
-<p>The &quot;linear&quot; current stream ID is the largest stream ID such that
+<p>A &quot;linear&quot; current stream ID is the largest stream ID such that
 all facts (added by any writer) with equal or smaller ID have completed.</p>
 </blockquote>
 <p>Because different stream readers A and B learn about new facts at different times, A and B may disagree about current stream IDs.
 Put differently: we should think of stream readers as being independent of each other, proceeding through a stream of facts at different rates.</p>
+<p>The above definition does not give a unique current stream ID, in fact there can
+be a range of current stream IDs. Synapse uses both the minimum and maximum IDs
+for different purposes. Most often the maximum is used, as its generally
+beneficial for workers to advance their IDs as soon as possible. However, the
+minimum is used in situations where e.g. another worker is going to wait until
+the stream advances past a position.</p>
 <p><strong>NB.</strong> For both senses of &quot;current&quot;, that if a writer opens a transaction that never completes, the current stream ID will never advance beyond that writer's last written stream ID.</p>
 <p>For single-writer streams, the per-writer current ID and the linear current ID are the same.
 Both senses of current ID are monotonic, but they may &quot;skip&quot; or jump over IDs because facts complete out of order.</p>
@@ -18401,7 +18407,7 @@ We only ever treat this as a multiple single-writer streams as there is no impor
 <li>track their current position (i.e. its own per-writer stream ID).</li>
 <li>their facts currently awaiting completion.</li>
 </ul>
-<p>At startup, </p>
+<p>At startup,</p>
 <ul>
 <li>the current position of that writer can be found by querying the database (which suggests that facts need to be written to the database atomically, in a transaction); and</li>
 <li>there are no facts awaiting completion.</li>