Author: jstephens
Date: 2006-06-29 15:45:01 +0200 (Thu, 29 Jun 2006)
New Revision: 2551
Log:
NdbEventOperation class description (first part).
Modified:
trunk/ndbapi/ndb-classes.xml
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2006-06-29 13:44:24 UTC (rev 2550)
+++ trunk/ndbapi/ndb-classes.xml 2006-06-29 13:45:01 UTC (rev 2551)
@@ -6368,7 +6368,7 @@
<note>
<para>
For a graphical representation of this class and its
- parent-child relationships, see
+ parent-child relationships, see
<xref linkend="class-dictionary"/>.
</para>
</note>
@@ -22219,12 +22219,426 @@
<title>The <literal>NdbEventOperation</literal> Class</title>
-<!-- <abstract> -->
+ <abstract>
- <para/>
+ <para>
+ This section describes the <literal>NdbEventOperation</literal>
+ class, which is used to monitor changes (events) in a database.
+ </para>
-<!-- </abstract> -->
+ </abstract>
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ <literal>NdbEventOperation</literal> represents a database
+ event.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Creating an Instance of <literal>NdbEventOperation</literal></title>
+
+ <para>
+ This class has no public constructor or destructor. Instead,
+ instances of <literal>NdbEventOperation</literal> are created as
+ the result of method calls on <literal>Ndb</literal> and
+ <literal>NdbDictionary</literal> objects:
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ There must exist an event which was created using
+ <literal>Dictionary::createEvent()</literal>. This method
+ returns an instance of the
+ <literal>NdbDictionary::Event</literal> class. See
+ <xref linkend="class-dictionary-createevent"/>.
+ </para>
+
+ <para>
+ An <literal>NdbEventOperation</literal> object is
+ instantiated using
+ <literal>Ndb::createEventOperation()</literal>, which acts
+ on instance of <literal>NdbDictionary::Event</literal>.
+ See <xref linkend="class-ndb-createeventoperation"/>.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ See also <xref linkend="class-event"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ An instance of this class is removed by invoking
+ <literal>Ndb::dropEventOperation</literal>. See
+ <xref linkend="class-ndb-dropeventoperation"/>, for more
+ information.
+ </para>
+
+ <tip>
+ <para>
+ A detailed example demonstrating creation and removal of event
+ operations is provided in
+ <xref linkend="example-event-handling"/>.
+ </para>
+ </tip>
+
+ <formalpara>
+
+ <title>Limitations</title>
+
+ <para>
+ The following limitations apply to this class:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The maximum number of active
+ <literal>NdbEventOperation</literal> objects is currently
+ fixed at compile time at 100. This may become a
+ 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 —
+ are sent to the API, even if only some attributes have
+ been specified. However, these are hidden from the user
+ and only relevant data is shown after calling
+ <literal>Ndb::nextEvent()</literal>.
+ </para>
+
+ <para>
+ Note that false exits from
+ <literal>Ndb::pollEvents()</literal> may occur, and thus
+ the following <literal>nextEvent()</literal> call returns
+ zero, since there was no available data. In such cases,
+ simply call <literal>pollEvents()</literal> again.
+ </para>
+
+ <para>
+ See <xref linkend="class-ndb-pollevents"/>, and
+ <xref linkend="class-ndb-nextevent"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Event code does <emphasis>not</emphasis> check the table
+ 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.
+ </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.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ We intend to fix these issues in future releases of MySQL
+ Cluster and the <literal>NDB</literal> API.
+ </para>
+
+ </formalpara>
+
+ <tip>
+ <para>
+ To view the contents of the system table containing created
+ events, you can use the <command>ndb_select_all</command>
+ utility as shown here:
+
+<programlisting>
+ndb_select_all -d sys 'NDB$EVENTS_0'
+</programlisting>
+ </para>
+ </tip>
+
+ <formalpara>
+
+ <title>Public Methods</title>
+
+ <para>
+ The following table lists the public methods of this class and
+ the purpose or use of each method:
+ </para>
+
+ </formalpara>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65*"/>
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Purpose / Use</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>getState()</literal></entry>
+ <entry>Gets the current state of the event operation</entry>
+ </row>
+ <row>
+ <entry><literal>getEventType()</literal></entry>
+ <entry>Gets the event type</entry>
+ </row>
+ <row>
+ <entry><literal>getValue()</literal></entry>
+ <entry>Retrieves an attribute value</entry>
+ </row>
+ <row>
+ <entry><literal>getPreValue()</literal></entry>
+ <entry>Retrieves an attribute's previous value</entry>
+ </row>
+ <row>
+ <entry><literal>getBlobHandle()</literal></entry>
+ <entry>Gets a handle for reading blob attributes</entry>
+ </row>
+ <row>
+ <entry><literal>getPreBlobHandle()</literal></entry>
+ <entry>Gets a handle for reading the previous blob attribute</entry>
+ </row>
+ <row>
+ <entry><literal>getGCI()</literal></entry>
+ <entry>Retrieves the CGI of the most recently retrieved event</entry>
+ </row>
+ <row>
+ <entry><literal>getLatestGCI()</literal></entry>
+ <entry>Retrieves the most recent CGI (whether or not the corresponding event
+ has been retrieved)</entry>
+ </row>
+ <row>
+ <entry><literal>getNdbError()</literal></entry>
+ <entry>Gets the most recent error</entry>
+ </row>
+<!--
+ <remark role="note">
+ [js] Commenting this out until I find out what it actually
+ does...
+ </remark>
+ <row>
+ <entry><literal>isOverrun()</literal></entry>
+ <entry></entry>
+ </row>
+ -->
+ <row>
+ <entry><literal>isConsistent()</literal></entry>
+ <entry>Detects event loss caused by node failure</entry>
+ </row>
+ <row>
+ <entry><literal>tableNameChanged()</literal></entry>
+ <entry>Checks to see whether the name of a table has changed</entry>
+ </row>
+ <row>
+ <entry><literal>tableFrmChanged()</literal></entry>
+ <entry>Checks to see whether a table <filename>.FRM</filename> file has changed</entry>
+ </row>
+ <row>
+ <entry><literal>tableFragmentationChanged()</literal></entry>
+ <entry>Checks to see whether the fragmentation for a table has changed</entry>
+ </row>
+ <row>
+ <entry><literal>tableRangeListChanged()</literal></entry>
+ <entry>Checks to see whether a table range partition list name has changed</entry>
+ </row>
+ <row>
+ <entry><literal>mergeEvents()</literal></entry>
+ <entry>Allows for events to be merged</entry>
+ </row>
+ <row>
+ <entry><literal>execute()</literal></entry>
+ <entry>Activates the <literal>NdbEventOperation</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ For detailed descriptions, signatures, and examples of use for
+ each of these methods, see
+ <xref linkend="class-ndbeventoperation-members"/>.
+ </para>
+
+ <formalpara>
+
+ <title>Public Types</title>
+
+ <para>
+ <literal>NdbEventOperation</literal> defines one enumerated
+ type. See <xref linkend="class-ndbeventoperation-state"/>, for
+ details.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Class Diagram</title>
+
+ <para>
+ This diagram shows all the available methods and enumerated
+ types of the <literal>NdbEventOperation</literal> class:
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/NdbEventOperation-class.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase lang="en">Public methods of the
+ <literal>NdbEventOperation</literal> class.</phrase>
+ </textobject>
+ </mediaobject>
+ </para>
+
+ </formalpara>
+
+ <section id="class-ndbeventoperation-state">
+
+ <title><literal>NdbEventOperation::State</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This type describes the event operation's state.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Enumeration Values</title>
+
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65*"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>EO_CREATED</literal></entry>
+ <entry>The event operation has been created, but <literal>execute()</literal>
+ has not yet been called.</entry>
+ </row>
+ <row>
+ <entry><literal>EO_EXECUTING</literal></entry>
+ <entry>The <literal>execute()</literal> method has been invoked for this event
+ operation.</entry>
+ </row>
+ <row>
+ <entry><literal>EO_DROPPED</literal></entry>
+ <entry>The event operation is waiting to be deleted, and is no longer usable.</entry>
+ </row>
+ <row>
+ <entry><literal>EO_ERROR</literal></entry>
+ <entry>An error has occurred, and the event operation is unusable.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ A <literal>State</literal> value is returned by the
+ <literal>getState()</literal> method. See
+ <literal>NdbEventOperation::getState()</literal>
+
+<!--<xref linkend="class-ndbeventoperation-getstate"/>-->
+
+ , for more information.
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbeventoperation-members">
+
+ <title><literal>NdbEventOperation</literal> Class Methods</title>
+
+ <abstract>
+
+ <para>
+ This section contains definitions and descriptions of the
+ public methods of the <literal>NdbEventOperation</literal>
+ class.
+ </para>
+
+ </abstract>
+
+ </section>
+
</section>
<section id="class-ndboperation">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2551 - trunk/ndbapi | jon | 29 Jun |
