svn commit - mysqldoc@docsrva: r5354 - trunk/ndbapi

[jon]

Author: jstephens
Date: 2007-03-14 17:52:51 +0100 (Wed, 14 Mar 2007)
New Revision: 5354

Log:

Most of the operation descriptions + diagrams.



Modified:
   trunk/ndbapi/ndb-internals-ndb-protocol.xml


Modified: trunk/ndbapi/ndb-internals-ndb-protocol.xml
===================================================================
--- trunk/ndbapi/ndb-internals-ndb-protocol.xml	2007-03-14 16:09:56 UTC (rev 5353)
+++ trunk/ndbapi/ndb-internals-ndb-protocol.xml	2007-03-14 16:52:51 UTC (rev 5354)
Changed blocks: 3, Lines Added: 340, Lines Deleted: 10; 13041 bytes

@@ -203,20 +203,39 @@
                 <entry><literal>TCINDXREF</literal></entry>
               </row>
               <row>
-                <entry><emphasis role="bold">Table or Index Scan
(<literal>SCANTAB</literal>)</emphasis></entry>
+                <entry><emphasis role="bold">Table or Index Scan
+                  (<literal>SCANTAB</literal>)</emphasis></entry>
                 <entry><literal>SCANTABREQ</literal></entry>
                 <entry><literal>SCANTABCONF</literal></entry>
                 <entry><literal>SCANTABREF</literal></entry>
               </row>
+              <row>
+                <entry><emphasis role="bold">Transaction Record Acquisition
+                  (<literal>TCSEIZE</literal>)</emphasis></entry>
+                <entry><literal>TCSEIZEREQ</literal></entry>
+                <entry><literal>TCSEIZECONF</literal></entry>
+                <entry><literal>TCSEIZEREF</literal></entry>
+              </row>
+              <row>
+                <entry><emphasis role="bold">Transaction Record Release
+                 
(<literal>TCRELEASE</literal>)</emphasis></entry>
+                <entry><literal>TCRELEASEREQ</literal></entry>
+                <entry><literal>TCRELEASECONF</literal></entry>
+                <entry><literal>TCRELEASEREF</literal></entry>
+              </row>
             </tbody>
           </tgroup>
         </informaltable>
+
+        <literal>CONF</literal> and <literal>REF</literal> are
shorthand
+        for <quote>confirmed</quote> and <quote>refused</quote>,
+        respectively.
       </para>
 
     </formalpara>
 
     <para>
-      Three additional types of messages are sometimes used in internode
+      Four additional types of messages are sometimes used in internode
       communication. These are:
 
       <orderedlist>

@@ -267,12 +286,20 @@
 
         <listitem>
           <para>
-            A <literal>TRANSID_AI</literal> message contains the data
-            returned from a read operation &mdash; in other words, a
-            result set.
+            A <literal>TRANSID_AI</literal> message contains data
+            returned from a read operation &mdash; in other words, it is
+            a result set (or part of one).
           </para>
         </listitem>
 
+        <listitem>
+          <para>
+            A <literal>SCAN_NEXTREQ</literal> message is used by the API
+            node to request additional results arising from a scan
+            operation.
+          </para>
+        </listitem>
+
       </orderedlist>
     </para>
 

@@ -325,16 +352,319 @@
 
   </section>
 
-  <section id="ndb-internals-ndb-protocol-signals-transactions">
+  <section id="ndb-internals-ndb-protocol-operations-signals-transactions">
 
-    <title>Signals and Transactions</title>
+    <title>Operations, Signals, and Transactions</title>
 
     <para>
-      
+      In this section we discuss the sequence of message-passing that
+      takes place between a data node and an API node for each of the
+      following operations:
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Primary key lookup
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Unique key lookup
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Table scan or index scan
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Explicit commit of a transaction
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Rollback of a transaction
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Transaction record handling (acquisition and release)
+          </para>
+        </listitem>
+
+      </itemizedlist>
     </para>
-    
-    
 
+    <formalpara>
+
+      <title>Primary key lookup</title>
+
+      <para>
+        An operation using a primary key lookup is performed shown in
+        the following diagram:
+
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="protocol-images/ndb-protocol-pk-lookup-1.png"
format="PNG"/>
+          </imageobject>
+          <textobject>
+            <phrase lang="en">Messages exchanged in a primary key
+            lookup</phrase>
+          </textobject>
+        </mediaobject>
+
+        <note>
+          <para>
+            <emphasis role="bold">*</emphasis> and
+            <emphasis role="bold">+</emphasis> are used here with the
+            meanings <quote>zero or more</quote> and <quote>one or
+            more</quote>, respectively.
+          </para>
+        </note>
+
+        This process is explained is greater detail here:
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              The API node sends a <literal>TCKEYREQ</literal> message
+              to the data node. In the event that the necessary
+              information about the key to be used is too large to be
+              contained in the <literal>TCKEYREQ</literal>, the message
+              may be accompanied by any number of
+              <literal>KEYINFO</literal> messages carrying the remaining
+              key information. If additional attributes are used for the
+              operation and exceed the space available in the
+              <literal>TCKEYREQ</literal>, or if data is to be sent to
+              the data node as part of a write operation, then these are
+              sent with the <literal>TCKEYREQ</literal> as any number of
+              <literal>ATTRINFO</literal> messages.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The data node then sends a message in response to the
+              request:
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    If the operation was successful, the data node sends
+                    a <literal>TCKEYCONF</literal> message to the API
+                    node. If the request was for a read operation, then
+                    <literal>TCKEYCONF</literal> is accompanied by a
+                    <literal>TRANSID_AI</literal> message, which
+                    contains actual result data. If there is more data
+                    than can be contained in a single
+                    <literal>TRANSID_AI</literal> can carry, more than
+                    one of these messages may be sent.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    If the operation failed, then the data node sends a
+                    <literal>TCKEYREF</literal> message back to the API
+                    node, and no more signalling takes place until the
+                    API node makes a new request.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+            </para>
+          </listitem>
+
+        </orderedlist>
+      </para>
+
+    </formalpara>
+
+    <formalpara>
+
+      <title>Unique key lookup</title>
+
+      <para>
+        This is performed in a manner similar to that performed in a
+        primary key lookup:
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              A request is made by the API node using a
+              <literal>TCINDXREQ</literal> message which may be
+              accompanied by zero or more <literal>KEYINFO</literal>
+              messages, zero or more <literal>ATTRINFO</literal>
+              messages, or both.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The data node returns a response:
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    If the operation was a success, the message is
+                    <literal>TCINDXCONF</literal>. For a successful read
+                    operation, this message may be accompanied by one or
+                    more <literal>TRANSID_AI</literal> messages carrying
+                    the result data.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    If the operation failed, the data node returns a
+                    <literal>TCINDXREF</literal> message.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        The exachange of messages involved in a unique key lookup is
+        illustrated here:
+
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="protocol-images/ndb-protocol-uk-lookup-1.png"
format="PNG"/>
+          </imageobject>
+          <textobject>
+            <phrase lang="en">Messages exchanged in a unique key
+            lookup</phrase>
+          </textobject>
+        </mediaobject>
+      </para>
+
+    </formalpara>
+
+    <formalpara>
+
+      <title>Table scans and index scans</title>
+
+      <para>
+        These are similar in many respects to primary key and unque key
+        lookups, as shown here:
+
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="protocol-images/ndb-protocol-table-index-scan-1.png"
format="PNG"/>
+          </imageobject>
+          <textobject>
+            <phrase lang="en">Messages exchanged for a table scan or
+            index scan operation.</phrase>
+          </textobject>
+        </mediaobject>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              A request is made by the API node using a
+              <literal>SCAN_TABREQ</literal> message, along with zero or
+              more <literal>ATTRINFO</literal> messages.
+              <literal>KEYINFO</literal> messages are also used with
+              index scans in the event that bounds are used.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The data node returns a response:
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    If the operation was a success, the message is
+                    <literal>SCAN_TABCONF</literal>. For a successful
+                    read operation, this message may be accompanied by
+                    one or more <literal>TRANSID_AI</literal> messages
+                    carrying the result data. However &mdash; unlike the
+                    case with lookups based on a primary or unique key
+                    &mdash; it is often necessary to fetch multiple
+                    results from the data node. Requests following the
+                    first are singalled by the API node using a
+                    <literal>SCAN_NEXTREQ</literal>, which tells the
+                    data node to send the next set of results (if there
+                    are more results). This is shown here:
+
+                    <mediaobject>
+                      <imageobject>
+                        <imagedata
fileref="protocol-images/ndb-protocol-fetch-results-1.png" format="PNG"/>
+                      </imageobject>
+                      <textobject>
+                        <phrase lang="en">Fetching mutitple result data
+                        sets following a table or index scan read
+                        operation</phrase>
+                      </textobject>
+                    </mediaobject>
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    If the operation failed, the data node returns a
+                    <literal>SCAN_TABREF</literal> message.
+                  </para>
+
+                  <para>
+                    <literal>SCAN_TABREF</literal> is also used to
+                    signal to the API node that all data resulting from
+                    a read has been sent.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+            </para>
+          </listitem>
+
+        </orderedlist>
+      </para>
+
+    </formalpara>
+
+    <formalpara>
+
+      <title>Committing transactions</title>
+
+      <para>
+        The process of performing an explicit commit follows the same
+        general pattern as shown previously. The API node sends a
+        <literal>TC_COMMITREQ</literal> message to the data node, which
+        responds with either a <literal>TC_COMMITCONF</literal> (on
+        success) or a <literal>TC_COMMITREF</literal> (if the commit
+        failed). This is shown in the following diagram:
+
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="protocol-images/ndb-protocol-explicit-commit-1.png"
format="PNG"/>
+          </imageobject>
+          <textobject>
+            <phrase lang="en">Messages exchanged in explicit commit
+            operation</phrase>
+          </textobject>
+        </mediaobject>
+      </para>
+
+    </formalpara>
+
   </section>
 
 </section>