Commit 5499b0c5 authored by unknown's avatar unknown

Merge mskold@bk-internal.mysql.com:/home/bk/mysql-5.0-ndb

into mysql.com:/usr/local/home/marty/MySQL/mysql-5.0-ndb

parents c15e0f74 aae10cd1
...@@ -328,12 +328,13 @@ ...@@ -328,12 +328,13 @@
- Scan subset of table using @ref NdbIndexScanOperation::setBound() - Scan subset of table using @ref NdbIndexScanOperation::setBound()
- Ordering result set ascending or descending, - Ordering result set ascending or descending,
@ref NdbIndexScanOperation::readTuples() @ref NdbIndexScanOperation::readTuples()
- When using NdbIndexScanOperation::BoundEQ on distribution key - When using NdbIndexScanOperation::BoundEQ on partition key
only fragment containing rows will be scanned. only fragments containing rows will be scanned.
Rows are returned unordered unless sorted is set to true. Rows are returned unordered unless sorted is set to true.
@note When performing sorted scan, parameter parallelism to readTuples will @note When performing sorted scan, parameter parallelism to
NdbIndexScanOperation::readTuples() will
be ignored and max parallelism will be used instead. be ignored and max parallelism will be used instead.
@subsection secScanLocks Lock handling with scans @subsection secScanLocks Lock handling with scans
...@@ -343,10 +344,10 @@ ...@@ -343,10 +344,10 @@
But Ndb will only lock a batch of rows per fragment at a time. But Ndb will only lock a batch of rows per fragment at a time.
How many rows will be locked per fragment is controlled by the How many rows will be locked per fragment is controlled by the
batch parameter to @ref NdbScanOperation::readTuples. batch parameter to NdbScanOperation::readTuples().
To let the application handle how locks are released To let the application handle how locks are released
@ref NdbScanOperation::nextResult() have a parameter fetch_allow. NdbScanOperation::nextResult() have a parameter fetch_allow.
If NdbScanOperation::nextResult() is called with fetch_allow = false, no If NdbScanOperation::nextResult() is called with fetch_allow = false, no
locks may be released as result of the function call. Otherwise the locks locks may be released as result of the function call. Otherwise the locks
for the current batch may be released. for the current batch may be released.
...@@ -380,11 +381,12 @@ ...@@ -380,11 +381,12 @@
One recommended way to handle a transaction failure One recommended way to handle a transaction failure
(i.e. an error is reported) is to: (i.e. an error is reported) is to:
-# Rollback transaction (NdbTransaction::execute with a special parameter) -# Rollback transaction (NdbTransaction::execute() with a special parameter)
-# Close transaction -# Close transaction
-# Restart transaction (if the error was temporary) -# Restart transaction (if the error was temporary)
@note Transaction are not automatically closed when an error occur. @note Transactions are not automatically closed when an error occur. Call
Ndb::closeTransaction() to close.
Several errors can occur when a transaction holds multiple Several errors can occur when a transaction holds multiple
operations which are simultaneously executed. operations which are simultaneously executed.
...@@ -392,9 +394,9 @@ ...@@ -392,9 +394,9 @@
objects and query for their NdbError objects to find out what really objects and query for their NdbError objects to find out what really
happened. happened.
NdbTransaction::getNdbErrorOperation returns a reference to the NdbTransaction::getNdbErrorOperation() returns a reference to the
operation causing the latest error. operation causing the latest error.
NdbTransaction::getNdbErrorLine delivers the method number of the NdbTransaction::getNdbErrorLine() delivers the method number of the
erroneous method in the operation. erroneous method in the operation.
@code @code
...@@ -417,14 +419,14 @@ ...@@ -417,14 +419,14 @@
Getting errorLine == 0 means that the error occurred when executing the Getting errorLine == 0 means that the error occurred when executing the
operations. operations.
Here errorOperation will be a pointer to the theOperation object. Here errorOperation will be a pointer to the theOperation object.
NdbTransaction::getNdbError will return the NdbError object NdbTransaction::getNdbError() will return the NdbError object
including holding information about the error. including holding information about the error.
Since errors could have occurred even when a commit was reported, Since errors could have occurred even when a commit was reported,
there is also a special method, NdbTransaction::commitStatus, there is also a special method, NdbTransaction::commitStatus(),
to check the commit status of the transaction. to check the commit status of the transaction.
*******************************************************************************/ ******************************************************************************/
/** /**
* @page ndbapi_simple.cpp ndbapi_simple.cpp * @page ndbapi_simple.cpp ndbapi_simple.cpp
...@@ -458,32 +460,14 @@ ...@@ -458,32 +460,14 @@
@page secAdapt Adaptive Send Algorithm @page secAdapt Adaptive Send Algorithm
At the time of "sending" the transaction At the time of "sending" the transaction
(using NdbTransaction::execute), the transactions (using NdbTransaction::execute()), the transactions
are in reality <em>not</em> immediately transfered to the NDB Kernel. are in reality <em>not</em> immediately transfered to the NDB Kernel.
Instead, the "sent" transactions are only kept in a Instead, the "sent" transactions are only kept in a
special send list (buffer) in the Ndb object to which they belong. special send list (buffer) in the Ndb object to which they belong.
The adaptive send algorithm decides when transactions should The adaptive send algorithm decides when transactions should
be transfered to the NDB kernel. be transfered to the NDB kernel.
For each of these "sent" transactions, there are three The NDB API is designed as a multi-threaded interface and
possible states:
-# Waiting to be transferred to NDB Kernel.
-# Has been transferred to the NDB Kernel and is currently
being processed.
-# Has been transferred to the NDB Kernel and has
finished processing.
Now it is waiting for a call to a poll method.
(When the poll method is invoked,
then the transaction callback method will be executed.)
The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
will return when:
-# at least 'minNoOfEventsToWakeup' of the transactions
in the send list have transitioned to state 3 as described above, and
-# all of these transactions have executed their callback methods.
Since the NDB API is designed as a multi-threaded interface,
it is desirable to transfer database operations from more than it is desirable to transfer database operations from more than
one thread at a time. one thread at a time.
The NDB API keeps track of which Ndb objects are active in transfering The NDB API keeps track of which Ndb objects are active in transfering
...@@ -514,14 +498,36 @@ ...@@ -514,14 +498,36 @@
later releases of NDB Cluster. later releases of NDB Cluster.
However, to support faster than 10 ms checks, However, to support faster than 10 ms checks,
there has to be support from the operating system. there has to be support from the operating system.
-# When calling NdbTransaction::execute synchronously or calling any -# When methods that are affected by the adaptive send alorithm,
of the poll-methods, there is a force parameter that overrides the e.g. NdbTransaction::execute(), there is a force parameter
adaptive algorithm and forces the send to all nodes. that overrides it forces the send to all nodes.
@note The times mentioned above are examples. These might @note The reasons mentioned above are examples. These might
change in later releases of NDB Cluster. change in later releases of NDB Cluster.
*/ */
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
/**
For each of these "sent" transactions, there are three
possible states:
-# Waiting to be transferred to NDB Kernel.
-# Has been transferred to the NDB Kernel and is currently
being processed.
-# Has been transferred to the NDB Kernel and has
finished processing.
Now it is waiting for a call to a poll method.
(When the poll method is invoked,
then the transaction callback method will be executed.)
The poll method invoked (either Ndb::pollNdb() or Ndb::sendPollNdb())
will return when:
-# at least 'minNoOfEventsToWakeup' of the transactions
in the send list have transitioned to state 3 as described above, and
-# all of these transactions have executed their callback methods.
*/
#endif
/** /**
@page secConcepts NDB Cluster Concepts @page secConcepts NDB Cluster Concepts
...@@ -563,14 +569,17 @@ ...@@ -563,14 +569,17 @@
The application programmer can however hint the NDB API which The application programmer can however hint the NDB API which
transaction coordinator to use transaction coordinator to use
by providing a <em>distribution key</em> (usually the primary key). by providing a <em>partition key</em> (usually the primary key).
By using the primary key as distribution key, By using the primary key as partition key,
the transaction will be placed on the node where the primary replica the transaction will be placed on the node where the primary replica
of that record resides. of that record resides.
Note that this is only a hint, the system can be Note that this is only a hint, the system can be
reconfigured and then the NDB API will choose a transaction reconfigured and then the NDB API will choose a transaction
coordinator without using the hint. coordinator without using the hint.
For more information, see NdbDictionary::Column::setDistributionKey. For more information, see NdbDictionary::Column::getPartitionKey(),
Ndb::startTransaction(). The application programmer can specify
the partition key from SQL by using the construct,
"CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<attribute list>)".
@section secRecordStruct Record Structure @section secRecordStruct Record Structure
...@@ -639,7 +648,7 @@ ...@@ -639,7 +648,7 @@
A simple example is an application that uses many simple updates where A simple example is an application that uses many simple updates where
a transaction needs to update one record. a transaction needs to update one record.
This record has a 32 bit primary key, This record has a 32 bit primary key,
which is also the distribution key. which is also the partition key.
Then the keyData will be the address of the integer Then the keyData will be the address of the integer
of the primary key and keyLen will be 4. of the primary key and keyLen will be 4.
*/ */
......
...@@ -286,14 +286,14 @@ public: ...@@ -286,14 +286,14 @@ public:
int getSize() const; int getSize() const;
/** /**
* Check if column is part of distribution key * Check if column is part of partition key
* *
* A <em>distribution key</em> is a set of attributes which are used * A <em>partition key</em> is a set of attributes which are used
* to distribute the tuples onto the NDB nodes. * to distribute the tuples onto the NDB nodes.
* The distribution key uses the NDB Cluster hashing function. * The partition key uses the NDB Cluster hashing function.
* *
* An example where this is useful is TPC-C where it might be * An example where this is useful is TPC-C where it might be
* good to use the warehouse id and district id as the distribution key. * good to use the warehouse id and district id as the partition key.
* This would place all data for a specific district and warehouse * This would place all data for a specific district and warehouse
* in the same database node. * in the same database node.
* *
...@@ -301,9 +301,12 @@ public: ...@@ -301,9 +301,12 @@ public:
* will still be used with the hashing algorithm. * will still be used with the hashing algorithm.
* *
* @return true then the column is part of * @return true then the column is part of
* the distribution key. * the partition key.
*/ */
bool getDistributionKey() const; bool getPartitionKey() const;
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
inline bool getDistributionKey() const { return getPartitionKey(); };
#endif
/** @} *******************************************************************/ /** @} *******************************************************************/
...@@ -401,13 +404,17 @@ public: ...@@ -401,13 +404,17 @@ public:
void setStripeSize(int size); void setStripeSize(int size);
/** /**
* Set distribution key * Set partition key
* @see getDistributionKey * @see getPartitionKey
* *
* @param enable If set to true, then the column will be part of * @param enable If set to true, then the column will be part of
* the distribution key. * the partition key.
*/ */
void setDistributionKey(bool enable); void setPartitionKey(bool enable);
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
inline void setDistributionKey(bool enable)
{ setPartitionKey(enable); };
#endif
/** @} *******************************************************************/ /** @} *******************************************************************/
......
...@@ -73,7 +73,7 @@ public: ...@@ -73,7 +73,7 @@ public:
* *
* For equality, it is better to use BoundEQ instead of the equivalent * For equality, it is better to use BoundEQ instead of the equivalent
* pair of BoundLE and BoundGE. This is especially true when table * pair of BoundLE and BoundGE. This is especially true when table
* distribution key is an initial part of the index key. * partition key is an initial part of the index key.
* *
* The sets of lower and upper bounds must be on initial sequences of * The sets of lower and upper bounds must be on initial sequences of
* index keys. All but possibly the last bound must be non-strict. * index keys. All but possibly the last bound must be non-strict.
......
...@@ -731,7 +731,7 @@ public: ...@@ -731,7 +731,7 @@ public:
void setAbortOption(Int8 ao) { m_abortOption = ao; } void setAbortOption(Int8 ao) { m_abortOption = ao; }
/** /**
* Set/get distribution/partition key * Set/get partition key
*/ */
void setPartitionId(Uint32 id); void setPartitionId(Uint32 id);
void setPartitionHash(Uint32 key); void setPartitionHash(Uint32 key);
......
...@@ -52,7 +52,7 @@ enum AbortOption { ...@@ -52,7 +52,7 @@ enum AbortOption {
TryCommit = 0, ///< <i>Missing explanation</i> TryCommit = 0, ///< <i>Missing explanation</i>
#endif #endif
AbortOnError = 0, ///< Abort transaction on failed operation AbortOnError = 0, ///< Abort transaction on failed operation
AO_IgnoreError = 2 ///< Transaction continues on failed operation AO_IgnoreError = 2 ///< Transaction continues on failed operation
}; };
typedef AbortOption CommitType; typedef AbortOption CommitType;
...@@ -76,33 +76,35 @@ enum ExecType { ...@@ -76,33 +76,35 @@ enum ExecType {
* @brief Represents a transaction. * @brief Represents a transaction.
* *
* A transaction (represented by an NdbTransaction object) * A transaction (represented by an NdbTransaction object)
* belongs to an Ndb object and is typically created using * belongs to an Ndb object and is created using
* Ndb::startTransaction. * Ndb::startTransaction().
* A transaction consists of a list of operations * A transaction consists of a list of operations
* (represented by NdbOperation objects). * (represented by NdbOperation, NdbScanOperation, NdbIndexOperation,
* and NdbIndexScanOperation objects).
* Each operation access exactly one table. * Each operation access exactly one table.
* *
* After getting the NdbTransaction object, * After getting the NdbTransaction object,
* the first step is to get (allocate) an operation given the table name. * the first step is to get (allocate) an operation given the table name using
* one of the methods getNdbOperation(), getNdbScanOperation(),
* getNdbIndexOperation(), or getNdbIndexScanOperation().
* Then the operation is defined. * Then the operation is defined.
* Several operations can be defined in parallel on the same * Several operations can be defined on the same
* NdbTransaction object. * NdbTransaction object, they will in that case be executed in parallell.
* When all operations are defined, the NdbTransaction::execute * When all operations are defined, the execute()
* method sends them to the NDB kernel for execution. * method sends them to the NDB kernel for execution.
* *
* The NdbTransaction::execute method returns when the NDB kernel has * The execute() method returns when the NDB kernel has
* completed execution of all operations defined before the call to * completed execution of all operations defined before the call to
* NdbTransaction::execute. * execute(). All allocated operations should be properly defined
* All allocated operations should be properly defined * before calling execute().
* before calling NdbTransaction::execute.
* *
* A call to NdbTransaction::execute uses one out of three types of execution: * A call to execute() uses one out of three types of execution:
* -# ExecType::NoCommit Executes operations without committing them. * -# ExecType::NoCommit Executes operations without committing them.
* -# ExecType::Commit Executes remaining operation and commits the * -# ExecType::Commit Executes remaining operation and commits the
* complete transaction * complete transaction
* -# ExecType::Rollback Rollbacks the entire transaction. * -# ExecType::Rollback Rollbacks the entire transaction.
* *
* NdbTransaction::execute is equipped with an extra error handling parameter * execute() is equipped with an extra error handling parameter.
* There are two alternatives: * There are two alternatives:
* -# AbortOption::AbortOnError (default). * -# AbortOption::AbortOnError (default).
* The transaction is aborted if there are any error during the * The transaction is aborted if there are any error during the
...@@ -345,6 +347,8 @@ public: ...@@ -345,6 +347,8 @@ public:
/** /**
* Close transaction * Close transaction
*
* @note Equivalent to to calling Ndb::closeTransaction()
*/ */
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
/** /**
...@@ -415,10 +419,7 @@ public: ...@@ -415,10 +419,7 @@ public:
Uint64 getTransactionId(); Uint64 getTransactionId();
/** /**
* Returns the commit status of the transaction. * The commit status of the transaction.
*
* @return The commit status of the transaction, i.e. one of
* { NotStarted, Started, TimeOut, Committed, Aborted, NeedAbort }
*/ */
enum CommitStatusType { enum CommitStatusType {
NotStarted, ///< Transaction not yet started NotStarted, ///< Transaction not yet started
...@@ -428,6 +429,11 @@ public: ...@@ -428,6 +429,11 @@ public:
NeedAbort ///< <i>Missing explanation</i> NeedAbort ///< <i>Missing explanation</i>
}; };
/**
* Get the commit status of the transaction.
*
* @return The commit status of the transaction
*/
CommitStatusType commitStatus(); CommitStatusType commitStatus();
/** @} *********************************************************************/ /** @} *********************************************************************/
...@@ -449,7 +455,7 @@ public: ...@@ -449,7 +455,7 @@ public:
* This method is used on the NdbTransaction object to find the * This method is used on the NdbTransaction object to find the
* NdbOperation causing an error. * NdbOperation causing an error.
* To find more information about the * To find more information about the
* actual error, use method NdbOperation::getNdbError * actual error, use method NdbOperation::getNdbError()
* on the returned NdbOperation object. * on the returned NdbOperation object.
* *
* @return The NdbOperation causing the latest error. * @return The NdbOperation causing the latest error.
......
...@@ -177,12 +177,12 @@ NdbDictionary::Column::getPrimaryKey() const { ...@@ -177,12 +177,12 @@ NdbDictionary::Column::getPrimaryKey() const {
} }
void void
NdbDictionary::Column::setDistributionKey(bool val){ NdbDictionary::Column::setPartitionKey(bool val){
m_impl.m_distributionKey = val; m_impl.m_distributionKey = val;
} }
bool bool
NdbDictionary::Column::getDistributionKey() const{ NdbDictionary::Column::getPartitionKey() const{
return m_impl.m_distributionKey; return m_impl.m_distributionKey;
} }
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment