Author: jstephens
Date: 2006-05-02 02:44:23 +0200 (Tue, 02 May 2006)
New Revision: 1984
Log:
First attempt at adding some indexes to NDB API doc.
Also a few misc. wording and markup fixes.
Modified:
trunk/ndbapi/examples.xml
trunk/ndbapi/ndbapi.xml
trunk/ndbapi/overview.xml
Modified: trunk/ndbapi/examples.xml
===================================================================
--- trunk/ndbapi/examples.xml 2006-05-01 22:45:15 UTC (rev 1983)
+++ trunk/ndbapi/examples.xml 2006-05-02 00:44:23 UTC (rev 1984)
@@ -26,6 +26,12 @@
<section id="example-synchronous-transactions">
<title>Using Synchronous Transactions</title>
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>synchronous</secondary>
+ <tertiary>example of use</tertiary>
+ </indexterm>
<abstract>
@@ -323,6 +329,11 @@
<section id="example-handling-errors">
<title>Handling Errors and Retrying Transactions</title>
+
+ <indexterm>
+ <primary>error handling</primary>
+ <secondary>example</secondary>
+ </indexterm>
<abstract>
@@ -338,6 +349,11 @@
</para>
</abstract>
+
+ <indexterm>
+ <primary>error types</primary>
+ <secondary>in applications</secondary>
+ </indexterm>
<para>
There are many ways to program using the NDB API. In this example,
@@ -598,6 +614,11 @@
<section id="example-basic-scanning">
<title>Basic Scanning Example</title>
+
+ <indexterm>
+ <primary>scans</primary>
+ <secondary>performing with <literal>NdbScanFilter</literal> and <literal>NdbScanOperation</literal></secondary>
+ </indexterm>
<abstract>
@@ -1015,8 +1036,7 @@
{
if (retryAttempt >= retryMax)
{
- std::cout << "ERROR: has retried this operation " << retryAttempt
- << " times, failing!" << std::endl;
+ std::cout << "ERROR: has retried this operation " << retryAttempt << " times, failing!" << std::endl;
return -1;
}
@@ -1485,6 +1505,12 @@
<section id="example-secondary-indexes">
<title>Using Secondary Indexes in Scans</title>
+
+ <indexterm>
+ <primary>scans</primary>
+ <secondary>using secondary indexes</secondary>
+ <tertiary>example</tertiary>
+ </indexterm>
<abstract>
@@ -1758,6 +1784,12 @@
<section id="example-event-handling">
<title>NDB API Event Handling Example</title>
+
+ <indexterm>
+ <primary>events</primary>
+ <secondary>handling</secondary>
+ <tertiary>example</tertiary>
+ </indexterm>
<abstract>
Modified: trunk/ndbapi/ndbapi.xml
===================================================================
--- trunk/ndbapi/ndbapi.xml 2006-05-01 22:45:15 UTC (rev 1983)
+++ trunk/ndbapi/ndbapi.xml 2006-05-02 00:44:23 UTC (rev 1984)
@@ -16,6 +16,10 @@
<abstract>
<title>&title;</title>
+
+ <para>
+ <remark role="repository.revision"/>
+ </para>
<para>
Provides information for developers wishing to use the low-level
Modified: trunk/ndbapi/overview.xml
===================================================================
--- trunk/ndbapi/overview.xml 2006-05-01 22:45:15 UTC (rev 1983)
+++ trunk/ndbapi/overview.xml 2006-05-02 00:44:23 UTC (rev 1984)
@@ -48,6 +48,11 @@
perform operations in a "no-commit" or deferred mode, to be
committed at a later time.
</para>
+
+ <indexterm>
+ <primary>scans</primary>
+ <secondary>types supported</secondary>
+ </indexterm>
<para>
NDB scans are conceptually rather similar to the SQL cursors
@@ -135,9 +140,13 @@
Glossary</ulink> to be useful as well.
</para>
- <itemizedlist>
+ <itemizedlist>
<listitem>
+ <indexterm>
+ <primary>backup</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Backup</emphasis>: A complete copy of
all cluster data, transactions and logs, saved to disk.
@@ -145,6 +154,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>restore</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Restore</emphasis>: Returning the
cluster to a previous state as stored in a backup.
@@ -152,6 +165,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>checkpoint</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Checkpoint</emphasis>: Generally
speaking, when data is saved to disk, it is said that a
@@ -164,6 +181,11 @@
<itemizedlist>
<listitem>
+ <indexterm>
+ <primary>LCP (Local Checkpoint)</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
<para>
<emphasis role="bold">Local Checkpoint (LCP)</emphasis>:
This is a checkpoint that is specific to a single node;
@@ -176,6 +198,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>GCP (Global Checkpoint)</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Global Checkpoint (GCP)</emphasis>:
A GCP occurs every few seconds, when transactions for all
@@ -188,6 +214,23 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>node</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary> management (MGM) node</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>SQL node (API node)</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>data node</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
<para>
<emphasis role="bold">Node</emphasis>: A component of MySQL
Cluster. 3 node types are supported:
@@ -203,6 +246,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>node failure</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Node Failure</emphasis>: MySQL Cluster
is not solely dependent upon the functioning of any single
@@ -212,6 +259,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>node restart</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Node Restart</emphasis>: The process of
restarting a failed cluster node.
@@ -219,6 +270,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>initial node restart</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Initial Node Restart</emphasis>: The
process of starting a cluster node with its filesystem
@@ -228,6 +283,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>system crash</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">System Crash</emphasis> (or
<emphasis role="bold">System Failure</emphasis>): This can
@@ -237,6 +296,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>system restart</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">System Restart</emphasis>: The process
of restarting the cluster and reinitialising its state from
@@ -246,6 +309,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>fragment</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Fragment</emphasis>: Contains a portion
of a database table; in other words, in the
@@ -257,6 +324,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>replica</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Replica</emphasis>: Under the
<literal>NDB</literal> storage engine, each table fragment has
@@ -265,6 +336,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>transporter</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">Transporter</emphasis>: A protocol
providing data transfer across a network. The NDB API supports
@@ -282,6 +357,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>NDB</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<literal>NDB</literal>: This originally stood for
<quote>Network Database</quote>. It now refers to the storage
@@ -291,6 +370,14 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>ACC</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Access Manager</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">ACC</emphasis>: Access Manager. Handles
hash indexes of primary keys providing speedy access to the
@@ -299,6 +386,14 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>TUP</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Tuple Manager</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">TUP</emphasis>: Tuple Manager. This
handles storage of tuples (records) and contains the filtering
@@ -308,6 +403,14 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>TC</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Transaction Co-ordinator</primary>
+ <secondary>defined</secondary>
+ </indexterm>
<para>
<emphasis role="bold">TC</emphasis>: Transaction Co-ordinator.
Handles co-ordination of transactions and timeouts; serves as
@@ -337,6 +440,16 @@
<section id="overview-ndb-classes">
<title>Core NDB API Classes</title>
+
+ <indexterm>
+ <primary>NDB API</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>NDB API classes</primary>
+ <secondary>overview</secondary>
+ </indexterm>
<para>
The NDB API is a MySQL Cluster application interface that
@@ -435,6 +548,11 @@
<section id="overview-application-programs">
<title>Application Program Basics</title>
+
+ <indexterm>
+ <primary>applications</primary>
+ <secondary>structure</secondary>
+ </indexterm>
<para>
The main structure of an application program is as follows:
@@ -481,6 +599,11 @@
<section id="overview-using-transactions">
<title>Using Transactions</title>
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>using</secondary>
+ </indexterm>
<para>
The procedure for using transactions is as follows:
@@ -518,6 +641,16 @@
The operation can be of two different types —
<literal>Commit</literal> or <literal>NoCommit</literal>:
</para>
+
+ <indexterm>
+ <primary><literal>Commit</literal></primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary><literal>NoCommit</literal></primary>
+ <secondary>defined</secondary>
+ </indexterm>
<itemizedlist>
@@ -554,6 +687,11 @@
<section id="overview-synchronous-transactions">
<title>Synchronous Transactions</title>
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>synchronous</secondary>
+ </indexterm>
<para>
Synchronous transactions are defined and executed as follows:
@@ -572,6 +710,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary><literal>NdbTransaction</literal> class methods</primary>
+ <secondary>using</secondary>
+ </indexterm>
<para>
Define operations and add them to the transaction, using
one or more of the following:
@@ -643,6 +785,16 @@
<section id="overview-operations">
<title>Operations</title>
+
+ <indexterm>
+ <primary>operations</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>operations</primary>
+ <secondary>transactions and</secondary>
+ </indexterm>
<para>
An <literal>NdbTransaction</literal> consists of a list of
@@ -656,7 +808,12 @@
<section id="overview-single-row-operations">
- <title>Single row operations</title>
+ <title>Single-row operations</title>
+
+ <indexterm>
+ <primary>operations</primary>
+ <secondary>single-row</secondary>
+ </indexterm>
<para>
After the operation is created using
@@ -694,6 +851,11 @@
Here are two brief examples illustrating this process. For
the sake of brevity, we omit error handling.
</para>
+
+ <indexterm>
+ <primary><literal>NdbOperation</literal> class</primary>
+ <secondary>example</secondary>
+ </indexterm>
<para>
This first example uses an <literal>NdbOperation</literal>:
@@ -701,25 +863,30 @@
<programlisting>
// 1. Retrieve table object
-myTable= myDict->getTable("MYTABLENAME");
+myTable= myDict->getTable("MYTABLENAME");
// 2. Create
myOperation= myTransaction->getNdbOperation(myTable);
// 3. Define type of operation and lock mode
-myOperation->readTuple(NdbOperation::LM_Read);
+myOperation->readTuple(NdbOperation::LM_Read);
// 4. Specify Search Conditions
-myOperation->equal("ATTR1", i);
+myOperation->equal("ATTR1", i);
// 5. Attribute Actions
-myRecAttr= myOperation->getValue("ATTR2", NULL);
+myRecAttr= myOperation->getValue("ATTR2", NULL);
</programlisting>
<para>
For additional examples of this sort, see
<xref linkend="example-synchronous-transactions"/>.
</para>
+
+ <indexterm>
+ <primary><literal>NdbIndexOperation</literal> class</primary>
+ <secondary>example</secondary>
+ </indexterm>
<para>
The second example uses an
@@ -728,19 +895,19 @@
<programlisting>
// 1. Retrieve index object
-myIndex= myDict->getIndex("MYINDEX", "MYTABLENAME");
+myIndex= myDict->getIndex("MYINDEX", "MYTABLENAME");
// 2. Create
-myOperation= myTransaction->getNdbIndexOperation(myIndex);
+myOperation= myTransaction->getNdbIndexOperation(myIndex);
// 3. Define type of operation and lock mode
-myOperation->readTuple(NdbOperation::LM_Read);
+myOperation->readTuple(NdbOperation::LM_Read);
// 4. Specify Search Conditions
-myOperation->equal("ATTR1", i);
+myOperation->equal("ATTR1", i);
// 5. Attribute Actions
-myRecAttr = myOperation->getValue("ATTR2", NULL);
+myRecAttr = myOperation->getValue("ATTR2", NULL);
</programlisting>
<para>
@@ -807,8 +974,9 @@
<para>
All of these operations operate on the unique tuple key.
- When NdbIndexOperation is used, then each of these
- operations operates on a defined unique hash index.
+ When <literal>NdbIndexOperation</literal> is used, then
+ each of these operations operates on a defined unique
+ hash index.
</para>
<note>
@@ -816,9 +984,10 @@
<para>
If you want to define multiple operations within the
same transaction, then you need to call
- NdbTransaction::getNdbOperation() or
- NdbTransaction::getNdbIndexOperation() for each
- operation.
+ <literal>NdbTransaction::getNdbOperation()</literal>
+ or
+ <literal>NdbTransaction::getNdbIndexOperation()</literal>
+ for each operation.
</para>
</note>
@@ -921,6 +1090,15 @@
<section id="overview-scan-operations">
<title>Scan Operations</title>
+
+ <indexterm>
+ <primary>operations</primary>
+ <secondary>scanning</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>scan operations</primary>
+ </indexterm>
<para>
Scans are roughly the equivalent of SQL cursors, providing a
@@ -929,6 +1107,11 @@
<literal>NdbScanOperation</literal>) or an ordered index (by
means of an <literal>NdbIndexScanOperation</literal>).
</para>
+
+ <indexterm>
+ <primary>scan operations</primary>
+ <secondary>characteristics</secondary>
+ </indexterm>
<para>
Scan operations have the following characteristics:
@@ -1024,13 +1207,13 @@
<programlisting>
// 1. Retrieve table object
-myTable= myDict->getTable("MYTABLENAME");
+myTable= myDict->getTable("MYTABLENAME");
// 2. Create
-myOperation= myTransaction->getNdbScanOperation(myTable);
+myOperation= myTransaction->getNdbScanOperation(myTable);
// 3. Define type of operation and lock mode
-myOperation->readTuples(NdbOperation::LM_Read);
+myOperation->readTuples(NdbOperation::LM_Read);
// 4. Specify Search Conditions
NdbScanFilter sf(myOperation);
@@ -1040,7 +1223,7 @@
sf.end();
// 5. Attribute Actions
-myRecAttr= myOperation->getValue("ATTR2", NULL);
+myRecAttr= myOperation->getValue("ATTR2", NULL);
</programlisting>
<para>
@@ -1050,21 +1233,21 @@
<programlisting>
// 1. Retrieve index object
-myIndex= myDict->getIndex("MYORDEREDINDEX", "MYTABLENAME");
+myIndex= myDict->getIndex("MYORDEREDINDEX", "MYTABLENAME");
// 2. Create
-myOperation= myTransaction->getNdbIndexScanOperation(myIndex);
+myOperation= myTransaction->getNdbIndexScanOperation(myIndex);
// 3. Define type of operation and lock mode
-myOperation->readTuples(NdbOperation::LM_Read);
+myOperation->readTuples(NdbOperation::LM_Read);
// 4. Specify Search Conditions
// All rows with ATTR1 between i and (i+1)
-myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundGE, i);
-myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundLE, i+1);
+myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundGE, i);
+myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundLE, i+1);
// 5. Attribute Actions
-myRecAttr = MyOperation->getValue("ATTR2", NULL);
+myRecAttr = MyOperation->getValue("ATTR2", NULL);
</programlisting>
<para>
@@ -1158,6 +1341,11 @@
<section id="overview-scans-update-delete">
<title>Using Scans to Update or Delete Rows</title>
+
+ <indexterm>
+ <primary>scan operations</primary>
+ <secondary>used for updates or deletes</secondary>
+ </indexterm>
<para>
Scanning can also be used to update or delete rows. This is
@@ -1243,6 +1431,16 @@
<section id="overview-scans-lock-handling">
<title>Lock Handling with Scans</title>
+
+ <indexterm>
+ <primary>scan operations</primary>
+ <secondary>with lock handling</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>lock handling</primary>
+ <secondary>and scan operations</secondary>
+ </indexterm>
<para>
Performing scans on either a table or an index has the
@@ -1275,17 +1473,17 @@
int check;
// Outer loop for each batch of rows
-while((check = MyScanOperation->nextResult(true)) == 0)
+while((check = MyScanOperation->nextResult(true)) == 0)
{
do
{
// Inner loop for each row within the batch
- MyScanOperation->deleteCurrentTuple();
+ MyScanOperation->deleteCurrentTuple();
}
- while((check = MyScanOperation->nextResult(false)) == 0);
+ while((check = MyScanOperation->nextResult(false)) == 0);
// When there are no more rows in the batch, exeute all defined deletes
- MyTransaction->execute(NoCommit);
+ MyTransaction->execute(NoCommit);
}
</programlisting>
@@ -1299,6 +1497,11 @@
<section id="overview-error-handling">
<title>Error Handling</title>
+
+ <indexterm>
+ <primary>error handling</primary>
+ <secondary>overview</secondary>
+ </indexterm>
<para>
Errors can occur either when operations making up a
@@ -1337,21 +1540,21 @@
</para>
<programlisting>
-theTransaction = theNdb->startTransaction();
-theOperation = theTransaction->getNdbOperation("TEST_TABLE");
+theTransaction = theNdb->startTransaction();
+theOperation = theTransaction->getNdbOperation("TEST_TABLE");
if(theOperation == NULL)
goto error;
-theOperation->readTuple(NdbOperation::LM_Read);
-theOperation->setValue("ATTR_1", at1);
-theOperation->setValue("ATTR_2", at1); // Error occurs here
-theOperation->setValue("ATTR_3", at1);
-theOperation->setValue("ATTR_4", at1);
+theOperation->readTuple(NdbOperation::LM_Read);
+theOperation->setValue("ATTR_1", at1);
+theOperation->setValue("ATTR_2", at1); // Error occurs here
+theOperation->setValue("ATTR_3", at1);
+theOperation->setValue("ATTR_4", at1);
if(theTransaction->execute(Commit) == -1)
{
- errorLine = theTransaction->getNdbErrorLine();
- errorOperation = theTransaction->getNdbErrorOperation();
+ errorLine = theTransaction->getNdbErrorLine();
+ errorOperation = theTransaction->getNdbErrorOperation();
}
</programlisting>
@@ -1463,6 +1666,10 @@
<itemizedlist>
<listitem>
+ <indexterm>
+ <primary>TC</primary>
+ <secondary>and NDB Kernel</secondary>
+ </indexterm>
<para>
<emphasis role="bold">TC</emphasis>: The transaction
co-ordinator.
@@ -1470,6 +1677,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>ACC</primary>
+ <secondary>and NDB Kernel</secondary>
+ </indexterm>
<para>
<emphasis role="bold">ACC</emphasis>: The index storage
component.
@@ -1477,6 +1688,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>TUP</primary>
+ <secondary>and NDB Kernel</secondary>
+ </indexterm>
<para>
<emphasis role="bold">TUP</emphasis>: The data storage
component.
@@ -1506,6 +1721,11 @@
<section id="overview-selecting-tc">
<title>Selecting a Transaction Co-Ordinator</title>
+
+ <indexterm>
+ <primary>TC</primary>
+ <secondary>selecting</secondary>
+ </indexterm>
<para>
The default method is to select the transaction co-ordinator
@@ -1591,6 +1811,17 @@
<section id="overview-ndb-record-structure">
<title>NDB Record Structure</title>
+
+
+ <indexterm>
+ <primary>NDB</primary>
+ <secondary>record structure</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>record structure</primary>
+ <secondary>NDB</secondary>
+ </indexterm>
<para>
The <literal>NDB Cluster</literal> storage engine used by
@@ -1629,6 +1860,15 @@
<para>
<emphasis role="bold">Concurrency Control</emphasis>
</para>
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>concurrency</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>concurrency control</primary>
+ </indexterm>
<para>
<literal>NDB Cluster</literal> uses <firstterm>pessimistic
@@ -1651,6 +1891,12 @@
<para>
<emphasis role="bold">Hints and Performance</emphasis>
</para>
+
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>performance</secondary>
+ </indexterm>
<para>
Placing the transaction co-ordinator in close proximity to the
@@ -1704,6 +1950,11 @@
<section id="overview-adaptive-send">
<title>The Adaptive Send Algorithm</title>
+
+ <indexterm>
+ <primary>transactions</primary>
+ <secondary>handling and transmission</secondary>
+ </indexterm>
<abstract>
@@ -1724,6 +1975,10 @@
send algorithm decides when transactions should actually be
transferred to the NDB kernel.
</para>
+
+ <indexterm>
+ <primary>threading</primary>
+ </indexterm>
<para>
The NDB API is designed as a multi-threaded interface, and so it
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r1984 - trunk/ndbapi | jon | 2 May |
