Author: jstephens
Date: 2006-07-19 15:39:50 +0200 (Wed, 19 Jul 2006)
New Revision: 2773
Log:
Some updates resulting from the first part of Hartmut's review.
Modified:
trunk/ndbapi/mgm-api.xml
trunk/ndbapi/ndb-classes.xml
trunk/ndbapi/overview.xml
Modified: trunk/ndbapi/mgm-api.xml
===================================================================
--- trunk/ndbapi/mgm-api.xml 2006-07-19 10:43:30 UTC (rev 2772)
+++ trunk/ndbapi/mgm-api.xml 2006-07-19 13:39:50 UTC (rev 2773)
Changed blocks: 5, Lines Added: 13, Lines Deleted: 7; 1796 bytes
@@ -14,8 +14,8 @@
<para>
This chapter discusses the MySQL Cluster Management API, a C
language API that is used for administrative tasks such as
- starting and stopping Cluster nodes, backups, and logging. Covers
- MGM concepts, programming constructs, and event types.
+ starting and stopping Cluster nodes, backups, and logging. It also
+ covers MGM concepts, programming constructs, and event types.
</para>
</abstract>
@@ -520,7 +520,8 @@
</section>
- <section id="ndb-logevent-get-fd">
+<!--
+ <section id="ndb-logevent-get-fd">
<title><literal>ndb_logevent_get_fd()</literal></title>
@@ -582,6 +583,8 @@
</formalpara>
+-->
+
<!--
<formalpara>
@@ -596,8 +599,11 @@
</formalpara>
-->
- </section>
+<!--
+ </section>
+-->
+
<section id="ndb-logevent-get-next">
<title><literal>ndb_logevent_get_next()</literal></title>
@@ -2845,9 +2851,9 @@
If <replaceable>disconnect</replaceable> returns
<literal>1</literal> (<literal>true</literal>), this
means the you must disconnect before you can apply the
- command to stop. For example, connecting is required
- when stopping the management server to which the
- handle is connected.
+ command to stop. For example, disconnecting is
+ required when stopping the management server to which
+ the handle is connected.
</para>
</listitem>
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2006-07-19 10:43:30 UTC (rev 2772)
+++ trunk/ndbapi/ndb-classes.xml 2006-07-19 13:39:50 UTC (rev 2773)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 4; 1040 bytes
@@ -10969,12 +10969,12 @@
<entry>Undefined</entry>
</row>
<row>
- <entry><literal>SystemTable</literal></entry>
- <entry>System table</entry>
+ <entry><literal>SystemTable</literal></entry>
+ <entry>System table</entry>
</row>
<row>
- <entry><literal>UserTable</literal></entry>
- <entry>User table (may be temporary)</entry>
+ <entry><literal>UserTable</literal></entry>
+ <entry>User table (may be temporary)</entry>
</row>
<row>
<entry><literal>UniqueHashIndex</literal></entry>
Modified: trunk/ndbapi/overview.xml
===================================================================
--- trunk/ndbapi/overview.xml 2006-07-19 10:43:30 UTC (rev 2772)
+++ trunk/ndbapi/overview.xml 2006-07-19 13:39:50 UTC (rev 2773)
Changed blocks: 20, Lines Added: 140, Lines Deleted: 81; 14570 bytes
@@ -42,7 +42,7 @@
<para>
The <firstterm>NDB API</firstterm> is an object-oriented
application programming interface for MySQL Cluster that
- implements transactions, scans, and event handling. NDB
+ implements indexes, scans, transactions, and event handling. NDB
transactions are ACID-compliant in that they provide a means to
group together operations in such a way that they succeed
(commit) or fail as a unit (rollback). It is also possible to
@@ -182,7 +182,7 @@
<emphasis role="bold">Checkpoint</emphasis>: Generally
speaking, when data is saved to disk, it is said that a
checkpoint has been reached. When working with the
- <literal>NDB</literal> storage engine, there are two sort of
+ <literal>NDB</literal> storage engine, there are two sorts of
checkpoints which work together in order to ensure that a
consistent view of the cluster's data is maintained:
</para>
@@ -204,6 +204,15 @@
minutes, depending upon the amount of data stored by the
node.
</para>
+
+ <para>
+ More detailed information about LCPs and their behaviour
+ can be found in the MySQL Manual, in the sections
+ <ulink url="&refman-base-url;mysql-cluster-db-definition.html">Defining
+ MySQL Cluster Data Nodes</ulink> and
+ <ulink url="&refman-base-url;mysql-cluster-config-lcp-params.html">Configuring
+ Parameters for Local Checkpoints</ulink>.
+ </para>
</listitem>
<listitem>
@@ -215,13 +224,14 @@
<para>
<emphasis role="bold">Global Checkpoint (GCP)</emphasis>:
A GCP occurs every few seconds, when transactions for all
- nodes are synchronised and the redo-log is flushed to
+ nodes are synchronised and the REDO log is flushed to
disk.
</para>
<para>
- A related term is <firstterm>CGI</firstterm>, which stands
- for <quote>Global Check ID</quote>.
+ A related term is <firstterm>GCI</firstterm>, which stands
+ for <quote>Global Check ID</quote>. This marks the point
+ in the REDO log where a GCP took place.
</para>
</listitem>
@@ -307,7 +317,43 @@
<para>
<emphasis role="bold">Node Restart</emphasis>: The process of
- restarting a failed cluster node.
+ restarting a cluster node which has stopped on its own or been
+ stopped deliberately. This can be done for several different
+ reasons, including the following:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Restarting a node which has shut down on its own (when
+ this has occurred, it is known as <firstterm>forced
+ shutdown</firstterm> or <firstterm>node
+ failure</firstterm>; the other cases dicussed here
+ involve manually shutting down the node and restarting
+ it)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To update the node's configuration
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ As part of a software or hardware upgrade
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In order to defragment the node's
+ <literal>DataMemory</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</listitem>
@@ -539,6 +585,17 @@
<listitem>
<para>
+ <literal>NdbDictionary</literal> provides meta-information
+ about tables and attributes.
+ </para>
+
+ <para>
+ See <xref linkend="class-ndbdictionary"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
<literal>NdbTransaction</literal> represents a transaction.
</para>
@@ -601,17 +658,6 @@
</para>
</listitem>
- <listitem>
- <para>
- <literal>NdbDictionary</literal> provides meta-information
- about tables and attributes.
- </para>
-
- <para>
- See <xref linkend="class-ndbdictionary"/>.
- </para>
- </listitem>
-
</itemizedlist>
<para>
@@ -671,6 +717,14 @@
<listitem>
<para>
+ Identify the tables, columns, and indexes on which you wish
+ to operate, using <literal>NdbDictionary</literal> and one
+ or more of its subclasses.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
Define and execute transactions using the
<literal>NdbTransaction</literal> class.
</para>
@@ -752,13 +806,18 @@
<para>
If the operation is of type
<literal>NoCommit</literal>, then the application
- program executes the operation portion of a
- transaction, but without actually committing the
- transaction. After executing a
- <literal>NoCommit</literal> operation, the program
- can continue to define additional transaction
- operations for later execution.
+ program requests that the operation portion of a
+ transaction be executed, but without actually
+ committing the transaction. Following the execution
+ of a <literal>NoCommit</literal> operation, the
+ program can continue to define additional
+ transaction operations for later execution.
</para>
+
+ <para>
+ <literal>NoCommit</literal> operations can also be
+ rolled back by the application.
+ </para>
</listitem>
<listitem>
@@ -816,40 +875,41 @@
<para>
Define operations and add them to the transaction, using
one or more of the following:
- </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- <literal>NdbTransaction::getNdbOperation()</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>NdbTransaction::getNdbOperation()</literal>
+ </para>
+ </listitem>
- <listitem>
- <para>
- <literal>NdbTransaction::getNdbScanOperation()</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>NdbTransaction::getNdbScanOperation()</literal>
+ </para>
+ </listitem>
- <listitem>
- <para>
- <literal>NdbTransaction::getNdbIndexOperation()</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>NdbTransaction::getNdbIndexOperation()</literal>
+ </para>
+ </listitem>
- <listitem>
- <para>
- <literal>NdbTransaction::getNdbIndexScanOperation()</literal>
- along with the appropriate methods of the respective
- <literal>NdbOperation</literal> class (or possibly one
- or more of its subclasses). Note that, at this point,
- the transaction has still not yet been sent to the NDB
- kernel.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>NdbTransaction::getNdbIndexScanOperation()</literal>
+ </para>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
+
+ along with the appropriate methods of the
+ respective<literal>NdbOperation</literal> class (or
+ possibly one or more of its subclasses). Note that, at
+ this point, the transaction has still not yet been sent to
+ the NDB kernel.
+ </para>
</listitem>
<listitem>
@@ -964,16 +1024,16 @@
// 1. Retrieve table object
myTable= myDict->getTable("MYTABLENAME");
-// 2. Create
+// 2. Create an NdbOperation on this table
myOperation= myTransaction->getNdbOperation(myTable);
-// 3. Define type of operation and lock mode
+// 3. Define the operation's type and lock mode
myOperation->readTuple(NdbOperation::LM_Read);
-// 4. Specify Search Conditions
+// 4. Specify search conditions
myOperation->equal("ATTR1", i);
-// 5. Attribute Actions
+// 5. Perform attribute retrieval
myRecAttr= myOperation->getValue("ATTR2", NULL);
</programlisting>
@@ -1222,8 +1282,8 @@
<listitem>
<para>
- They can perform only reads. These may shared, exclusive
- or dirty.
+ They can perform read operations which may be shared,
+ exclusive, or dirty.
</para>
</listitem>
@@ -1307,23 +1367,23 @@
</para>
<programlisting>
-// 1. Retrieve table object
+// 1. Retrieve a table object
myTable= myDict->getTable("MYTABLENAME");
-// 2. Create
+// 2. Create a scan operation (NdbScanOperation) on this table
myOperation= myTransaction->getNdbScanOperation(myTable);
-// 3. Define type of operation and lock mode
+// 3. Define the operation's type and lock mode
myOperation->readTuples(NdbOperation::LM_Read);
-// 4. Specify Search Conditions
+// 4. Specify search conditions
NdbScanFilter sf(myOperation);
sf.begin(NdbScanFilter::OR);
sf.eq(0, i); // Return rows with column 0 equal to i or
sf.eq(1, i+1); // column 1 equal to (i+1)
sf.end();
-// 5. Attribute Actions
+// 5. Retrieve attributes
myRecAttr= myOperation->getValue("ATTR2", NULL);
</programlisting>
@@ -1336,18 +1396,18 @@
// 1. Retrieve index object
myIndex= myDict->getIndex("MYORDEREDINDEX", "MYTABLENAME");
-// 2. Create
+// 2. Create an operation (NdbIndexScanOperation object)
myOperation= myTransaction->getNdbIndexScanOperation(myIndex);
// 3. Define type of operation and lock mode
myOperation->readTuples(NdbOperation::LM_Read);
-// 4. Specify Search Conditions
+// 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);
-// 5. Attribute Actions
+// 5. Retrieve attributes
myRecAttr = MyOperation->getValue("ATTR2", NULL);
</programlisting>
@@ -1379,7 +1439,7 @@
<literal>NdbTransaction::getNdbScanOperation()</literal>
or
<literal>NdbTransaction::getNdbIndexScanOperation()</literal>
- separately for each operation.
+ separately for <emphasis>each</emphasis> operation.
</para>
</note>
</listitem>
@@ -1628,7 +1688,7 @@
<para>
<literal>NdbTransaction::getNdbErrorLine()</literal>
yields the method number of the erroneous method in the
- operation.
+ operation, starting with <literal>1</literal>.
</para>
</listitem>
@@ -1761,9 +1821,9 @@
<abstract>
<para>
- Covers the NDB Kernel; discusses MySQL Cluster transaction
- handling, and transaction coordinators. Also describes NDB
- record structures and concurrency issues.
+ This seciton covers the NDB Kernel, and discusses MySQL
+ Cluster transaction handling and transaction coordinators. It
+ also describes NDB record structures and concurrency issues.
</para>
</abstract>
@@ -1936,10 +1996,10 @@
<para>
The <literal>NDB Cluster</literal> storage engine used by
MySQL Cluster is a relational database engine storing records
- in tables just as with any other database system. Table rows
- represent records as tuples of relational data. When a new
- table is created, its attribute schema is specified for the
- table as a whole, and thus each table row has the same
+ in tables as with other relational database systems. Table
+ rows represent records as tuples of relational data. When a
+ new table is created, its attribute schema is specified for
+ the table as a whole, and thus each table row has the same
structure. Again, this is typical of relational databases, and
<literal>NDB</literal> is no different in this regard.
</para>
@@ -2119,12 +2179,11 @@
<listitem>
<para>
- The NDB Transporter (TCP/IP, OSE, SCI or shared memory)
- decides that a buffer is full and sends it off. The buffer
- size is implementation-dependent and may change between
- MySQL Cluster releases. When TCP/IP is the transporter, the
- buffer size is usually around 64 KB; when using OSE/Delta it
- is usually less than 2000 bytes. Since each
+ The NDB Transporter (TCP/IP, SCI, or shared memory) decides
+ that a buffer is full and sends it off. The buffer size is
+ implementation-dependent and may change between MySQL
+ Cluster releases. When TCP/IP is the transporter, the buffer
+ size is usually around 64 KB. Since each
<literal>Ndb</literal> object provides a single buffer per
data node, the notion of a <quote>full</quote> buffer is
local to each data node.
@@ -2135,7 +2194,7 @@
<para>
The accumulation of statistical data on transferred
information may force sending of buffers to all storage
- nodes.
+ nodes (that is, when all the buffers become full).
</para>
</listitem>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2773 - trunk/ndbapi | jstephens | 19 Jul |
