MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbEventOperation
class, which is used to monitor
changes (events) in a database. It provides the core functionality
used to implement NDB Cluster Replication.
None
None
NdbEventOperation
represents a database
event.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.41 NdbEventOperation class methods and descriptions
Name | Description |
---|---|
clearError() |
Clears the most recent error. Deprecated in NDB 7.4.3. |
execute() |
Activates the NdbEventOperation |
getBlobHandle() |
Gets a handle for reading blob attributes |
getEpoch() |
Retrieves the epoch for the event data most recently retrieved. Added in NDB 7.4.3. |
getEventType() |
Gets the event type. Deprecated in NDB 7.4.3. |
getEventType2() |
Gets the event type. Added in NDB 7.4.3. |
getGCI() |
Retrieves the GCI of the most recently retrieved event. Deprecated in NDB 7.4.3. |
getLatestGCI() |
Retrieves the most recent GCI (whether or not the corresponding event has been retrieved). Deprecated in NDB 7.4.3. |
getNdbError() |
Gets the most recent error |
getPreBlobHandle() |
Gets a handle for reading the previous blob attribute |
getPreValue() |
Retrieves an attribute's previous value |
getState() |
Gets the current state of the event operation |
getValue() |
Retrieves an attribute value |
hasError() |
Whether an error has occurred as part of this operation. Deprecated in NDB 7.4.3. |
isConsistent() |
Detects event loss caused by node failure. Deprecated in NDB 7.4.3. |
isEmptyEpoch() |
Detects an empty epoch. Added in NDB 7.4.3. |
isErrorEpoch() |
Detects an error epoch, and retrieves the error if there is one. Added in NDB 7.4.3. |
isOverrun() |
Whether event loss has taken place due to a buffer overrun. Deprecated in NDB 7.4.3. |
mergeEvents() |
Makes it possible for events to be merged |
tableFragmentationChanged() |
Checks to see whether the fragmentation for a table has changed |
tableFrmChanged() |
Checks to see whether a table .FRM file has changed |
tableNameChanged() |
Checks to see whether the name of a table has changed |
tableRangeListChanged() |
Checks to see whether a table range partition list name has changed |
NdbEventOperation
defines one enumerated
type, the
State
type.
Creating an Instance of NdbEventOperation.
This class has no public constructor or destructor. Instead,
instances of NdbEventOperation
are created as
the result of method calls on
Ndb
and
NdbDictionary
objects, subject
to the following conditions:
There must exist an event which was created using
Dictionary::createEvent()
.
This method returns an instance of the
Event
class.
An NdbEventOperation
object is instantiated
using
Ndb::createEventOperation()
,
which acts on an instance of
Event
.
An instance of this class is removed by invoking
Ndb::dropEventOperation
.
A detailed example demonstrating creation and removal of event operations is provided in Section 2.5.8, “NDB API Event Handling Example”.
Known Issues. The following issues may be encountered when working with event operations in the NDB API:
The maximum number of active
NdbEventOperation
objects is currently
fixed at compile time at 2 *
MaxNoOfTables
.
Currently, all INSERT
,
DELETE
, and UPDATE
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
Ndb::nextEvent()
.
Note that false exits from
Ndb::pollEvents()
may occur,
and thus the following nextEvent()
call
returns zero, since there was no available data. In such
cases, simply call pollEvents()
again.
Event code does not check the table schema version. When a table is dropped, make sure that you drop any associated events.
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.
In the NDB Cluster replication code, duplicate primary keys on
INSERT
operations are normally handled by
treating such inserts as REPLACE
operations.
To view the contents of the system table containing created events, you can use the ndb_select_all utility as shown here:
ndb_select_all -d sys 'NDB$EVENTS_0'
Clears the error most recently associated with this event operation.
This method is deprecated in NDB 7.4.3, and is subject to removal in a future release.
void clearError ( void )
None.
None.
Activates the
NdbEventOperation
, so that
it can begin receiving events. Changed attribute values may
be retrieved after
Ndb::nextEvent()
has
returned a value other than NULL
.
One of getValue()
,
getPreValue()
,
getBlobValue()
, or
getPreBlobValue()
must be called before
invoking execute()
.
Before attempting to use this method, you should have read the explanations provided in Ndb::nextEvent() (DEPRECATED), and NdbEventOperation::getValue(). Also see Section 2.3.16, “The NdbEventOperation Class”.
int execute ( void )
None.
This method returns 0
on success and
-1
on failure.
This method is used in place of
getValue()
for blob attributes. The blob handle
(NdbBlob
) returned by this
method supports read operations only.
To obtain the previous value for a blob attribute, use
getPreBlobHandle()
.
NdbBlob* getBlobHandle
(
const char* name
)
The name
of the blob attribute.
A pointer to an NdbBlob
object.
Gets the epoch for the latest event data retrieved.
Added in NDB 7.4.3, this method supersedes
getGCI()
,
which is now deprecated and subject to removal in a future
NDB Cluster release.
Uint64 getEpoch ( void ) const
None.
An epoch number (an integer).
This method is used to obtain the event's type
(TableEvent
).
This method is deprecated in NDB 7.4.3, and is subject to
removal in a future release. In NDB 7.4.3 and later, you
should use
getEventType2()
instead.
NdbDictionary::Event::TableEvent getEventType ( void ) const
None.
A TableEvent
value.
This method is used to obtain the event's type
(TableEvent
).
Added in NDB 7.4.3, this method supersedes
getEventType()
,
which is now deprecated and subject to removal in a future
NDB Cluster release.
getEventType2 ( void ) const
None.
A TableEvent
value.
This method retrieves the GCI for the most recently retrieved event.
This method is deprecated in NDB 7.4.3, and is subject to
removal in a future release. In NDB 7.4.3 and later, you
should use
getEpoch()
instead.
Uint64 getGCI ( void ) const
None.
The global checkpoint index of the most recently retrieved event (an integer).
This method retrieves the most recent GCI.
This method returns the latest epoch number.
The GCI obtained using this method is not necessarily associated with an event.
This method is deprecated in NDB 7.4.3, and is subject to
removal in a future release. In NDB 7.4.3 and later, you
should use
Ndb::getHighestQueuedEpoch()
instead.
Uint64 getLatestGCI ( void ) const
None.
The index of the latest global checkpoint, an integer.
This method retrieves the most recent error.
const struct NdbError& getNdbError ( void ) const
None.
A reference to an NdbError
structure.
This function is the same as
getBlobHandle()
, except that it is used
to access the previous value of the blob attribute. See
NdbEventOperation::getBlobHandle().
NdbBlob* getPreBlobHandle
(
const char* name
)
The name
of the blob attribute.
A pointer to an NdbBlob
.
This method performs identically to
getValue()
,
except that it is used to define a retrieval operation of an
attribute's previous value rather than the current
value.
NdbRecAttr* getPreValue ( const char*name
, char*value
= 0 )
This method takes the two parameters listed here:
The name
of the attribute (as
a constant character pointer).
A pointer to a value
, such
that:
If the attribute value is not
NULL
, then the attribute value is
returned in this parameter.
If the attribute value is NULL
,
then the attribute value is stored only in the
NdbRecAttr
object
returned by this method.
See
value
Buffer Memory Allocation,
for more information regarding this parameter.
An NdbRecAttr
object to
hold the value of the attribute, or a
NULL
pointer indicating that an error has
occurred.
This method gets the event operation's current state.
State getState ( void )
None.
A State
value.
This method defines the retrieval of an attribute value. The
NDB API allocates memory for the
NdbRecAttr
object that is
to hold the returned attribute value.
This method does not fetch the
attribute value from the database, and the
NdbRecAttr
object returned
by this method is not readable or printable before calling
the
execute()
method and Ndb::nextEvent()
has returned a non-NULL
value.
If a specific attribute has not changed, the corresponding
NdbRecAttr
will be in the
state UNDEFINED
. This can be checked by
using NdbRecAttr::isNULL()
which in such cases returns -1
.
getValue()
retrieves the current value.
Use
getPreValue()
for retrieving the previous value.
NdbRecAttr* getValue ( const char*name
, char*value
= 0 )
This method takes the two parameters listed here:
The name
of the attribute (as
a constant character pointer).
A pointer to a value
, such
that:
If the attribute value is not
NULL
, then the attribute value is
returned in this parameter.
If the attribute value is NULL
,
then the attribute value is stored only in the
NdbRecAttr
object
returned by this method.
See
value
Buffer Memory Allocation,
for more information regarding this parameter.
An NdbRecAttr
object to
hold the value of the attribute, or a
NULL
pointer indicating that an error has
occurred.
value
Buffer Memory Allocation.
It is the application's responsibility to allocate
sufficient memory for the value
buffer (if not NULL
), and this buffer must be
aligned appropriately. The buffer is used directly (thus
avoiding a copy penalty) only if it is aligned on a 4-byte
boundary and the attribute size in bytes (calculated as
NdbRecAttr::get_size_in_bytes()
)
is a multiple of 4.
This method is used to determine whether there is an error associated with this event operation.
This method is deprecated in NDB 7.4.3, and is subject to
removal in a future release. In NDB 7.4.3 and later, you
should instead use
getEventType2()
to determine the event type. See
Event::TableEvent.
int hasError ( void ) const
None.
If event loss has taken place, then this method returns 0; otherwise, it returns 1.
This method is used to determine whether event loss has taken place following the failure of a node.
This method is deprecated in NDB 7.4.3, and is subject to
removal in a future release. In NDB 7.4.3 and later, you
should instead use
getEventType2()
to determine whether the event is of type
TE_INCONSISTENT
. See
Event::TableEvent.
bool isConsistent ( void ) const
None.
If event loss has taken place, then this method returns
false
; otherwise, it returns
true
.
This method is used to determine whether consumed event data marks an empty epoch.
This method was added in NDB 7.4.3.
bool isEmptyEpoch ( void )
None.
If this epoch is empty, the method returns
true
; otherwise, it returns
false
.
This method is used to determine whether consumed event data marks an empty epoch.
This method was added in NDB 7.4.3.
bool isErrorEpoch
(
NdbDictionary::Event::TableEvent* error_type
= 0
)
If this is an error epoch,
error_type
contains the
TableEvent
value
corresponding to the error.
If this epoch is in error, the method returns
true
; otherwise, it returns
false
.
This method is used to determine whether event loss has taken place due to a buffer overrun.
bool isOverrun ( void ) const
None.
If the event buffer has been overrun, then this method
returns true
, otherwise, it returns
false
.
This method is used to set the merge events flag. For information about event merging, see Event::mergeEvents().
The merge events flag is false
by
default.
void mergeEvents
(
bool flag
)
A Boolean flag
.
None.
This section provides information about the
State
data type.
This type describes the event operation's state.
A State
value is returned by the
getState()
method.
Possible values are shown, along with descriptions, in the following table:
Table 2.42 NdbEventOperation data type values and descriptions
Name | Description |
---|---|
EO_CREATED |
The event operation has been created, but execute()
has not yet been called. |
EO_EXECUTING |
The execute() method has been invoked for this event
operation. |
EO_DROPPED |
The event operation is waiting to be deleted, and is no longer usable. |
EO_ERROR |
An error has occurred, and the event operation is unusable. |
This method is used to test whether a table's
fragmentation has changed in connection with a
TE_ALTER
event. (See
Event::TableEvent.)
bool tableFragmentationChanged ( void ) const
None.
Returns true
if the table's
fragmentation has changed; otherwise, the method returns
false
.
Use this method to determine whether a table
.FRM
file has changed in connection
with a TE_ALTER
event. (See
Event::TableEvent.)
bool tableFrmChanged ( void ) const
None.
Returns true
if the table
.FRM
file has changed; otherwise, the
method returns false
.
This method tests whether a table name has changed as the
result of a TE_ALTER
table event. (See
Event::TableEvent.)
bool tableNameChanged ( void ) const
None.
Returns true
if the name of the table has
changed; otherwise, the method returns
false
.
Use this method to check whether a table range partition
list name has changed in connection with a
TE_ALTER
event.
bool tableRangeListChanged ( void ) const
None.
This method returns true
if range or list
partition name has changed; otherwise it returns
false
.