PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip - Mend

amps-python-client 5.3.4.1__zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (550) hide show

amps-python-client-5.3.4.1/docs/user-guide/html/chapters/acks.html ADDED Viewed

@@ -0,0 +1,289 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>17. Command Acknowledgment &#8212; AMPS User Guide develop documentation</title>
+    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     'develop',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true,
+        SOURCELINK_SUFFIX: '.txt'
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="next" title="18. Transports" href="transports.html" />
+    <link rel="prev" title="16. Message Types" href="messageTypes.html" />
+  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+  </head>
+  <body role="document">
+  <div class="document">
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+            <p class="logo"><a href="../index.html">
+              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
+            </a></p>
+  <h3><a href="../index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">17. Command Acknowledgment</a><ul>
+<li><a class="reference internal" href="#requesting-acknowledgments">Requesting Acknowledgments</a></li>
+<li><a class="reference internal" href="#receiving-acknowledgments">Receiving Acknowledgments</a></li>
+<li><a class="reference internal" href="#bookmark-subscriptions-and-completed-acknowledgments">Bookmark Subscriptions and Completed Acknowledgments</a></li>
+<li><a class="reference internal" href="#bookmark-subscriptions-and-persisted-acknowledgments">Bookmark Subscriptions and Persisted Acknowledgments</a></li>
+<li><a class="reference internal" href="#acknowledgment-conflation-and-publish-acknowledgments">Acknowledgment Conflation and Publish Acknowledgments</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="../index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="messageTypes.html" title="previous chapter">16. Message Types</a></li>
+      <li>Next: <a href="transports.html" title="next chapter">18. Transports</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <form class="search" action="../search.html" method="get">
+      <div><input type="text" name="q" /></div>
+      <div><input type="submit" value="Go" /></div>
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+  <div class="section" id="command-acknowledgment">
+<span id="acks"></span><h1>17. Command Acknowledgment<a class="headerlink" href="#command-acknowledgment" title="Permalink to this headline">¶</a></h1>
+<p>AMPS command processing is designed to be asynchronous. The design of
+the server makes it possible for an application to send a command to
+AMPS, and receive the results of that command at a later time.
+Acknowledgment of commands is always optional: the server makes no
+requirement that an application request acknowledgment. The AMPS client
+libraries automatically request the acknowledgments required to
+maintain the guarantees the client API provides.</p>
+<p>The status and results of a command are returned to a client in the form
+of an acknowledgment, or <code class="docutils literal"><span class="pre">ack</span></code>, message. AMPS can return status
+updates at various checkpoints throughout the command processing
+sequence.</p>
+<p>For many applications, it may not be necessary for the application to
+request message acknowledgments explicitly. The AMPS clients request a
+set of acknowledgments by default that balance performance with error
+detection.</p>
+<p>AMPS supports a variety of <code class="docutils literal"><span class="pre">ack</span></code> types, and allows you to request
+multiple <code class="docutils literal"><span class="pre">ack</span></code> types on each command. For example, the received <code class="docutils literal"><span class="pre">ack</span></code>
+type requests that AMPS acknowledge when the command is received, while the
+completed <code class="docutils literal"><span class="pre">ack</span></code> type requests that AMPS acknowledge when it has completed
+the command (or the portion of the command that runs immediately). Each
+AMPS command supports a different set of types, and the precise meaning
+of the <code class="docutils literal"><span class="pre">ack</span></code> returned depends on the command that AMPS is
+acknowledging.</p>
+<p>AMPS commands are inherently <em>asynchronous</em>, and AMPS does not provide
+acknowledgment messages by default. A client must both explicitly
+request an acknowledgment and then receive and process that
+acknowledgment to know the results of a command. It is normal for time
+to elapse between the request and the acknowledgment, therefore AMPS
+acknowledgments provide a way to correlate the acknowledgment with the
+command that produced it. This is typically done with an identifier that
+the client assigns to a command, which is then returned in the
+acknowledgment for the command.</p>
+<p>AMPS supports the acknowledgment types listed in the following table:</p>
+<table border="1" class="docutils" id="id1">
+<caption><span class="caption-text"><em>Acknowledgment types</em></span><a class="headerlink" href="#id1" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Acknowledgment Type</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">completed</span></code></td>
+<td>The command (or a portion of the command) has
+completed.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">persisted</span></code></td>
+<td>The results of the command have been persisted
+to durable storage.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">processed</span></code></td>
+<td>AMPS has processed the command.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">received</span></code></td>
+<td>AMPS has received the command.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">stats</span></code></td>
+<td>AMPS returns statistics associated with the
+command.</td>
+</tr>
+</tbody>
+</table>
+<p>Acknowledgments for different commands may not arrive in the order that
+commands were submitted to AMPS. For example, a <code class="docutils literal"><span class="pre">publish</span></code> command to a
+topic that uses synchronous replication will not return a <code class="docutils literal"><span class="pre">persisted</span></code>
+acknowledgment until the synchronous replication destinations have
+persisted the message. If the client issues a <code class="docutils literal"><span class="pre">subscribe</span></code> command in
+the meantime, the <code class="docutils literal"><span class="pre">processed</span></code> acknowledgment for the <code class="docutils literal"><span class="pre">subscribe</span></code>
+command &#8211; indicating that AMPS has processed the subscription request
+&#8211; may well return before the <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment.</p>
+<p>Not all commands support all acknowledgment types, and the meaning of
+each acknowledgment may differ depending on the command submitted. The
+acknowledgments for different commands set different fields on an
+acknowledgment message. See the <a class="reference external" href="../../../command-reference/html/index.html">AMPS Command Reference</a> for details.</p>
+<div class="section" id="requesting-acknowledgments">
+<span id="ug-ack-requesting"></span><h2>Requesting Acknowledgments<a class="headerlink" href="#requesting-acknowledgments" title="Permalink to this headline">¶</a></h2>
+<p>Acknowledgments from the AMPS server are always optional. The AMPS
+clients will request acknowledgments as necessary for processing and
+error reporting. In addition, an application can request acknowledgments
+as necessary to meet the requirements of an application.</p>
+<p>The <em>AMPS Command Reference</em> contains information on the acknowledgment types
+available for each command and the meaning of those acknowledgments.</p>
+<div class="admonition tip">
+<p class="first admonition-title">Tip</p>
+<p><strong>Developer Tip</strong>: The AMPS client libraries automatically request
+and automatically process the acknowledgments needed for the
+library itself to work as expected.</p>
+<p>An application can also request acknowledgments explicitly.</p>
+<p>When an application explicitly requests an acknowledgment that is
+<em>not</em> conflated (see the section on <a class="reference internal" href="#ug-ack-conflation"><span class="std std-ref">Acknowledgment Conflation and Publish Acknowledgments</span></a> below),
+the AMPS clients deliver that acknowledgment to the message handler
+provided on the command, if one was provided.</p>
+<p class="last">If the acknowledgment is conflated, the application must either
+provide a last chance message handler, or provide a global command
+type message handler to process acknowledgments.</p>
+</div>
+</div>
+<div class="section" id="receiving-acknowledgments">
+<span id="ug-ack-receiving"></span><h2>Receiving Acknowledgments<a class="headerlink" href="#receiving-acknowledgments" title="Permalink to this headline">¶</a></h2>
+<p>Acknowledgments for a specific command or subscription are delivered as a
+part of the message stream for that command. In an AMPS client, this means
+that whatever method an application is using to receive responses from AMPS
+will include acknowledgment messages.</p>
+<p>Acknowledgments from AMPS have a command type of <code class="docutils literal"><span class="pre">ack</span></code>. This command type
+is reserved for responses from AMPS to a client. The <code class="docutils literal"><span class="pre">CommandId</span></code> of the
+acknowledgment message contains the <code class="docutils literal"><span class="pre">CommandId</span></code> provided by the client
+on the command that AMPS is responding to. The client uses this <code class="docutils literal"><span class="pre">CommandId</span></code>
+to route the acknowledgment message to the correct message processor in
+the application.</p>
+<p>Notice that when acknowledgments are <em>conflated</em> &#8211; that is, the
+acknowledgment refers to a number of publish commands &#8211; AMPS does not include
+a <code class="docutils literal"><span class="pre">CommandId</span></code> in the acknowledgment message. Further details are provided in the
+section on <a class="reference internal" href="#ug-ack-conflation"><span class="std std-ref">Acknowledgment Conflation and Publish Acknowledgments</span></a>.</p>
+</div>
+<div class="section" id="bookmark-subscriptions-and-completed-acknowledgments">
+<span id="ug-ack-completed"></span><h2>Bookmark Subscriptions and Completed Acknowledgments<a class="headerlink" href="#bookmark-subscriptions-and-completed-acknowledgments" title="Permalink to this headline">¶</a></h2>
+<p>When AMPS is processing a bookmark subscription, a <code class="docutils literal"><span class="pre">completed</span></code>
+acknowledgment indicates that the subscription has completed replay from the
+transaction log. This means that the subscription has reached the point in
+the transaction log at which the subscribe command was received, and
+messages delivered on the subscription after the <code class="docutils literal"><span class="pre">completed</span></code> acknowledgment
+are from new publishes.</p>
+</div>
+<div class="section" id="bookmark-subscriptions-and-persisted-acknowledgments">
+<h2>Bookmark Subscriptions and Persisted Acknowledgments<a class="headerlink" href="#bookmark-subscriptions-and-persisted-acknowledgments" title="Permalink to this headline">¶</a></h2>
+<p>A bookmark subscription typically also requests the <code class="docutils literal"><span class="pre">persisted</span></code>
+acknowledgment (the AMPS clients do this automatically). In this case,
+once the replay has reached the end of the transaction log,
+AMPS periodically returns an acknowledgment that includes the last
+bookmark written to the local transaction log and acknowledged
+by all replication destinations that use <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment.
+This information helps with application recovery, particularly in
+cases where publishers are intermittent or low-volume, and the last
+message for a subscription is significantly older than the last
+message evaluated for delivery to the subscription.</p>
+<p>This also helps to manage failover in situations where
+multiple instances in a given replication fabric are
+accepting publishes by providing a stable failover point
+across instances.</p>
+</div>
+<div class="section" id="acknowledgment-conflation-and-publish-acknowledgments">
+<span id="ug-ack-conflation"></span><h2>Acknowledgment Conflation and Publish Acknowledgments<a class="headerlink" href="#acknowledgment-conflation-and-publish-acknowledgments" title="Permalink to this headline">¶</a></h2>
+<p>For some commands, AMPS will <em>conflate</em> acknowledgments and return
+acknowledgments for multiple commands at one time. When AMPS conflates
+acknowledgments, AMPS provides an identifier other than the command
+identifier that describes which commands the acknowledgment applies to.</p>
+<p>For example, when a transaction log is configured (with at least one
+topic recorded), AMPS conflates <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgments in
+response to <code class="docutils literal"><span class="pre">publish</span></code> commands and <code class="docutils literal"><span class="pre">sow_delete</span></code> commands. These conflated
+acknowledgments contain the last client sequence number that the
+acknowledgment applies to rather than the command identifiers or
+sequence numbers for all messages being acknowledged. For example, if an
+application publishes messages with sequence numbers <code class="docutils literal"><span class="pre">1</span></code>, <code class="docutils literal"><span class="pre">2</span></code>,
+<code class="docutils literal"><span class="pre">3</span></code>, <code class="docutils literal"><span class="pre">4</span></code>, and <code class="docutils literal"><span class="pre">5</span></code>, and message <code class="docutils literal"><span class="pre">3</span></code> fails due to entitlement
+restrictions, AMPS will return an <code class="docutils literal"><span class="pre">ack</span></code> indicating success for message
+<code class="docutils literal"><span class="pre">2</span></code>, an <code class="docutils literal"><span class="pre">ack</span></code> indicating failure for message <code class="docutils literal"><span class="pre">3</span></code>, and an <code class="docutils literal"><span class="pre">ack</span></code>
+indicating success for message <code class="docutils literal"><span class="pre">5</span></code>.</p>
+<p>By default, AMPS produces conflated acknowledgments for a given connection
+approximately once a second.</p>
+<p>Starting with version 5.2.3.0, AMPS allows configuration of the
+conflation interval. To set a different conflation interval:</p>
+<ul class="simple">
+<li>For an individual client, provide an <code class="docutils literal"><span class="pre">ack_conflation</span></code> option in
+the options string for the logon for that client. This sets the
+interval at which AMPS will provide acknowledgments to that client.</li>
+<li>For replication acknowledgments, specify the <code class="docutils literal"><span class="pre">AckConflationInterval</span></code>
+in the replication <code class="docutils literal"><span class="pre">Destination</span></code>. This sets the interval at which the
+downstream AMPS server will provide acknowledgments to this AMPS server.</li>
+</ul>
+<p>Notice that when a publisher is publishing to a replicated topic, the
+<code class="docutils literal"><span class="pre">ack_conflation</span></code> interval sets the interval at which AMPS acknowledges
+messages that have already been acknowledged by synchronous replication
+destinations, while the <code class="docutils literal"><span class="pre">AckConflationInterval</span></code> specifies how often
+those downstream destinations produce an acknowledgment. In a situation
+where it is important to reduce the default latency of an acknowledgment,
+<strong>both</strong> the server option and the client side option typically need to be set.</p>
+<p>To see more information about the different commands and their supported
+acknowledgment types, please refer to the <em>AMPS Command Reference</em>,
+provided with 4.0 and greater versions of the AMPS clients and available from
+the 60East documentation site at <a class="reference external" href="http://docs.crankuptheamps.com/">http://docs.crankuptheamps.com/</a>.</p>
+</div>
+</div>
+          </div>
+        </div>
+      </div>
+    <div class="clearer"></div>
+  </div>
+    <div class="footer">
+      &copy;2023 60East Technologies, Inc. (version develop).
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
+    </div>
+  </body>
+</html>