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

[jon]

Author: jstephens
Date: 2008-02-26 15:31:37 +0100 (Tue, 26 Feb 2008)
New Revision: 10016

Log:

Added info about and example of use for distribution-aware form of 
Ndb::startTransaction() (Thanks, Massimo and Tomas!)



Modified:
   trunk/ndbapi/class-ndb.xml


Modified: trunk/ndbapi/class-ndb.xml
===================================================================
--- trunk/ndbapi/class-ndb.xml	2008-02-26 13:35:09 UTC (rev 10015)
+++ trunk/ndbapi/class-ndb.xml	2008-02-26 14:31:37 UTC (rev 10016)
Changed blocks: 6, Lines Added: 104, Lines Deleted: 14; 5644 bytes

@@ -925,14 +925,23 @@
 
       </formalpara>
 
-        &mccge-warning-begin;
+      &mccge-warning-begin;
+      
+      <formalpara>
 
+        <title>Distribution-aware form of <literal>startTransaction()</literal></title>
+
         <para>
-        Beginning with MySQL 5.1.15-ndb-6.1.4, it is possible to suggest
-        which node node should be used to act as the transaction
-        coordinator.
-      </para>
+          Beginning with MySQL 5.1.15-ndb-6.1.4, it is possible to
+          employ <firstterm>distribution awareness</firstterm> with this
+          method &mdash; that is, to suggest which node should act as
+          the transaction coordinator. When
+          <literal>startTransaction()</literal> is used in this way, it
+          takes 4 arguments, as shown in the following paragraphs.
+        </para>
 
+      </formalpara>
+
       <formalpara>
 
         <title>Signature</title>

@@ -956,7 +965,7 @@
         <title>Parameters</title>
 
         <para>
-          When specifying the transactioncoordinator, this method takes
+          When specifying the transaction coordinator, this method takes
           four parameters:
 
           <itemizedlist>

@@ -972,9 +981,8 @@
 
             <listitem>
               <para>
-                A null-terminated array of pointers to a
-                <literal>Key_part_ptr</literal> structure that is part
-                of the distribution key. The length of the key part is
+                A null-terminated array of pointers to the values of the
+                distribution key columns. The length of the key part is
                 read from metadata and checked against the passed value.
               </para>
 

@@ -985,8 +993,8 @@
 <programlisting>
 struct Key_part_ptr
     {
-      const void * <replaceable>ptr</replaceable>;
-      unsigned <replaceable>len</replaceable>;
+      const void *<replaceable>ptr</replaceable>;
+      unsigned    <replaceable>len</replaceable>;
     }
 </programlisting>
               </para>

@@ -994,7 +1002,7 @@
 
             <listitem>
               <para>
-                A pointer to a temporary buffer be used to calculate the
+                A pointer to a temporary buffer, used to calculate the
                 hash value.
               </para>
             </listitem>

@@ -1018,16 +1026,98 @@
 
       </formalpara>
 
+      <formalpara>
+
+        <title>Example</title>
+
+        <para>
+          Suppose that the table&apos;s partition key is single
+          <literal>BIGINT</literal> column. Then you would declare the
+          distribution key array as shown here:
+
+<programlisting>            
+Key_part_ptr distkey[2];
+</programlisting>
+
+          The value of the distribution key would be defined as shown
+          here:
+
+<programlisting>            
+unsigned long long distkeyValue= 23;
+</programlisting>
+
+          The pointer to the distribution key array would be set as
+          follows:
+
+<programlisting>            
+distkey[0].ptr= (const void*) &amp;distkeyValue;
+</programlisting>
+
+          The length of this pointer would be set accordingly:
+
+<programlisting>            
+distkey[0].len=sizeof(distkeyValue);
+</programlisting>
+
+          The distribution key array must terminate with a
+          <literal>NULL</literal> element. This is necessary to avoid to
+          having an additional parameter providing the number of columns
+          in the distribution key:
+
+<programlisting>           
+distkey[1].ptr=NULL;
+distkey[1].len=NULL;
+</programlisting>
+
+          Setting the buffer to <literal>NULL</literal> allows
+          <literal>startTransaction()</literal> to allocate and free
+          memory automatically:
+
+<programlisting>           
+           xfrmbuf=NULL
+           xfrmbuflen=0
+</programlisting>
+
+          <note>
+            <para>
+              You can also specify a buffer to save having to make
+              explicit <literal>malloc()</literal> and
+              <literal>free()</literal> calls, but calculating an
+              appropriate size for this buffer is not a simple matter.
+              However, if you choose to specify the buffer, 1 MB is
+              usually sufficient for its size.
+            </para>
+          </note>
+
+          Now, when you start the transaction, you access the node that
+          contains the desired information directly.
+        </para>
+
+      </formalpara>
+
       <para>
+        In the event that the cluster has the same number of data nodes
+        as it has replicas, there is no difference in performance
+        between the two versions of
+        <literal>startTransaction()</literal>, since each data node
+        contains the entire database. However, where the number of data
+        nodes is greater than the number of replicas (for example, where
+        <literal>NoOfReplicas</literal> is set equal to 2 in a cluster
+        with 4 data nodes), you should see a marked improvement in
+        performance by using the distribution-aware version of this
+        method.
+      </para>
+
+      <para>
         It is still possible to use this method as before, without
         specifying the transaction coordinator. In either case, you must
         still explicitly close the transaction, whether or not the call
         to <literal>startTransaction()</literal> was successful.
       </para>
 
-        &mccge-warning-end-api;
+      &mccge-warning-end-api;
 
-        <formalpara>
+      <formalpara>
 
         <title>Return Value</title>