Ndb.hpp

/*
   Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; version 2 of the License.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
*/

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif  
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif


#ifndef Ndb_H
#define Ndb_H

#include <ndb_types.h>
#include "ndbapi_limits.h"
#include "ndb_cluster_connection.hpp"
#include "NdbError.hpp"
#include "NdbDictionary.hpp"

class NdbObjectIdMap;
class NdbOperation;
class NdbEventOperationImpl;
class NdbScanOperation;
class NdbIndexScanOperation;
class NdbIndexOperation;
class NdbTransaction;
class NdbApiSignal;
class NdbRecAttr;
class NdbLabel;
class NdbBranch;
class NdbSubroutine;
class NdbCall;
class Table;
class BaseString;
class NdbEventOperation;
class NdbBlob;
class NdbReceiver;
class TransporterFacade;
class PollGuard;
class Ndb_local_table_info;
template <class T> struct Ndb_free_list_t;
class NdbLockHandle;

typedef void (* NdbEventCallback)(NdbEventOperation*, Ndb*, void*);

#define WAITFOR_RESPONSE_TIMEOUT 120000 // Milliseconds

#define NDB_SYSTEM_DATABASE "sys"
#define NDB_SYSTEM_SCHEMA "def"

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
// to be documented later
/*
 * If one Ndb object is used to handle parallel transactions through the 
 * asynchronous programming interface, please read the notes regarding
 * asynchronous transactions (Section @ref secAsync).
 * The asynchronous interface provides much higher performance 
 * in some situations, but is more complicated for the application designer. 
 *
 * @note Each Ndb object should either use the methods for 
 *       asynchronous transaction or the methods for 
 *       synchronous transactions but not both.
 */
#endif

class Ndb
{
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  friend class NdbReceiver;
  friend class NdbOperation;
  friend class NdbEventOperationImpl;
  friend class NdbEventBuffer;
  friend class NdbTransaction;
  friend class Table;
  friend class NdbApiSignal;
  friend class NdbIndexOperation;
  friend class NdbScanOperation;
  friend class NdbIndexScanOperation;
  friend class NdbDictionary::Dictionary;
  friend class NdbDictionaryImpl;
  friend class NdbDictInterface;
  friend class NdbBlob;
  friend class NdbImpl;
  friend class Ndb_cluster_connection;
  friend class Ndb_cluster_connection_impl;
  friend class Ndb_internal;
  friend class NdbScanFilterImpl;
  friend class PollGuard;
  friend class NdbQueryImpl;
  friend class NdbQueryOperationImpl;
#endif

public:
  Ndb(Ndb_cluster_connection *ndb_cluster_connection,
      const char* aCatalogName = "", const char* aSchemaName = "def");

  ~Ndb();

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

  Ndb_cluster_connection& get_ndb_cluster_connection();
#endif

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

  const char * getCatalogName() const;

  int setCatalogName(const char * aCatalogName);

  const char * getSchemaName() const;

  int setSchemaName(const char * aSchemaName);
#endif

  const char * getDatabaseName() const;

  int setDatabaseName(const char * aDatabaseName);

  const char * getDatabaseSchemaName() const;

  int setDatabaseSchemaName(const char * aDatabaseSchemaName);

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

  int setDatabaseAndSchemaName(const NdbDictionary::Table* t);
#endif

  int init(int maxNoOfTransactions = 4);

#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED

  int waitUntilReady(int timeout = 60);
#endif

  class NdbDictionary::Dictionary* getDictionary() const;
  

  NdbEventOperation* createEventOperation(const char* eventName);
  int dropEventOperation(NdbEventOperation* eventOp);

  int pollEvents(int aMillisecondNumber, Uint64 *latestGCI= 0);

  NdbEventOperation *nextEvent();

  bool isConsistent(Uint64& gci);

  bool isConsistentGCI(Uint64 gci);

  const NdbEventOperation*
    getGCIEventOperations(Uint32* iter, Uint32* event_types);
  

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  int flushIncompleteEvents(Uint64 gci);
  NdbEventOperation *getEventOperation(NdbEventOperation* eventOp= 0);
  Uint64 getLatestGCI();
  void forceGCP();
  void setReportThreshEventGCISlip(unsigned thresh);
  void setReportThreshEventFreeMem(unsigned thresh);
#endif

  NdbTransaction* startTransaction(const NdbDictionary::Table *table= 0,
                                   const char  *keyData = 0, 
                                   Uint32       keyLen = 0);


  struct Key_part_ptr
  {
    const void * ptr;
    unsigned len;
  };

  struct PartitionSpec
  {
    enum SpecType
    {
      PS_NONE                = 0,
      PS_USER_DEFINED        = 1,
      PS_DISTR_KEY_PART_PTR  = 2,
      PS_DISTR_KEY_RECORD    = 3
    };

    Uint32 type;
    
    union
    {
      struct {
        Uint32 partitionId;
      } UserDefined;
      
      struct {
        const Key_part_ptr* tableKeyParts;
        void* xfrmbuf;
        Uint32 xfrmbuflen;
      } KeyPartPtr;

      struct {
        const NdbRecord* keyRecord;
        const char* keyRow;
        void* xfrmbuf;
        Uint32 xfrmbuflen;
      } KeyRecord;
    };
  };

#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
  /* First version of PartitionSpec, defined here for 
   * backwards compatibility reasons
   */
  struct PartitionSpec_v1
  {
    enum SpecType
    {
      PS_NONE                = 0,
      PS_USER_DEFINED        = 1,
      PS_DISTR_KEY_PART_PTR  = 2
    };

    Uint32 type;
    
    union
    {
      struct {
        Uint32 partitionId;
      } UserDefined;
      
      struct {
        const Key_part_ptr* tableKeyParts;
        void* xfrmbuf;
        Uint32 xfrmbuflen;
      } KeyPartPtr;
    };
  };
#endif

  NdbTransaction* startTransaction(const NdbDictionary::Table *table,
                                   const struct Key_part_ptr * keyData,
                                   void* xfrmbuf = 0, Uint32 xfrmbuflen = 0);
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  NdbTransaction* startTransaction(const NdbRecord *keyRec, const char *keyData,
                                   void* xfrmbuf, Uint32 xfrmbuflen);
#endif

  NdbTransaction* startTransaction(const NdbDictionary::Table* table,
                                   Uint32 partitionId);

  static int computeHash(Uint32* hashvalueptr,
                         const NdbDictionary::Table*, 
                         const struct Key_part_ptr * keyData,
                         void* xfrmbuf = 0, Uint32 xfrmbuflen = 0);
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  static int computeHash(Uint32* hashvalueptr,
                         const NdbRecord *keyRec, const char *keyData,
                         void* xfrmbuf, Uint32 xfrmbuflen);
#endif

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

#endif
  void closeTransaction(NdbTransaction*);

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
  // to be documented later
  int  pollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
              int minNoOfEventsToWakeup = 1);

  void sendPreparedTransactions(int forceSend = 0);

  int  sendPollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
                   int minNoOfEventsToWakeup = 1,
                   int forceSend = 0);
#endif
  
  const NdbError & getNdbError() const;
  
  const NdbError & getNdbError(int errorCode);

  const char* getNdbErrorDetail(const NdbError& err, 
                                char* buff, 
                                Uint32 buffLen) const;

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

  int getNodeId();

  bool usingFullyQualifiedNames();

  enum TamperType       { 
    LockGlbChp = 1,           
    UnlockGlbChp,             
    CrashNode,                
    ReadRestartGCI,           
    InsertError               

  };

  struct TupleIdRange {
    TupleIdRange() {}
    Uint64 m_first_tuple_id;
    Uint64 m_last_tuple_id;
    Uint64 m_highest_seen;
    void reset() {
      m_first_tuple_id = ~(Uint64)0;
      m_last_tuple_id = ~(Uint64)0;
      m_highest_seen = 0;
    };
  };

  int initAutoIncrement();

  int getAutoIncrementValue(const char* aTableName, 
                            Uint64 & autoValue, Uint32 cacheSize,
                            Uint64 step = 1, Uint64 start = 1);
  int getAutoIncrementValue(const NdbDictionary::Table * aTable, 
                            Uint64 & autoValue, Uint32 cacheSize,
                            Uint64 step = 1, Uint64 start = 1);
  int getAutoIncrementValue(const NdbDictionary::Table * aTable, 
                            TupleIdRange & range, Uint64 & autoValue,
                            Uint32 cacheSize,
                            Uint64 step = 1, Uint64 start = 1);
  int readAutoIncrementValue(const char* aTableName,
                             Uint64 & autoValue);
  int readAutoIncrementValue(const NdbDictionary::Table * aTable,
                             Uint64 & autoValue);
  int readAutoIncrementValue(const NdbDictionary::Table * aTable,
                             TupleIdRange & range, Uint64 & autoValue);
  int setAutoIncrementValue(const char* aTableName,
                            Uint64 autoValue, bool modify);
  int setAutoIncrementValue(const NdbDictionary::Table * aTable,
                            Uint64 autoValue, bool modify);
  int setAutoIncrementValue(const NdbDictionary::Table * aTable,
                            TupleIdRange & range, Uint64 autoValue,
                            bool modify);
#ifdef NDBAPI_50_COMPAT
  Uint64 getAutoIncrementValue(const NdbDictionary::Table * aTable, 
                               Uint32 cacheSize = 1)
    {
      Uint64 val;
      if (getAutoIncrementValue(aTable, val, cacheSize, 1, 1) == -1)
        return ~(Uint64)0;
      return val;
    }
#endif
  bool checkUpdateAutoIncrementValue(TupleIdRange & range, Uint64 autoValue);
private:
  int getTupleIdFromNdb(const NdbTableImpl* table,
                        TupleIdRange & range, Uint64 & tupleId,
                        Uint32 cacheSize, Uint64 step = 1, Uint64 start = 1);
  int readTupleIdFromNdb(const NdbTableImpl* table,
                         TupleIdRange & range, Uint64 & tupleId);
  int setTupleIdInNdb(const NdbTableImpl* table,
                      TupleIdRange & range, Uint64 tupleId, bool modify);
  int checkTupleIdInNdb(TupleIdRange & range,
                        Uint64 tupleId);
  int opTupleIdOnNdb(const NdbTableImpl* table,
                     TupleIdRange & range, Uint64 & opValue, Uint32 op);
public:

  NdbTransaction* hupp( NdbTransaction* );
  Uint32 getReference() const { return theMyRef;}

  struct Free_list_usage
  {
    const char * m_name;
    Uint32 m_created;
    Uint32 m_free;
    Uint32 m_sizeof;
  };

  Free_list_usage * get_free_list_usage(Free_list_usage*);

  /* Get minimum known DB node version */
  Uint32 getMinDbNodeVersion() const;

  /* Get/Set per-Ndb custom data pointer */
  void setCustomData(void*);
  void* getCustomData() const;
  
  /* Some client behaviour counters to assist
   * optimisation
   */
  enum ClientStatistics
  {
    /* Latency avoidance : */
    /* Number of times user thread blocked waiting for data node response */
    WaitExecCompleteCount    = 0,  /* Waiting for PK/UK/Scan requests to complete */
    WaitScanResultCount      = 1,  /* Waiting for next scan batch(es) to arrive */
    WaitMetaRequestCount     = 2,  /* Waiting for some meta data operation to complete */

    /* Measured latency */
    WaitNanosCount           = 3,  /* Nanoseconds spent waiting for kernel response */

    /* Data transfer */
    BytesSentCount           = 4,  /* Bytes sent to kernel by this object */
    BytesRecvdCount          = 5,  /* Bytes received from kernel by this object */

    /* Work performed */
    TransStartCount          = 6,  /* Transactions started */
    TransCommitCount         = 7,  /* Transactions committed */
    TransAbortCount          = 8,  /* Transactions aborted */
    TransCloseCount          = 9,  /* Transactions closed */

    PkOpCount                = 10, /* Primary key operation count */
    UkOpCount                = 11, /* Unique key operation count */
    TableScanCount           = 12, /* Table scans */
    RangeScanCount           = 13, /* Range scans */

    /* Efficiency */
    PrunedScanCount          = 14, /* Count of scans scanning 1 fragment */
    ScanBatchCount           = 15, /* Count of scan batches received */
    ReadRowCount             = 16, /* Rows returned to API, from PK/UK/Scan */
    TransLocalReadRowCount   = 17, /* Rows returned to API from trans node */

    /* Event Api */
    DataEventsRecvdCount     = 18, /* Number of table data change events received */
    NonDataEventsRecvdCount  = 19, /* Number of non-data events received */
    EventBytesRecvdCount     = 20, /* Number of bytes of event data received */
    
    NumClientStatistics      = 21   /* End marker */
  };
  
  Uint64 getClientStat(Uint32 id) const;
  const char* getClientStatName(Uint32 id) const;
#endif

private:
/*****************************************************************************
 *     These are service routines used by the other classes in the NDBAPI.
 ****************************************************************************/
  Uint32 _unused;
  void *_unused2;

  Ndb(const Ndb&); // Not impl.
  Ndb&operator=(const Ndb&);

  void setup(Ndb_cluster_connection *ndb_cluster_connection,
             const char* aCatalogName, const char* aSchemaName);

  void connected(Uint32 block_reference);
 

  NdbTransaction*  startTransactionLocal(Uint32 aPrio, Uint32 aNode,
                                         Uint32 instance);

// Connect the connection object to the Database.
  int NDB_connect(Uint32 tNode, Uint32 instance);
  NdbTransaction* doConnect(Uint32 nodeId, Uint32 instance);
  void    doDisconnect();        
  
  NdbReceiver*          getNdbScanRec();// Get a NdbScanReceiver from idle list
  NdbLabel*             getNdbLabel();  // Get a NdbLabel from idle list
  NdbBranch*            getNdbBranch(); // Get a NdbBranch from idle list
  NdbSubroutine*        getNdbSubroutine();// Get a NdbSubroutine from idle
  NdbCall*              getNdbCall();   // Get a NdbCall from idle list
  NdbApiSignal*         getSignal();    // Get an operation from idle list
  NdbRecAttr*           getRecAttr();   // Get a receeive attribute object from
                                        // idle list of the Ndb object.
  NdbOperation*         getOperation(); // Get an operation from idle list
  NdbIndexScanOperation* getScanOperation(); // Get a scan operation from idle
  NdbIndexOperation*    getIndexOperation();// Get an index operation from idle

  NdbBlob*              getNdbBlob();// Get a blob handle etc

  NdbLockHandle*        getLockHandle(); // Get a lock handle.

  void                  releaseSignal(NdbApiSignal* anApiSignal);
  void                  releaseSignals(Uint32, NdbApiSignal*, NdbApiSignal*);
  void                  releaseSignalsInList(NdbApiSignal** pList);
  void                  releaseNdbScanRec(NdbReceiver* aNdbScanRec);
  void                  releaseNdbLabel(NdbLabel* anNdbLabel);
  void                  releaseNdbBranch(NdbBranch* anNdbBranch);
  void                  releaseNdbSubroutine(NdbSubroutine* anNdbSubroutine);
  void                  releaseNdbCall(NdbCall* anNdbCall);
  void                  releaseRecAttr (NdbRecAttr* aRecAttr);  
  void                  releaseOperation(NdbOperation* anOperation);    
  void                  releaseScanOperation(NdbIndexScanOperation*);
  void                  releaseNdbBlob(NdbBlob* aBlob);
  void                  releaseLockHandle(NdbLockHandle* lh);

  void                  check_send_timeout();
  void                  remove_sent_list(Uint32);
  Uint32                insert_completed_list(NdbTransaction*);
  Uint32                insert_sent_list(NdbTransaction*);

  // Handle a received signal. Used by both
  // synchronous and asynchronous interface
  void handleReceivedSignal(const NdbApiSignal* anApiSignal,
                            const struct LinearSectionPtr ptr[3]);
  
  int                   sendRecSignal(Uint16 aNodeId,
                                      Uint32 aWaitState,
                                      NdbApiSignal* aSignal,
                                      Uint32 nodeSequence,
                                      Uint32 *ret_conn_seq= 0);
  
  // Get block number of this NDBAPI object
  int                   getBlockNumber();
  
  /****************************************************************************
   *    These are local service routines used by this class.    
   ***************************************************************************/
  
  int                   createConIdleList(int aNrOfCon);
  int           createOpIdleList( int nrOfOp ); 

  void  freeOperation();          // Free the first idle operation.
  void  freeScanOperation();      // Free the first idle scan operation.
  void  freeIndexOperation();     // Free the first idle index operation.
  void  freeNdbCon();   // Free the first idle connection.
  void  freeSignal();   // Free the first idle signal   
  void  freeRecAttr();  // Free the first idle receive attr obj 
  void  freeNdbLabel(); // Free the first idle NdbLabel obj
  void  freeNdbBranch();// Free the first idle NdbBranch obj
  void  freeNdbSubroutine();// Free the first idle NdbSubroutine obj
  void  freeNdbCall();      // Free the first idle NdbCall obj
  void  freeNdbScanRec();   // Free the first idle NdbScanRec obj
  void  freeNdbBlob();      // Free the first etc

  NdbTransaction* getNdbCon();  // Get a connection from idle list
  
  NdbTransaction* getConnectedNdbTransaction(Uint32 nodeId, Uint32 instance);

  // Release and disconnect from DBTC a connection
  // and seize it to theConIdleList
  void  releaseConnectToNdb (NdbTransaction*);

  // Release a connection to idle list
  void  releaseNdbCon (NdbTransaction*);
  
  int   checkInitState();               // Check that we are initialized
  void  report_node_failure(Uint32 node_id);           // Report Failed node
  void  report_node_failure_completed(Uint32 node_id); // Report Failed node(NF comp.)

  void  checkFailedNode();              // Check for failed nodes

  int   NDB_connect();     // Perform connect towards NDB Kernel

  // Release arrays of NdbTransaction pointers
  void  releaseTransactionArrays();     

  Uint32  pollCompleted(NdbTransaction** aCopyArray);
  void    sendPrepTrans(int forceSend);
  void    reportCallback(NdbTransaction** aCopyArray, Uint32 aNoOfComplTrans);
  int     poll_trans(int milliSecs, int noOfEventsToWaitFor, PollGuard *pg);
  void    waitCompletedTransactions(int milliSecs, int noOfEventsToWaitFor,
                                    PollGuard *pg);
  void    completedTransaction(NdbTransaction* aTransaction);
  void    completedScanTransaction(NdbTransaction* aTransaction);

  void    abortTransactionsAfterNodeFailure(Uint16 aNodeId);

  static
  const char * externalizeTableName(const char * internalTableName,
                                    bool fullyQualifiedNames);
  const char * externalizeTableName(const char * internalTableName);
  const BaseString internalize_table_name(const char * external_name) const;

  static
  const char * externalizeIndexName(const char * internalIndexName,
                                    bool fullyQualifiedNames);
  const char * externalizeIndexName(const char * internalIndexName);
  const BaseString old_internalize_index_name(const NdbTableImpl * table,
                                              const char * external_name) const;
  const BaseString internalize_index_name(const NdbTableImpl * table,
                                          const char * external_name) const;

  static
  const BaseString getDatabaseFromInternalName(const char * internalName);
  static 
  const BaseString getSchemaFromInternalName(const char * internalName);

  void*              int2void     (Uint32 val);
  NdbReceiver*       void2rec     (void* val);
  NdbTransaction*     void2con     (void* val);
  NdbOperation*      void2rec_op  (void* val);
  NdbIndexOperation* void2rec_iop (void* val);
  NdbTransaction* lookupTransactionFromOperation(const class TcKeyConf *);

  Uint64 allocate_transaction_id();

/******************************************************************************
 *      These are the private variables in this class.  
 *****************************************************************************/
  NdbTransaction**       thePreparedTransactionsArray;
  NdbTransaction**       theSentTransactionsArray;
  NdbTransaction**       theCompletedTransactionsArray;

  Uint32                theNoOfPreparedTransactions;
  Uint32                theNoOfSentTransactions;
  Uint32                theNoOfCompletedTransactions;
  Uint32                theRemainingStartTransactions;
  Uint32                theMaxNoOfTransactions;
  Uint32                theMinNoOfEventsToWakeUp;

  Uint32                theNextConnectNode;

  bool fullyQualifiedNames;



  class NdbImpl * theImpl;
  class NdbDictionaryImpl* theDictionary;
  class NdbEventBuffer* theEventBuffer;

  NdbTransaction*       theTransactionList;
  NdbTransaction**      theConnectionArray;

  Uint32   theMyRef;        // My block reference  
  Uint32   theNode;         // The node number of our node
  
  Uint64               the_last_check_time;
  Uint64               theFirstTransId;
  // The tupleId is retrieved from DB
  const NdbDictionary::Table *m_sys_tab_0;

  Uint32                theRestartGCI;  // the Restart GCI used by DIHNDBTAMPER
  
  NdbError              theError;

  Int32                 theNdbBlockNumber;

  enum InitType {
    NotConstructed,
    NotInitialised,
    StartingInit,
    Initialised,
    InitConfigError
  } theInitState;

  NdbApiSignal* theCommitAckSignal;

  /* Cached minimum connected Db node version */
  Uint32 theCachedMinDbNodeVersion;


#ifdef POORMANSPURIFY
  int cfreeSignals;
  int cnewSignals;
  int cgetSignals;
  int creleaseSignals;
#endif

#ifdef VM_TRACE
#include <my_attribute.h>
  void printState(const char* fmt, ...)
    ATTRIBUTE_FORMAT(printf, 2, 3);
#endif
};

#endif