Commit 5499b0c5 authored by unknown's avatar unknown
Browse files

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

ndb/include/ndbapi/Ndb.hpp

+49 −40
Original line number Diff line number Diff line
@@ -328,12 +328,13 @@ 
   - Scan subset of table using @ref NdbIndexScanOperation::setBound()

   - Ordering result set ascending or descending, 

     @ref NdbIndexScanOperation::readTuples()

   - When using NdbIndexScanOperation::BoundEQ on distribution key 

     only fragment containing rows will be scanned.

   - When using NdbIndexScanOperation::BoundEQ on partition key 

     only fragments containing rows will be scanned.

   

   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. 



   @subsection secScanLocks Lock handling with scans
@@ -343,10 +344,10 @@ 


   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 

   batch parameter to @ref NdbScanOperation::readTuples.

   batch parameter to NdbScanOperation::readTuples().



   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

   locks may be released as result of the function call. Otherwise the locks

   for the current batch may be released.
@@ -380,11 +381,12 @@ 


   One recommended way to handle a transaction failure 

   (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

   -# 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 

   operations which are simultaneously executed.
@@ -392,9 +394,9 @@ 
   objects and query for their NdbError objects to find out what really

   happened.



   NdbTransaction::getNdbErrorOperation returns a reference to the 

   NdbTransaction::getNdbErrorOperation() returns a reference to the 

   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.



   @code
@@ -417,14 +419,14 @@ 
   Getting errorLine == 0 means that the error occurred when executing the 

   operations.

   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.



   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.



*******************************************************************************/

******************************************************************************/



/**

 * @page ndbapi_simple.cpp ndbapi_simple.cpp
@@ -458,32 +460,14 @@ 
   @page secAdapt  Adaptive Send Algorithm



   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.  

   Instead, the "sent" transactions are only kept in a 

   special send list (buffer) in the Ndb object to which they belong.

   The adaptive send algorithm decides when transactions should

   be transfered to the NDB kernel.

  

   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.

  

  

   Since the NDB API is designed as a multi-threaded interface, 

   The NDB API is designed as a multi-threaded interface and

   it is desirable to transfer database operations from more than 

   one thread at a time. 

   The NDB API keeps track of which Ndb objects are active in transfering
@@ -514,14 +498,36 @@ 
      later releases of NDB Cluster.

      However, to support faster than 10 ms checks, 

      there has to be support from the operating system.

   -# When calling NdbTransaction::execute synchronously or calling any 

      of the poll-methods, there is a force parameter that overrides the 

      adaptive algorithm and forces the send to all nodes.

   -# When methods that are affected by the adaptive send alorithm,

      e.g. NdbTransaction::execute(), there is a force parameter 

      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.

*/



#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
@@ -563,14 +569,17 @@ 
   

   The application programmer can however hint the NDB API which 

   transaction coordinator to use

   by providing a <em>distribution key</em> (usually the primary key).

   By using the primary key as distribution key, 

   by providing a <em>partition key</em> (usually the primary key).

   By using the primary key as partition key, 

   the transaction will be placed on the node where the primary replica

   of that record resides.

   Note that this is only a hint, the system can be 

   reconfigured and then the NDB API will choose a transaction

   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
@@ -639,7 +648,7 @@ 
   A simple example is an application that uses many simple updates where

   a transaction needs to update one record. 

   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 

   of the primary key and keyLen will be 4.

*/

ndb/include/ndbapi/NdbDictionary.hpp

+17 −10
Original line number Diff line number Diff line
@@ -286,14 +286,14 @@ public: 
    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.

     * 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

     * 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 

     * in the same database node.

     *
@@ -301,9 +301,12 @@ public: 
     * will still be used with the hashing algorithm.

     *

     * @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: 
    void setStripeSize(int size);



    /** 

     * Set distribution key

     * @see getDistributionKey

     * Set partition key

     * @see getPartitionKey

     *

     * @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



    /** @} *******************************************************************/

ndb/include/ndbapi/NdbIndexScanOperation.hpp

+1 −1
Original line number Diff line number Diff line
@@ -73,7 +73,7 @@ public: 
   *

   * For equality, it is better to use BoundEQ instead of the equivalent

   * 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

   * index keys.  All but possibly the last bound must be non-strict.

ndb/include/ndbapi/NdbOperation.hpp

+1 −1
Original line number Diff line number Diff line
@@ -731,7 +731,7 @@ public: 
  void setAbortOption(Int8 ao) { m_abortOption = ao; }

  

  /**

   * Set/get distribution/partition key

   * Set/get partition key

   */

  void setPartitionId(Uint32 id);

  void setPartitionHash(Uint32 key);

ndb/include/ndbapi/NdbTransaction.hpp

+26 −20
Original line number Diff line number Diff line
@@ -76,33 +76,35 @@ enum ExecType { 
 * @brief Represents a transaction.

 *

 * A transaction (represented by an NdbTransaction object) 

 * belongs to an Ndb object and is typically created using 

 * Ndb::startTransaction.

 * belongs to an Ndb object and is created using 

 * Ndb::startTransaction().

 * 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.

 *

 * 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. 

 * Several operations can be defined in parallel on the same 

 * NdbTransaction object. 

 * When all operations are defined, the NdbTransaction::execute

 * Several operations can be defined on the same 

 * NdbTransaction object, they will in that case be executed in parallell.

 * When all operations are defined, the execute()

 * 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 

 * NdbTransaction::execute. 

 * All allocated operations should be properly defined 

 * before calling NdbTransaction::execute.

 * execute(). All allocated operations should be properly defined 

 * before calling 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::Commit	   Executes remaining operation and commits the 

 *        	           complete 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:

 * -# AbortOption::AbortOnError (default).

 *    The transaction is aborted if there are any error during the
@@ -345,6 +347,8 @@ public: 


  /**

   * Close transaction

   *

   * @note Equivalent to to calling Ndb::closeTransaction()

   */

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

  /**
@@ -415,10 +419,7 @@ public: 
  Uint64	getTransactionId();



  /**

   * Returns the commit status of the transaction.

   *

   * @return  The commit status of the transaction, i.e. one of

   *          { NotStarted, Started, TimeOut, Committed, Aborted, NeedAbort } 

   * The commit status of the transaction.

   */

  enum CommitStatusType { 

    NotStarted,                   ///< Transaction not yet started
@@ -428,6 +429,11 @@ public: 
    NeedAbort                     ///< <i>Missing explanation</i>

  };



  /**

   * Get the commit status of the transaction.

   *

   * @return  The commit status of the transaction

   */

  CommitStatusType commitStatus();



  /** @} *********************************************************************/
@@ -449,7 +455,7 @@ public: 
   * This method is used on the NdbTransaction object to find the

   * NdbOperation causing an error.  

   * To find more information about the

   * actual error, use method NdbOperation::getNdbError 

   * actual error, use method NdbOperation::getNdbError()

   * on the returned NdbOperation object.

   *

   * @return The NdbOperation causing the latest error.