Author: jstephens
Date: 2007-10-04 12:13:26 +0200 (Thu, 04 Oct 2007)
New Revision: 7968
Log:
Revised description of event handling (Thanks, Tomas!)
Modified:
trunk/ndbapi/ndb-classes.xml
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2007-10-04 08:49:53 UTC (rev 7967)
+++ trunk/ndbapi/ndb-classes.xml 2007-10-04 10:13:26 UTC (rev 7968)
Changed blocks: 11, Lines Added: 64, Lines Deleted: 73; 8983 bytes
@@ -1383,14 +1383,25 @@
<title>Description</title>
<para>
- This method waits for an event to occur, and returns as soon
- as an event is detected in any existing subscription
- belonging to the <literal>Ndb</literal> object for which the
- method is invoked. It is used to determine whether any
- events are available in the subscription queue.
+ This method waits for a GCP to complete. It is used to
+ determine whether any events are available in the
+ subscription queue.
</para>
</formalpara>
+
+ &mccge-warning-begin;
+
+ <para>
+ Beginning with MySQL 5.1.22-ndb-6.2.5, this method waits for
+ the next <emphasis>epoch</emphasis>, rather than the next GCP.
+ See <xref linkend="class-ndbeventoperation"/>, for more
+ information about the differences in event handling for this
+ and later &mccge-series; 6.2.<replaceable>x</replaceable>
+ releases.
+ </para>
+
+ &mccge-warning-end-api;
<formalpara>
@@ -1432,9 +1443,7 @@
<para>
The index of the most recent global checkpoint.
Normally, this may safely be permitted to assume its
- default value, which is
- <emphasis role="bold"
- >0</emphasis>.
+ default value, which is <literal>0</literal>.
</para>
</listitem>
@@ -1556,8 +1565,7 @@
object representing the next event in a subscription queue,
if there is such an event. If there is no event in the
queue, it returns <literal>NULL</literal> instead. (See
- <xref
- linkend="class-ndbeventoperation"/>.)
+ <xref linkend="class-ndbeventoperation"/>.)
</para>
</formalpara>
@@ -26319,6 +26327,8 @@
<para>
This section describes the <literal>NdbEventOperation</literal>
class, which is used to monitor changes (events) in a database.
+ It provides the core functionality used to implement MySQL
+ Cluster Replication.
</para>
</abstract>
@@ -26388,10 +26398,11 @@
<formalpara>
- <title>Limitations</title>
+ <title>Known Issues</title>
<para>
- The following limitations apply to this class:
+ The following issues may be encountered when working with event
+ operations in the <literal>NDB</literal> API:
<itemizedlist>
@@ -26399,51 +26410,14 @@
<para>
The maximum number of active
<literal>NdbEventOperation</literal> objects is currently
- fixed at compile time at 100. This may become a
+ fixed at compile time at <literal>2 *
+ MaxNoOfTables</literal>. This may become a seperately
configurable parameter in a future release.
</para>
</listitem>
<listitem>
<para>
- The maximum number of <literal>NdbEventOperation</literal>
- objects associated with a single event in one process is
- 16.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- </formalpara>
-
- <formalpara>
-
- <title>Known Issues</title>
-
- <para>
- The following issues may be encountered when working with event
- operations in the <literal>NDB</literal> API:
-
- <itemizedlist>
-
- <listitem>
- <para>
- When several instances of
- <literal>NdbEventOperation</literal> are tied to the same
- event in the same process, they share the circular buffer
- (set as the <replaceable>bufferLength</replaceable>
- parameter to
- <literal>Ndb::createEventOperation()</literal>), which is
- therefore the same for all such instances and determined
- when the first one is instantiated. For this reason, you
- should make sure to instantiate the <quote>largest</quote>
- instance first.
- </para>
- </listitem>
-
- <listitem>
- <para>
Currently, all <literal>INSERT</literal>,
<literal>DELETE</literal>, and <literal>UPDATE</literal>
events — as well as all attribute changes —
@@ -26473,30 +26447,31 @@
schema version. When a table is dropped, make sure that
you drop any associated events.
</para>
- </listitem>
- <listitem>
<para>
- On a replicated Cluster, each event is received multiple
- times — once for each replica. However, if a node
- fails, events are no longer received multiple times for
- data in the corresponding fragment.
+ We intend to remedy this issue in a future release of
+ MySQL Cluster and the <literal>NDB</literal> API.
</para>
</listitem>
<listitem>
<para>
- Following the failure of a node, not all events will be
- received any longer. You should drop any associated
- <literal>NdbEventOperation</literal> objects and re-create
- them after once the node is running again.
+ If you have received a complete epoch, events from this
+ epoch are not re-sent, even in the event of a node
+ failure. However, if a node failure has occurred,
+ subsequent epochs may contain duplicate events, which can
+ be identified by duplicated primary keys.
</para>
+
+ <para>
+ In the MySQL Cluster replication code, duplicate primary
+ keys on <literal>INSERT</literal> operations are normally
+ handled by treating such inserts as
+ <literal>REPLACE</literal> operations.
+ </para>
</listitem>
</itemizedlist>
-
- We intend to remedy these issues in future releases of MySQL
- Cluster and the <literal>NDB</literal> API.
</para>
</formalpara>
@@ -26919,9 +26894,10 @@
This method does <emphasis>not</emphasis> fetch the
attribute value from the database, and the
<literal>NdbRecAttr</literal> object returned by this method
- is not readable or printable before calling the execute()
- method and <literal>Ndb::nextEvent()</literal> has returned
- not <literal>NULL</literal>.
+ is not readable or printable before calling the
+ <literal>execute()</literal> method and
+ <literal>Ndb::nextEvent()</literal> has returned a
+ non-<literal>NULL</literal> value.
</para>
<para>
@@ -27204,9 +27180,8 @@
<para>
This method is used in place of getValue() for blob
- attributes. The blob handle
- (<literal>NdbBlob</literal>)returned by this method supports
- read operations only.
+ attributes. The blob handle (<literal>NdbBlob</literal>)
+ returned by this method supports read operations only.
</para>
</formalpara>
@@ -27447,6 +27422,20 @@
</para>
</formalpara>
+
+ &mccge-warning-begin;
+
+ <para>
+ Beginning with MySQL 5.1.22-ndb-6.2.5, this method actually
+ returns the latest epoch number, and all references to GCIs in
+ the documentation for this method when using this
+ &mccge-series; version or a later &mccge-series;
+ 6.2.<replaceable>x</replaceable> version should be taken to
+ mean epoch numbers instead. This is a consequence of the
+ implementation for micro-CGPs.
+ </para>
+
+ &mccge-warning-end-api;
<note>
<para>
@@ -28066,9 +28055,11 @@
Activates the <literal>NdbEventOperation</literal>, so that
it can begin receiving events. Changed attribute values may
be retrieved after <literal>Ndb::nextEvent()</literal> has
- returned not <literal>NULL</literal>.
- <literal>getValue()</literal> or
- <literal>getPreValue()</literal> must be called before
+ returned a value other than <literal>NULL</literal>. One of
+ <literal>getValue()</literal>,
+ <literal>getPreValue()</literal>,
+ <literal>getBlobValue()</literal>, or
+ <literal>getPreBlobValue()</literal> must be called before
invoking <literal>execute()</literal>.
</para>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r7968 - trunk/ndbapi | jon | 4 Oct |
