1 /* 2 Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. 3 4 This program is free software; you can redistribute it and/or modify 5 it under the terms of the GNU General Public License, version 2.0, 6 as published by the Free Software Foundation. 7 8 This program is also distributed with certain software (including 9 but not limited to OpenSSL) that is licensed under separate terms, 10 as designated in a particular file or component or in included license 11 documentation. The authors of MySQL hereby grant you an additional 12 permission to link the program and your derivative works with the 13 separately licensed software that they have included with MySQL. 14 15 This program is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU General Public License, version 2.0, for more details. 19 20 You should have received a copy of the GNU General Public License 21 along with this program; if not, write to the Free Software 22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 23 */ 24 25 /** 26 @mainpage NDB API Programmers' Guide 27 28 This guide assumes a basic familiarity with MySQL Cluster concepts found 29 in the MySQL Cluster documentation. 30 Some of the fundamental ones are also described in section @ref secConcepts. 31 32 The NDB API is a MySQL Cluster application interface 33 that implements transactions. 34 The NDB API consists of the following fundamental classes: 35 - Ndb_cluster_connection, representing a connection to a cluster, 36 - Ndb is the main class, representing a connection to a database, 37 - NdbTransaction represents a transaction, 38 - NdbOperation represents an operation using a primary key, 39 - NdbScanOperation represents an operation performing a full table scan. 40 - NdbIndexOperation represents an operation using a unique hash index, 41 - NdbIndexScanOperation represents an operation performing a scan using 42 an ordered index, 43 - NdbRecAttr represents an attribute value 44 - NdbRecord represents a memory layout of a row data for a particular table 45 - NdbDictionary represents meta information about tables and attributes. 46 47 In addition, the NDB API defines a structure NdbError, which contains the 48 specification for an error. 49 50 It is also possible to receive "events" triggered when data in the database in changed. 51 This is done through the NdbEventOperation class. 52 53 There are also some auxiliary classes, which are listed in the class hierarchy. 54 55 The main structure of an application program is as follows: 56 -# Connect to a cluster using the Ndb_cluster_connection 57 object. 58 -# Initiate a database connection by constructing and initialising one or more Ndb objects. 59 -# Define and execute transactions using the NdbTransaction class. 60 -# Delete Ndb objects. 61 -# Terminate the connection to the cluster (terminate instance of Ndb_cluster_connection). 62 63 The procedure for using transactions is as follows: 64 -# Start transaction (instantiate an NdbTransaction object) 65 -# Add and define operations associated with the transaction using instances of one or more of the 66 NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation classes 67 -# Execute transaction (call NdbTransaction::execute()) 68 69 The operation can be of two different types, 70 <var>Commit</var> or <var>NoCommit</var>. 71 If the operation is of type <var>NoCommit</var>, 72 then the application program executes the operation part of a transaction, 73 but without actually committing the transaction. 74 After executing a <var>NoCommit</var> operation, the program can continue 75 to add and define more operations to the transaction 76 for later execution. 77 78 If the operation is of type <var>Commit</var>, then the transaction is 79 immediately committed. The transaction <em>must</em> be closed after it has been 80 commited (even if commit fails), and no further addition or definition of 81 operations for this transaction is allowed. 82 83 @section secSync Synchronous Transactions 84 85 Synchronous transactions are defined and executed as follows: 86 87 -# Start (create) the transaction, which is 88 referenced by an NdbTransaction object 89 (typically created using Ndb::startTransaction()). 90 At this point, the transaction is only being defined, 91 and is not yet sent to the NDB kernel. 92 -# Define operations and add them to the transaction, using one or more of 93 - NdbTransaction::getNdbOperation() 94 - NdbTransaction::getNdbScanOperation() 95 - NdbTransaction::getNdbIndexOperation() 96 - NdbTransaction::getNdbIndexScanOperation() 97 - NdbTransaction::readTuple() 98 - NdbTransaction::insertTuple() 99 - NdbTransaction::updateTuple() 100 - NdbTransaction::writeTuple() 101 - NdbTransaction::deleteTuple() 102 - NdbTransaction::scanTable() 103 - NdbTransaction::scanIndex() 104 along with the appropriate methods of the respective NdbOperation class 105 (or possibly one or more of its subclasses). 106 Note that the transaction has still not yet been sent to the NDB kernel. 107 -# Execute the transaction, using the NdbTransaction::execute() method. 108 -# Close the transaction (call Ndb::closeTransaction()). 109 110 For an example of this process, see the program listing in 111 @ref ndbapi_simple.cpp. 112 113 To execute several parallel synchronous transactions, one can either 114 use multiple Ndb objects in several threads, or start multiple 115 application programs. 116 117 @section secNdbOperations Operations 118 119 A NdbTransaction consists of a list of operations, each of which is represented 120 by an instance of NdbOperation, NdbScanOperation, NdbIndexOperation, or 121 NdbIndexScanOperation. 122 123 <h3>Single row operations</h3> 124 After the operation is created using NdbTransaction::getNdbOperation() 125 (or NdbTransaction::getNdbIndexOperation()), it is defined in the following 126 three steps: 127 -# Define the standard operation type, using NdbOperation::readTuple() 128 -# Specify search conditions, using NdbOperation::equal() 129 -# Specify attribute actions, using NdbOperation::getValue() 130 131 Here are two brief examples illustrating this process. For the sake of 132 brevity, we omit error handling. 133 134 This first example uses an NdbOperation: 135 @code 136 // 1. Retrieve table object 137 myTable= myDict->getTable("MYTABLENAME"); 138 139 // 2. Create 140 myOperation= myTransaction->getNdbOperation(myTable); 141 142 // 3. Define type of operation and lock mode 143 myOperation->readTuple(NdbOperation::LM_Read); 144 145 // 4. Specify Search Conditions 146 myOperation->equal("ATTR1", i); 147 148 // 5. Attribute Actions 149 myRecAttr= myOperation->getValue("ATTR2", NULL); 150 @endcode 151 For additional examples of this sort, see @ref ndbapi_simple.cpp. 152 153 The second example uses an NdbIndexOperation: 154 @code 155 // 1. Retrieve index object 156 myIndex= myDict->getIndex("MYINDEX", "MYTABLENAME"); 157 158 // 2. Create 159 myOperation= myTransaction->getNdbIndexOperation(myIndex); 160 161 // 3. Define type of operation and lock mode 162 myOperation->readTuple(NdbOperation::LM_Read); 163 164 // 4. Specify Search Conditions 165 myOperation->equal("ATTR1", i); 166 167 // 5. Attribute Actions 168 myRecAttr = myOperation->getValue("ATTR2", NULL); 169 @endcode 170 Another example of this second type can be found in 171 @ref ndbapi_simple_index.cpp. 172 173 We will now discuss in somewhat greater detail each step involved in the 174 creation and use of synchronous transactions. 175 176 <h4>Step 1: Define single row operation type</h4> 177 The following operation types are supported: 178 -# NdbOperation::insertTuple() : 179 inserts a non-existing tuple 180 -# NdbOperation::writeTuple() : 181 updates an existing tuple if is exists, 182 otherwise inserts a new tuple 183 -# NdbOperation::updateTuple() : 184 updates an existing tuple 185 -# NdbOperation::deleteTuple() : 186 deletes an existing tuple 187 -# NdbOperation::readTuple() : 188 reads an existing tuple with specified lock mode 189 190 All of these operations operate on the unique tuple key. 191 (When NdbIndexOperation is used then all of these operations 192 operate on a defined unique hash index.) 193 194 @note If you want to define multiple operations within the same transaction, 195 then you need to call NdbTransaction::getNdbOperation() or 196 NdbTransaction::getNdbIndexOperation() for each operation. 197 198 <h4>Step 2: Specify Search Conditions</h4> 199 The search condition is used to select tuples. Search conditions are set using NdbOperation::equal(). 200 201 <h4>Step 3: Specify Attribute Actions</h4> 202 Next, it is necessary to determine which attributes should be read or updated. 203 It is important to remember that: 204 - Deletes can neither read nor set values, but only delete them 205 - Reads can only read values 206 - Updates can only set values 207 Normally the attribute is identified by name, but it is 208 also possible to use the attribute's identity to determine the 209 attribute. 210 211 NdbOperation::getValue() returns an NdbRecAttr object 212 containing the read value. 213 To obtain the actual value, one of two methods can be used; 214 the application can either 215 - use its own memory (passed through a pointer aValue) to 216 NdbOperation::getValue(), or 217 - receive the attribute value in an NdbRecAttr object allocated 218 by the NDB API. 219 220 The NdbRecAttr object is released when Ndb::closeTransaction() 221 is called. 222 Thus, the application cannot reference this object following 223 any subsequent call to Ndb::closeTransaction(). 224 Attempting to read data from an NdbRecAttr object before 225 calling NdbTransaction::execute() yields an undefined result. 226 227 228 @subsection secScan Scan Operations 229 230 Scans are roughly the equivalent of SQL cursors, providing a means to 231 preform high-speed row processing. A scan can be performed 232 on either a table (using @ref NdbScanOperation) or 233 an ordered index (by means of an @ref NdbIndexScanOperation). 234 235 Scan operations are characterised by the following: 236 - They can perform only reads (shared, exclusive or dirty) 237 - They can potentially work with multiple rows 238 - They can be used to update or delete multiple rows 239 - They can operate on several nodes in parallel 240 241 After the operation is created using NdbTransaction::getNdbScanOperation() 242 (or NdbTransaction::getNdbIndexScanOperation()), 243 it is carried out in the following three steps: 244 -# Define the standard operation type, using NdbScanOperation::readTuples() 245 -# Specify search conditions, using @ref NdbScanFilter and/or 246 @ref NdbIndexScanOperation::setBound() 247 -# Specify attribute actions, using NdbOperation::getValue() 248 -# Executing the transaction, using NdbTransaction::execute() 249 -# Traversing the result set by means of succssive calls to 250 NdbScanOperation::nextResult() 251 252 Here are two brief examples illustrating this process. Once again, in order 253 to keep things relatively short and simple, we will forego any error handling. 254 255 This first example performs a table scan, using an NdbScanOperation: 256 @code 257 // 1. Retrieve table object 258 myTable= myDict->getTable("MYTABLENAME"); 259 260 // 2. Create 261 myOperation= myTransaction->getNdbScanOperation(myTable); 262 263 // 3. Define type of operation and lock mode 264 myOperation->readTuples(NdbOperation::LM_Read); 265 266 // 4. Specify Search Conditions 267 NdbScanFilter sf(myOperation); 268 sf.begin(NdbScanFilter::OR); 269 sf.eq(0, i); // Return rows with column 0 equal to i or 270 sf.eq(1, i+1); // column 1 equal to (i+1) 271 sf.end(); 272 273 // 5. Attribute Actions 274 myRecAttr= myOperation->getValue("ATTR2", NULL); 275 @endcode 276 277 Our second example uses an NdbIndexScanOperation to perform an index scan: 278 @code 279 // 1. Retrieve index object 280 myIndex= myDict->getIndex("MYORDEREDINDEX", "MYTABLENAME"); 281 282 // 2. Create 283 myOperation= myTransaction->getNdbIndexScanOperation(myIndex); 284 285 // 3. Define type of operation and lock mode 286 myOperation->readTuples(NdbOperation::LM_Read); 287 288 // 4. Specify Search Conditions 289 // All rows with ATTR1 between i and (i+1) 290 myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundGE, i); 291 myOperation->setBound("ATTR1", NdbIndexScanOperation::BoundLE, i+1); 292 293 // 5. Attribute Actions 294 myRecAttr = MyOperation->getValue("ATTR2", NULL); 295 @endcode 296 297 Some additional discussion of each step required to perform a scan follows: 298 299 <h4>Step 1: Define Scan Operation Type</h4> 300 It is important to remember that only a single operation is supported for each scan operation 301 (@ref NdbScanOperation::readTuples() or @ref NdbIndexScanOperation::readTuples()). 302 303 @note If you want to define multiple scan operations within the same 304 transaction, then you need to call 305 NdbTransaction::getNdbScanOperation() or 306 NdbTransaction::getNdbIndexScanOperation() separately for <b>each</b> operation. 307 308 <h4>Step 2: Specify Search Conditions</h4> 309 The search condition is used to select tuples. 310 If no search condition is specified, the scan will return all rows 311 in the table. 312 313 The search condition can be an @ref NdbScanFilter (which can be used on both 314 @ref NdbScanOperation and @ref NdbIndexScanOperation) or bounds which 315 can only be used on index scans (@ref NdbIndexScanOperation::setBound()). 316 An index scan can use both NdbScanFilter and bounds. 317 318 @note When NdbScanFilter is used, each row is examined, whether or not it is 319 actually returned. However, when using bounds, only rows within the bounds will be examined. 320 321 <h4>Step 3: Specify Attribute Actions</h4> 322 323 Next, it is necessary to define which attributes should be read. 324 As with transaction attributes, scan attributes are defined by name but it is 325 also possible to use the attributes' identities to define attributes. 326 327 As previously discussed (see @ref secSync), the value read is returned as 328 an NdbRecAttr object by the NdbOperation::getValue() method. 329 330 <h3>Using Scan to Update/Delete</h3> 331 Scanning can also be used to update or delete rows. 332 This is performed by 333 -# Scanning using exclusive locks (using NdbOperation::LM_Exclusive) 334 -# When iterating through the result set, for each row optionally calling 335 either NdbScanOperation::updateCurrentTuple() or 336 NdbScanOperation::deleteCurrentTuple() 337 -# (If performing NdbScanOperation::updateCurrentTuple():) 338 Setting new values for records simply by using @ref NdbOperation::setValue() 339 (on the new NdbOperation object retured from updateCurrentTuple()). 340 NdbOperation::equal() should <em>not</em> be called in such cases, as the primary 341 key is retrieved from the scan. 342 343 @note The actual update or delete will not be performed until the next 344 call to NdbTransaction::execute(), just as with single row operations. 345 NdbTransaction::execute() also must be called before any locks are released; 346 see @ref secScanLocks for more information. 347 348 <h4>Features Specific to Index Scans</h4> 349 350 When performing an index scan, it is possible to 351 scan only a subset of a table using @ref NdbIndexScanOperation::setBound(). 352 In addition, result sets can be sorted in either ascending or descending order, using 353 @ref NdbIndexScanOperation::readTuples(). Note that rows are returned unordered 354 by default, that is, unless <var>sorted</var> is set to <b>true</b>. 355 It is also important to note that, when using NdbIndexScanOperation::BoundEQ 356 on a partition key, only fragments containing rows will actually be scanned. 357 358 @note When performing a sorted scan, any value passed as the 359 NdbIndexScanOperation::readTuples() method's <code>parallel</code> argument 360 will be ignored and maximum parallelism will be used instead. In other words, all 361 fragments which it is possible to scan will be scanned simultaneously and in parallel 362 in such cases. 363 364 @subsection secScanLocks Lock handling with scans 365 366 Performing scans on either a table or an index has the potential to 367 return a great many records; however, Ndb will lock only a predetermined 368 number of rows per fragment at a time. 369 How many rows will be locked per fragment is controlled by the 370 <var>batch</var> parameter passed to NdbScanOperation::readTuples(). 371 372 In order to allow the application to handle how locks are released, 373 NdbScanOperation::nextResult() has a Boolean parameter <var>fetch_allow</var>. 374 If NdbScanOperation::nextResult() is called with <var>fetch_allow</var> equal to 375 <b>false</b>, then no locks may be released as result of the function call. 376 Otherwise the locks for the current batch may be released. 377 378 This next example shows a scan delete that handle locks in an efficient manner. 379 For the sake of brevity, we omit error-handling. 380 @code 381 int check; 382 383 // Outer loop for each batch of rows 384 while((check = MyScanOperation->nextResult(true)) == 0) 385 { 386 do 387 { 388 // Inner loop for each row within batch 389 MyScanOperation->deleteCurrentTuple(); 390 } while((check = MyScanOperation->nextResult(false)) == 0); 391 392 // When no more rows in batch, exeute all defined deletes 393 MyTransaction->execute(NoCommit); 394 } 395 @endcode 396 397 See @ref ndbapi_scan.cpp for a more complete example of a scan. 398 399 @section secError Error Handling 400 401 Errors can occur either when operations making up a transaction are being 402 defined, or when the transaction is actually being executed. Catching and 403 handling either sort of error requires testing the value returned by 404 NdbTransaction::execute(), and then, if an error is indicated (that is, 405 if this value is equal to -1), using the following two methods in order to 406 identify the error's type and location: 407 408 - NdbTransaction::getNdbErrorOperation() returns a reference to the 409 operation causing the most recent error. 410 - NdbTransaction::getNdbErrorLine() yields the method number of the 411 erroneous method in the operation. 412 413 This short example illustrates how to detect an error and to use these 414 two methods to identify it: 415 416 @code 417 theTransaction = theNdb->startTransaction(); 418 theOperation = theTransaction->getNdbOperation("TEST_TABLE"); 419 if (theOperation == NULL) goto error; 420 theOperation->readTuple(NdbOperation::LM_Read); 421 theOperation->setValue("ATTR_1", at1); 422 theOperation->setValue("ATTR_2", at1); // Error occurs here 423 theOperation->setValue("ATTR_3", at1); 424 theOperation->setValue("ATTR_4", at1); 425 426 if (theTransaction->execute(Commit) == -1) { 427 errorLine = theTransaction->getNdbErrorLine(); 428 errorOperation = theTransaction->getNdbErrorOperation(); 429 } 430 @endcode 431 432 Here <code>errorLine</code> will be 3, as the error occurred in the 433 third method called on the NdbOperation object (in this case, 434 <code>theOperation</code>); if the result of 435 NdbTransaction::getNdbErrorLine() is 0, this means that the error 436 occurred when the operations were executed. In this example, 437 <code>errorOperation</code> will be a pointer to the <code>theOperation</code> 438 object. The NdbTransaction::getNdbError() method returns an NdbError 439 object providing information about the error. 440 441 @note Transactions are <b>not</b> automatically closed when an error occurs. Call 442 Ndb::closeTransaction() to close the transaction. 443 444 One recommended way to handle a transaction failure 445 (i.e. an error is reported) is to: 446 -# Rollback transaction (call NdbTransaction::execute() with a special parameter) 447 -# Close transaction (call NdbTransaction::closeTransaction()) 448 -# If the error was temporary, attempt to restart the transaction 449 450 Several errors can occur when a transaction contains multiple 451 operations which are simultaneously executed. 452 In this case the application has to go through all operations 453 and query their NdbError objects to find out what really happened. 454 455 It is also important to note that errors can occur even when a commit is 456 reported as successful. In order to handle such situations, the NDB API 457 provides an additional NdbTransaction::commitStatus() method to check the 458 transactions's commit status. 459 460 ******************************************************************************/ 461 462 /** 463 * @page ndbapi_simple.cpp ndbapi_simple.cpp 464 * @include ndbapi_simple.cpp 465 */ 466 467 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 468 /** 469 * @page ndbapi_async.cpp ndbapi_async.cpp 470 * @include ndbapi_async.cpp 471 */ 472 /** 473 * @page ndbapi_async1.cpp ndbapi_async1.cpp 474 * @include ndbapi_async1.cpp 475 */ 476 #endif 477 478 /** 479 * @page ndbapi_retries.cpp ndbapi_retries.cpp 480 * @include ndbapi_retries.cpp 481 */ 482 483 /** 484 * @page ndbapi_simple_index.cpp ndbapi_simple_index.cpp 485 * @include ndbapi_simple_index.cpp 486 */ 487 488 /** 489 * @page ndbapi_scan.cpp ndbapi_scan.cpp 490 * @include ndbapi_scan.cpp 491 */ 492 493 /** 494 * @page ndbapi_event.cpp ndbapi_event.cpp 495 * @include ndbapi_event.cpp 496 */ 497 498 499 /** 500 @page secAdapt Adaptive Send Algorithm 501 502 At the time of "sending" a transaction 503 (using NdbTransaction::execute()), the transactions 504 are in reality <em>not</em> immediately transfered to the NDB Kernel. 505 Instead, the "sent" transactions are only kept in a 506 special send list (buffer) in the Ndb object to which they belong. 507 The adaptive send algorithm decides when transactions should 508 actually be transferred to the NDB kernel. 509 510 The NDB API is designed as a multi-threaded interface and so 511 it is often desirable to transfer database operations from more than 512 one thread at a time. 513 The NDB API keeps track of which Ndb objects are active in transferring 514 information to the NDB kernel and the expected amount of threads to 515 interact with the NDB kernel. 516 Note that a given instance of Ndb should be used in at most one thread; 517 different threads should <em>not</em> use the same Ndb object. 518 519 There are four conditions leading to the transfer of database 520 operations from Ndb object buffers to the NDB kernel: 521 -# The NDB Transporter (TCP/IP, SCI or shared memory) 522 decides that a buffer is full and sends it off. 523 The buffer size is implementation-dependent and 524 may change between MySQL Cluster releases. 525 On TCP/IP the buffer size is usually around 64 KB; 526 Since each Ndb object provides a single buffer per storage node, 527 the notion of a "full" buffer is local to this storage node. 528 -# The accumulation of statistical data on transferred information 529 may force sending of buffers to all storage nodes. 530 -# Every 10 ms, a special transmission thread checks whether or not 531 any send activity has occurred. If not, then the thread will 532 force transmission to all nodes. 533 This means that 20 ms is the maximum time database operations 534 are kept waiting before being sent off. The 10-millisecond limit 535 is likely to become a configuration parameter in 536 future releases of MySQL Cluster; however, for checks that 537 are more frequent than each 10 ms, 538 additional support from the operating system is required. 539 -# For methods that are affected by the adaptive send alorithm 540 (such as NdbTransaction::execute()), there is a <var>force</var> 541 parameter 542 that overrides its default behaviour in this regard and forces 543 immediate transmission to all nodes. See the inidvidual NDB API class 544 listings for more information. 545 546 @note The conditions listed above are subject to change in future releases 547 of MySQL Cluster. 548 */ 549 550 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 551 /** 552 553 For each of these "sent" transactions, there are three 554 possible states: 555 -# Waiting to be transferred to NDB Kernel. 556 -# Has been transferred to the NDB Kernel and is currently 557 being processed. 558 -# Has been transferred to the NDB Kernel and has 559 finished processing. 560 Now it is waiting for a call to a poll method. 561 (When the poll method is invoked, 562 then the transaction callback method will be executed.) 563 564 The poll method invoked (either Ndb::pollNdb() or Ndb::sendPollNdb()) 565 will return when: 566 -# at least 'minNoOfEventsToWakeup' of the transactions 567 in the send list have transitioned to state 3 as described above, and 568 -# all of these transactions have executed their callback methods. 569 */ 570 #endif 571 572 /** 573 @page secConcepts MySQL Cluster Concepts 574 575 The <em>NDB Kernel</em> is the collection of storage nodes 576 belonging to a MySQL Cluster. 577 The application programmer can for most purposes view the 578 set of all storage nodes as a single entity. 579 Each storage node is made up of three main components: 580 - TC : The transaction co-ordinator 581 - ACC : Index storage component 582 - TUP : Data storage component 583 584 When an application program executes a transaction, 585 it connects to one transaction co-ordinator on one storage node. 586 Usually, the programmer does not need to specify which TC should be used, 587 but in some cases when performance is important, the programmer can 588 provide "hints" to use a certain TC. 589 (If the node with the desired transaction co-ordinator is down, then another TC will 590 automatically take over the work.) 591 592 Every storage node has an ACC and a TUP which store 593 the indexes and data portions of the database table fragment. 594 Even though one TC is responsible for the transaction, 595 several ACCs and TUPs on other storage nodes might be involved in the 596 execution of the transaction. 597 598 599 @section secNdbKernelConnection Selecting a Transaction Co-ordinator 600 601 The default method is to select the transaction co-ordinator (TC) determined to be 602 the "closest" storage node, using a heuristic for proximity based on 603 the type of transporter connection. In order of closest to most distant, these are 604 - SCI 605 - SHM 606 - TCP/IP (localhost) 607 - TCP/IP (remote host) 608 If there are several connections available with the same proximity, they will each be 609 selected in a round robin fashion for every transaction. Optionally 610 one may set the method for TC selection to round-robin mode, where each new set of 611 transactions is placed on the next DB node. The pool of connections from which this 612 selection is made consists of all available connections. 613 614 As noted previously, the application programmer can provide hints to the NDB API as to 615 which transaction co-ordinator it should use. This is done by 616 providing a <em>table</em> and <em>partition key</em> 617 (usually the primary key). 618 By using the primary key as the partition key, 619 the transaction will be placed on the node where the primary replica 620 of that record resides. 621 Note that this is only a hint; the system can be 622 reconfigured at any time, in which case the NDB API will choose a transaction 623 co-ordinator without using the hint. 624 For more information, see NdbDictionary::Column::getPartitionKey() and 625 Ndb::startTransaction(). The application programmer can specify 626 the partition key from SQL by using the construct, 627 <code>CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<var>attribute-list</var>);</code>. 628 629 630 @section secRecordStruct NDB Record Structure 631 The NDB Cluster engine used by MySQL Cluster is a relational database engine 632 storing records in tables just as with any other RDBMS. 633 Table rows represent records as tuples of relational data. 634 When a new table is created, its attribute schema is specified for the table as a whole, 635 and thus each record of the table has the same structure. Again, this is typical 636 of relational databases, and NDB is no different in this regard. 637 638 639 @subsection secKeys Primary Keys 640 Each record has from 1 up to 32 attributes which belong 641 to the primary key of the table. 642 643 @section secTrans Transactions 644 645 Transactions are committed first to main memory, 646 and then to disk after a global checkpoint (GCP) is issued. 647 Since all data is (in most NDB Cluster configurations) 648 synchronously replicated and stored on multiple NDB nodes, 649 the system can still handle processor failures without loss 650 of data. 651 However, in the case of a system failure (e.g. the whole system goes down), 652 then all (committed or not) transactions occurring since the latest GCP are lost. 653 654 655 @subsection secConcur Concurrency Control 656 NDB Cluster uses pessimistic concurrency control based on locking. 657 If a requested lock (implicit and depending on database operation) 658 cannot be attained within a specified time, 659 then a timeout error occurs. 660 661 Concurrent transactions as requested by parallel application programs and 662 thread-based applications can sometimes deadlock when they try to access 663 the same information simultaneously. 664 Thus, applications need to be written in a manner so that timeout errors 665 occurring due to such deadlocks are handled gracefully. This generally 666 means that the transaction encountering a timeout should be rolled back 667 and restarted. 668 669 670 @section secHint Hints and Performance 671 672 Placing the transaction co-ordinator in close proximity 673 to the actual data used in the transaction can in many cases 674 improve performance significantly. This is particularly true for 675 systems using TCP/IP. For example, a Solaris system using a single 500 MHz processor 676 has a cost model for TCP/IP communication which can be represented by the formula 677 678 <code>[30 microseconds] + ([100 nanoseconds] * [<var>number of bytes</var>])</code> 679 680 This means that if we can ensure that we use "popular" links we increase 681 buffering and thus drastically reduce the communication cost. 682 The same system using SCI has a different cost model: 683 684 <code>[5 microseconds] + ([10 nanoseconds] * [<var>number of bytes</var>])</code> 685 686 Thus, the efficiency of an SCI system is much less dependent on selection of 687 transaction co-ordinators. 688 Typically, TCP/IP systems spend 30-60% of their working time on communication, 689 whereas for SCI systems this figure is closer to 5-10%. 690 Thus, employing SCI for data transport means that less care from the NDB API 691 programmer is required and greater scalability can be achieved, even for 692 applications using data from many different parts of the database. 693 694 A simple example is an application that uses many simple updates where 695 a transaction needs to update one record. 696 This record has a 32 bit primary key, 697 which is also the partition key. 698 Then the keyData will be the address of the integer 699 of the primary key and keyLen will be 4. 700 */ 701 702 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 703 /** 704 (A transaction's execution can also be divided into three 705 steps: prepare, send, and poll. This allows us to perform asynchronous 706 transactions. More about this later.) 707 */ 708 #endif 709 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 710 /** 711 Another way to execute several parallel transactions is to use 712 asynchronous transactions. 713 */ 714 #endif 715 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 716 /** 717 Operations are of two different kinds: 718 -# standard operations, and 719 -# interpreted program operations. 720 */ 721 #endif 722 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 723 /** 724 <h3>Interpreted Program Operations</h3> 725 The following types of interpreted program operations exist: 726 -# NdbOperation::interpretedUpdateTuple : 727 updates a tuple using an interpreted program 728 -# NdbOperation::interpretedDeleteTuple : 729 delete a tuple using an interpreted program 730 731 The operations interpretedUpdateTuple and interpretedDeleteTuple both 732 work using the unique tuple key. 733 734 These <em>interpreted programs</em> 735 make it possible to perform computations 736 inside the NDB Cluster Kernel instead of in the application 737 program. 738 This is sometimes very effective, since no intermediate results 739 are sent to the application, only the final result. 740 741 742 <h3>Interpreted Update and Delete</h3> 743 744 Operations for interpreted updates and deletes must follow a 745 certain order when defining operations on a tuple. 746 As for read and write operations, 747 one must first define the operation type and then the search key. 748 -# The first step is to define the initial readings. 749 In this phase it is only allowed to use the 750 NdbOperation::getValue method. 751 This part might be empty. 752 -# The second step is to define the interpreted part. 753 The methods supported are the methods listed below except 754 NdbOperation::def_subroutine and NdbOperation::ret_sub 755 which can only be used in a subroutine. 756 NdbOperation::incValue and NdbOperation::subValue 757 increment and decrement attributes 758 (currently only unsigned integers supported). 759 This part can also be empty since interpreted updates 760 can be used for reading and updating the same tuple. 761 <p> 762 Even though getValue and setValue are not really interpreted 763 program instructions, it is still allowed to use them as 764 the last instruction of the program. 765 (If a getValue or setValue is found when an interpret_exit_ok 766 could have been issued then the interpreted_exit_ok 767 will be inserted. 768 A interpret_exit_ok should be viewed as a jump to the first 769 instruction after the interpreted instructions.) 770 -# The third step is to define all updates without any 771 interpreted program instructions. 772 Here a set of NdbOperation::setValue methods are called. 773 There might be zero such calls. 774 -# The fourth step is the final readings. 775 The initial readings reads the initial value of attributes 776 and the final readings reads them after their updates. 777 There might be zero NdbOperation::getValue calls. 778 -# The fifth step is possible subroutine definitions using 779 NdbOperation::def_subroutine and NdbOperation::ret_sub. 780 */ 781 #endif 782 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 783 /** 784 <h3>Interpreted Programs</h3> 785 Interpreted programs are executed in a 786 register-based virtual machine. 787 The virtual machine has eight 64 bit registers numbered 0-7. 788 Each register contains type information which is used both 789 for type conversion and for type checking. 790 791 @note Arrays are currently <b>not</b> supported in the virtual machine. 792 Currently only unsigned integers are supported and of size 793 maximum 64 bits. 794 795 All errors in the interpretation program will cause a 796 transaction abort, but will not affect any other transactions. 797 798 The following are legal interpreted program instructions: 799 -# incValue : Add to an attribute 800 -# subValue : Subtract from an attribute 801 -# def_label : Define a label in the interpreted program 802 -# add_reg : Add two registers 803 -# sub_reg : Subtract one register from another 804 -# load_const_u32 : Load an unsigned 32 bit value into a register 805 -# load_const_u64 : Load an unsigned 64 bit value into a register 806 -# load_const_null : Load a NULL value into a register 807 -# read_attr : Read attribute value into a register 808 -# write_attr : Write a register value into an attribute 809 -# branch_ge : Compares registers and possibly jumps to specified label 810 -# branch_gt : Compares registers and possibly jumps to specified label 811 -# branch_le : Compares registers and possibly jumps to specified label 812 -# branch_lt : Compares registers and possibly jumps to specified label 813 -# branch_eq : Compares registers and possibly jumps to specified label 814 -# branch_ne : Compares registers and possibly jumps to specified label 815 -# branch_ne_null : Jumps if register does not contain NULL value 816 -# branch_eq_null : Jumps if register contains NULL value 817 -# branch_label : Unconditional jump to label 818 -# interpret_exit_ok : Exit interpreted program 819 (approving tuple if used in scan) 820 -# interpret_exit_nok : Exit interpreted program 821 (disqualifying tuple if used in scan) 822 823 There are also three instructions for subroutines, which 824 are described in the next section. 825 826 @subsection subsubSub Interpreted Programs: Subroutines 827 828 The following are legal interpreted program instructions for 829 subroutines: 830 -# NdbOperation::def_subroutine : 831 Defines start of subroutine in interpreted program code 832 -# NdbOperation::call_sub : 833 Calls a subroutine 834 -# NdbOperation::ret_sub : 835 Return from subroutine 836 837 The virtual machine executes subroutines using a stack for 838 its operation. 839 The stack allows for up to 32 subroutine calls in succession. 840 Deeper subroutine nesting will cause an abort of the transaction. 841 842 All subroutines starts with the instruction 843 NdbOperation::def_subroutine and ends with the instruction 844 NdbOperation::ret_sub. 845 If it is necessary to return earlier in the subroutine 846 it has to be done using a branch_label instruction 847 to a label defined right before the 848 NdbOperation::ret_sub instruction. 849 850 @note The subroutines are automatically numbered starting with 0. 851 The parameter used by NdbOperation::def_subroutine 852 should match the automatic numbering to make it easier to 853 debug the interpreted program. 854 */ 855 #endif 856 857 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 858 /** 859 @section secAsync Asynchronous Transactions 860 The asynchronous interface is used to increase the speed of 861 transaction executing by better utilizing the connection 862 between the application and the NDB Kernel. 863 The interface is used to send many transactions 864 at the same time to the NDB kernel. 865 This is often much more efficient than using synchronous transactions. 866 Sending many transactions at the same time ensures that bigger 867 chunks of data are sent when actually sending and thus decreasing 868 the operating system overhead. 869 870 The synchronous call to NdbTransaction::execute 871 normally performs three main steps:<br> 872 -# <b>Prepare</b> 873 Check transaction status 874 - if problems, abort the transaction 875 - if ok, proceed 876 -# <b>Send</b> 877 Send the defined operations since last execute 878 or since start of transaction. 879 -# <b>Poll</b> 880 Wait for response from NDB kernel. 881 882 The asynchronous method NdbTransaction::executeAsynchPrepare 883 only perform step 1. 884 (The abort part in step 1 is only prepared for. The actual 885 aborting of the transaction is performed in a later step.) 886 887 Asynchronous transactions are defined and executed 888 in the following way. 889 -# Start (create) transactions (same way as for the 890 synchronous transactions) 891 -# Add and define operations (also as in the synchronous case) 892 -# <b>Prepare</b> transactions 893 (using NdbTransaction::executeAsynchPrepare or 894 NdbTransaction::executeAsynch) 895 -# <b>Send</b> transactions to NDB Kernel 896 (using Ndb::sendPreparedTransactions, 897 NdbTransaction::executeAsynch, or Ndb::sendPollNdb) 898 -# <b>Poll</b> NDB kernel to find completed transactions 899 (using Ndb::pollNdb or Ndb::sendPollNdb) 900 -# Close transactions (same way as for the synchronous transactions) 901 902 See example program in section @ref ndbapi_example2.cpp. 903 904 This prepare-send-poll protocol actually exists in four variants: 905 - (Prepare-Send-Poll). This is the one-step variant provided 906 by synchronous transactions. 907 - (Prepare-Send)-Poll. This is the two-step variant using 908 NdbTransaction::executeAsynch and Ndb::pollNdb. 909 - Prepare-(Send-Poll). This is the two-step variant using 910 NdbTransaction::executeAsynchPrepare and Ndb::sendPollNdb. 911 - Prepare-Send-Poll. This is the three-step variant using 912 NdbTransaction::executeAsynchPrepare, Ndb::sendPreparedTransactions, and 913 Ndb::pollNdb. 914 915 Transactions first has to be prepared by using method 916 NdbTransaction::executeAsynchPrepare or NdbTransaction::executeAsynch. 917 The difference between these is that 918 NdbTransaction::executeAsynch also sends the transaction to 919 the NDB kernel. 920 One of the arguments to these methods is a callback method. 921 The callback method is executed during polling (item 5 above). 922 923 Note that NdbTransaction::executeAsynchPrepare does not 924 send the transaction to the NDB kernel. When using 925 NdbTransaction::executeAsynchPrepare, you either have to call 926 Ndb::sendPreparedTransactions or Ndb::sendPollNdb to send the 927 database operations. 928 (Ndb::sendPollNdb also polls Ndb for completed transactions.) 929 930 The methods Ndb::pollNdb and Ndb::sendPollNdb checks if any 931 sent transactions are completed. The method Ndb::sendPollNdb 932 also send all prepared transactions before polling NDB. 933 Transactions still in the definition phase (i.e. items 1-3 above, 934 transactions which has not yet been sent to the NDB kernel) are not 935 affected by poll-calls. 936 The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb) 937 will return when: 938 -# at least 'minNoOfEventsToWakeup' of the transactions 939 are finished processing, and 940 -# all of these transactions have executed their 941 callback methods. 942 943 The poll method returns the number of transactions that 944 have finished processing and executed their callback methods. 945 946 @note When an asynchronous transaction has been started and sent to 947 the NDB kernel, it is not allowed to execute any methods on 948 objects belonging to this transaction until the transaction 949 callback method have been executed. 950 (The transaction is stated and sent by either 951 NdbTransaction::executeAsynch or through the combination of 952 NdbTransaction::executeAsynchPrepare and either 953 Ndb::sendPreparedTransactions or Ndb::sendPollNdb). 954 955 More about how transactions are sent the NDB Kernel is 956 available in section @ref secAdapt. 957 */ 958 #endif 959 960 961 /** 962 963 Put this back when real array ops are supported 964 i.e. get/setValue("kalle[3]"); 965 966 @subsection secArrays Array Attributes 967 A table attribute in NDB Cluster can be of type <var>Array</var>, 968 meaning that the attribute consists of an ordered sequence of 969 elements. In such cases, <var>attribute size</var> is the size 970 (expressed in bits) of any one element making up the array; the 971 <var>array size</var> is the number of elements in the array. 972 973 */ 974 975 #ifndef Ndb_H 976 #define Ndb_H 977 978 #include <ndb_types.h> 979 #include "ndbapi_limits.h" 980 #include "ndb_cluster_connection.hpp" 981 #include "NdbError.hpp" 982 #include "NdbDictionary.hpp" 983 984 class NdbObjectIdMap; 985 class NdbOperation; 986 class NdbEventOperationImpl; 987 class NdbScanOperation; 988 class NdbIndexScanOperation; 989 class NdbIndexOperation; 990 class NdbTransaction; 991 class NdbApiSignal; 992 class NdbRecAttr; 993 class NdbLabel; 994 class NdbBranch; 995 class NdbSubroutine; 996 class NdbCall; 997 class Table; 998 class BaseString; 999 class NdbEventOperation; 1000 class NdbBlob; 1001 class NdbReceiver; 1002 class TransporterFacade; 1003 class PollGuard; 1004 class Ndb_local_table_info; 1005 template <class T> struct Ndb_free_list_t; 1006 class NdbLockHandle; 1007 1008 typedef void (* NdbEventCallback)(NdbEventOperation*, Ndb*, void*); 1009 1010 #define WAITFOR_RESPONSE_TIMEOUT 120000 // Milliseconds 1011 1012 #define NDB_SYSTEM_DATABASE "sys" 1013 #define NDB_SYSTEM_SCHEMA "def" 1014 1015 /** 1016 * @class Ndb 1017 * @brief Represents the NDB kernel and is the main class of the NDB API. 1018 * 1019 * Always start your application program by creating an Ndb object. 1020 * By using several Ndb objects it is possible to design 1021 * a multi-threaded application, but note that Ndb objects 1022 * cannot be shared by several threads. 1023 * Different threads should use different Ndb objects. 1024 * A thread might however use multiple Ndb objects. 1025 * Currently there is a limit of maximum 128 Ndb objects 1026 * per application process. 1027 * 1028 * @note It is not allowed to call methods in the NDB API 1029 * on the same Ndb object in different threads 1030 * simultaneously (without special handling of the 1031 * Ndb object). 1032 * 1033 * @note The Ndb object is multi-thread safe in the following manner. 1034 * Each Ndb object can ONLY be handled in one thread. 1035 * If an Ndb object is handed over to another thread then the 1036 * application must ensure that a memory barrier is used to 1037 * ensure that the new thread see all updates performed by 1038 * the previous thread. 1039 * Semaphores, mutexes and so forth are easy ways of issuing memory 1040 * barriers without having to bother about the memory barrier concept. 1041 * 1042 */ 1043 1044 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1045 // to be documented later 1046 /* 1047 * If one Ndb object is used to handle parallel transactions through the 1048 * asynchronous programming interface, please read the notes regarding 1049 * asynchronous transactions (Section @ref secAsync). 1050 * The asynchronous interface provides much higher performance 1051 * in some situations, but is more complicated for the application designer. 1052 * 1053 * @note Each Ndb object should either use the methods for 1054 * asynchronous transaction or the methods for 1055 * synchronous transactions but not both. 1056 */ 1057 #endif 1058 1059 class Ndb 1060 { 1061 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1062 friend class NdbReceiver; 1063 friend class NdbOperation; 1064 friend class NdbEventOperationImpl; 1065 friend class NdbEventBuffer; 1066 friend class NdbTransaction; 1067 friend class Table; 1068 friend class NdbApiSignal; 1069 friend class NdbIndexOperation; 1070 friend class NdbScanOperation; 1071 friend class NdbIndexScanOperation; 1072 friend class NdbDictionary::Dictionary; 1073 friend class NdbDictionaryImpl; 1074 friend class NdbDictInterface; 1075 friend class NdbBlob; 1076 friend class NdbImpl; 1077 friend class Ndb_cluster_connection; 1078 friend class Ndb_cluster_connection_impl; 1079 friend class Ndb_internal; 1080 friend class NdbScanFilterImpl; 1081 friend class PollGuard; 1082 friend class NdbQueryImpl; 1083 friend class NdbQueryOperationImpl; 1084 #endif 1085 1086 public: 1087 /** 1088 * @name General 1089 * @{ 1090 */ 1091 /** 1092 * The Ndb object represents a connection to a database. 1093 * 1094 * @note The init() method must be called before the Ndb object may actually be used. 1095 * 1096 * @param ndb_cluster_connection is a connection to the cluster containing 1097 * the database to be used 1098 * @param aCatalogName is the name of the catalog to be used. 1099 * @note The catalog name provides a namespace for the tables and 1100 * indexes created in any connection from the Ndb object. 1101 * @param aSchemaName is the name of the schema you 1102 * want to use. 1103 * @note The schema name provides an additional namespace 1104 * for the tables and indexes created in a given catalog. 1105 */ 1106 Ndb(Ndb_cluster_connection *ndb_cluster_connection, 1107 const char* aCatalogName = "", const char* aSchemaName = "def"); 1108 1109 ~Ndb(); 1110 1111 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1112 /** 1113 * The current ndb_cluster_connection get_ndb_cluster_connection. 1114 * 1115 * @return the current connection 1116 */ 1117 Ndb_cluster_connection& get_ndb_cluster_connection(); 1118 #endif 1119 1120 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1121 /** 1122 * The current catalog name can be fetched by getCatalogName. 1123 * 1124 * @return the current catalog name 1125 */ 1126 const char * getCatalogName() const; 1127 1128 /** 1129 * The current catalog name can be set by setCatalogName. 1130 * 1131 * @param aCatalogName is the new name of the current catalog 1132 */ 1133 int setCatalogName(const char * aCatalogName); 1134 1135 /** 1136 * The current schema name can be fetched by getSchemaName. 1137 * 1138 * @return the current schema name 1139 */ 1140 const char * getSchemaName() const; 1141 1142 /** 1143 * The current schema name can be set by setSchemaName. 1144 * 1145 * @param aSchemaName is the new name of the current schema 1146 */ 1147 int setSchemaName(const char * aSchemaName); 1148 #endif 1149 1150 /** 1151 * The current database name can be fetched by getDatabaseName. 1152 * 1153 * @return the current database name 1154 */ 1155 const char * getDatabaseName() const; 1156 1157 /** 1158 * The current database name can be set by setDatabaseName. 1159 * 1160 * @param aDatabaseName is the new name of the current database 1161 */ 1162 int setDatabaseName(const char * aDatabaseName); 1163 1164 /** 1165 * The current database schema name can be fetched by getDatabaseSchemaName. 1166 * 1167 * @return the current database schema name 1168 */ 1169 const char * getDatabaseSchemaName() const; 1170 1171 /** 1172 * The current database schema name can be set by setDatabaseSchemaName. 1173 * 1174 * @param aDatabaseSchemaName is the new name of the current database schema 1175 */ 1176 int setDatabaseSchemaName(const char * aDatabaseSchemaName); 1177 1178 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1179 /** Set database and schema name to match previously retrieved table 1180 * 1181 * Returns non-zero if table internal name does not contain 1182 * non-empty database and schema names 1183 */ 1184 int setDatabaseAndSchemaName(const NdbDictionary::Table* t); 1185 #endif 1186 1187 /** 1188 * Initializes the Ndb object 1189 * 1190 * @param maxNoOfTransactions 1191 * Maximum number of parallel 1192 * NdbTransaction objects that can be handled by the Ndb object. 1193 * Maximum value is 1024. 1194 * 1195 * @note each scan or index scan operation uses one extra 1196 * NdbTransaction object 1197 * 1198 * @return 0 if successful, -1 otherwise. 1199 */ 1200 int init(int maxNoOfTransactions = 4); 1201 1202 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED 1203 /** 1204 * Wait for Ndb object to successfully set-up connections to 1205 * the NDB kernel. 1206 * Starting to use the Ndb object without using this method 1207 * gives unspecified behavior. 1208 * 1209 * @param timeout The maximum time we will wait for 1210 * the initiation process to finish. 1211 * Timeout is expressed in seconds. 1212 * @return 0: Ndb is ready and timeout has not occurred.<br> 1213 * -1: Timeout has expired 1214 */ 1215 int waitUntilReady(int timeout = 60); 1216 #endif 1217 1218 /** @} *********************************************************************/ 1219 1220 /** 1221 * @name Meta Information 1222 * @{ 1223 */ 1224 1225 /** 1226 * Get an object for retrieving or manipulating database schema information 1227 * 1228 * @note this object operates outside any transaction 1229 * 1230 * @return Object containing meta information about all tables 1231 * in NDB Cluster. 1232 */ 1233 class NdbDictionary::Dictionary* getDictionary() const; 1234 1235 1236 /** @} *********************************************************************/ 1237 1238 /** 1239 * @name Event subscriptions 1240 * @{ 1241 */ 1242 1243 /** 1244 * Create a subcription to an event defined in the database 1245 * 1246 * @param eventName 1247 * unique identifier of the event 1248 * 1249 * @return Object representing an event, NULL on failure 1250 */ 1251 NdbEventOperation* createEventOperation(const char* eventName); 1252 /** 1253 * Drop a subscription to an event 1254 * 1255 * @param eventOp 1256 * Event operation 1257 * 1258 * @return 0 on success 1259 */ 1260 int dropEventOperation(NdbEventOperation* eventOp); 1261 1262 /** 1263 * Wait for an event to occur. Will return as soon as an event 1264 * is detected on any of the created events. 1265 * 1266 * @param aMillisecondNumber 1267 * maximum time to wait 1268 * 1269 * @return > 0 if events available, 0 if no events available, < 0 on failure 1270 */ 1271 int pollEvents(int aMillisecondNumber, Uint64 *latestGCI= 0); 1272 1273 /** 1274 * Returns an event operation that has data after a pollEvents 1275 * 1276 * @return an event operations that has data, NULL if no events left with data. 1277 */ 1278 NdbEventOperation *nextEvent(); 1279 1280 /** 1281 * Check if all events are consistent 1282 * If node failure occurs during resource exaustion events 1283 * may be lost and the delivered event data might thus be incomplete. 1284 * 1285 * @param OUT aGCI 1286 * any inconsistent GCI found 1287 * 1288 * @return true if all received events are consistent, false if possible 1289 * inconsistency 1290 */ 1291 bool isConsistent(Uint64& gci); 1292 1293 /** 1294 * Check if all events in a GCI are consistent 1295 * If node failure occurs during resource exaustion events 1296 * may be lost and the delivered event data might thus be incomplete. 1297 * 1298 * @param aGCI 1299 * the GCI to check 1300 * 1301 * @return true if GCI is consistent, false if possible inconsistency 1302 */ 1303 bool isConsistentGCI(Uint64 gci); 1304 1305 /** 1306 * Iterate over distinct event operations which are part of current 1307 * GCI. Valid after nextEvent. Used to get summary information for 1308 * the epoch (e.g. list of all tables) before processing event data. 1309 * 1310 * Set *iter=0 to start. Returns NULL when no more. If event_types 1311 * is not NULL, it returns bitmask of received event types. 1312 */ 1313 const NdbEventOperation* 1314 getGCIEventOperations(Uint32* iter, Uint32* event_types); 1315 1316 1317 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1318 int flushIncompleteEvents(Uint64 gci); 1319 NdbEventOperation *getEventOperation(NdbEventOperation* eventOp= 0); 1320 Uint64 getLatestGCI(); 1321 void forceGCP(); 1322 void setReportThreshEventGCISlip(unsigned thresh); 1323 void setReportThreshEventFreeMem(unsigned thresh); 1324 #endif 1325 1326 /** @} *********************************************************************/ 1327 1328 /** 1329 * @name Starting and Closing Transactions 1330 * @{ 1331 */ 1332 1333 /** 1334 * Start a transaction 1335 * 1336 * @note When the transaction is completed it must be closed using 1337 * Ndb::closeTransaction or NdbTransaction::close. 1338 * The transaction must be closed independent of its outcome, i.e. 1339 * even if there is an error. 1340 * 1341 * @param table Pointer to table object used for deciding 1342 * which node to run the Transaction Coordinator on 1343 * @param keyData Pointer to partition key corresponding to 1344 * <var>table</var> 1345 * @param keyLen Length of partition key expressed in bytes 1346 * 1347 * @return NdbTransaction object, or NULL on failure. 1348 */ 1349 NdbTransaction* startTransaction(const NdbDictionary::Table *table= 0, 1350 const char *keyData = 0, 1351 Uint32 keyLen = 0); 1352 1353 1354 /** 1355 * Structure for passing in pointers to distribution key values 1356 * When distribution key has multiple parts, they should be 1357 * passed as an array, with the last part's ptr == NULL. 1358 * 1359 */ 1360 struct Key_part_ptr 1361 { 1362 const void * ptr; 1363 unsigned len; 1364 }; 1365 1366 /** 1367 * Structure for describing a table partition in terms of either 1368 * 1369 * PS_NONE 1370 * No partitioning info provided. 1371 * 1372 * PS_USER_DEFINED 1373 * A specific partition id for a table with user defined 1374 * partitioning 1375 * 1376 * PS_DISTR_KEY_PART_PTR 1377 * An array of a table's distribution key values for a 1378 * table with native partitioning. 1379 * 1380 * PS_DISTR_KEY_RECORD 1381 * A row in given NdbRecord format containing a natively 1382 * partitioned table's distribution key values 1383 * 1384 */ 1385 1386 struct PartitionSpec 1387 { 1388 enum SpecType 1389 { 1390 PS_NONE = 0, 1391 PS_USER_DEFINED = 1, 1392 PS_DISTR_KEY_PART_PTR = 2, 1393 PS_DISTR_KEY_RECORD = 3 1394 }; 1395 1396 Uint32 type; 1397 1398 union 1399 { 1400 struct { 1401 Uint32 partitionId; 1402 } UserDefined; 1403 1404 struct { 1405 const Key_part_ptr* tableKeyParts; 1406 void* xfrmbuf; 1407 Uint32 xfrmbuflen; 1408 } KeyPartPtr; 1409 1410 struct { 1411 const NdbRecord* keyRecord; 1412 const char* keyRow; 1413 void* xfrmbuf; 1414 Uint32 xfrmbuflen; 1415 } KeyRecord; 1416 }; 1417 }; 1418 1419 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED 1420 /* First version of PartitionSpec, defined here for 1421 * backwards compatibility reasons 1422 */ 1423 struct PartitionSpec_v1 1424 { 1425 enum SpecType 1426 { 1427 PS_NONE = 0, 1428 PS_USER_DEFINED = 1, 1429 PS_DISTR_KEY_PART_PTR = 2 1430 }; 1431 1432 Uint32 type; 1433 1434 union 1435 { 1436 struct { 1437 Uint32 partitionId; 1438 } UserDefined; 1439 1440 struct { 1441 const Key_part_ptr* tableKeyParts; 1442 void* xfrmbuf; 1443 Uint32 xfrmbuflen; 1444 } KeyPartPtr; 1445 }; 1446 }; 1447 #endif 1448 1449 /** 1450 * Start a transaction 1451 * 1452 * @note When the transaction is completed it must be closed using 1453 * Ndb::closeTransaction or NdbTransaction::close. 1454 * The transaction must be closed independent of its outcome, i.e. 1455 * even if there is an error. 1456 * 1457 * @param table Pointer to table object used for deciding 1458 * which node to run the Transaction Coordinator on 1459 * @param keyData Null-terminated array of pointers to keyParts that is 1460 * part of distribution key. 1461 * Length of resp. keyPart will be read from 1462 * metadata and checked against passed value 1463 * @param xfrmbuf Pointer to temporary buffer that will be used 1464 * to calculate hashvalue 1465 * @param xfrmbuflen Lengh of buffer 1466 * 1467 * @note if xfrmbuf is null (default) malloc/free will be made 1468 * if xfrmbuf is not null but length is too short, method will fail 1469 * 1470 * @return NdbTransaction object, or NULL on failure. 1471 */ 1472 NdbTransaction* startTransaction(const NdbDictionary::Table *table, 1473 const struct Key_part_ptr * keyData, 1474 void* xfrmbuf = 0, Uint32 xfrmbuflen = 0); 1475 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1476 NdbTransaction* startTransaction(const NdbRecord *keyRec, const char *keyData, 1477 void* xfrmbuf, Uint32 xfrmbuflen); 1478 #endif 1479 /** 1480 * Start a transaction, specifying table+partition as hint for 1481 * TC-selection 1482 * 1483 */ 1484 NdbTransaction* startTransaction(const NdbDictionary::Table* table, 1485 Uint32 partitionId); 1486 1487 /** 1488 * Compute distribution hash value given table/keys 1489 * 1490 * @param hashvalueptr - OUT, is set to hashvalue if return value is 0 1491 * @param table Pointer to table object 1492 * @param keyData Null-terminated array of pointers to keyParts that is 1493 * part of distribution key. 1494 * Length of resp. keyPart will be read from 1495 * metadata and checked against passed value 1496 * @param xfrmbuf Pointer to temporary buffer that will be used 1497 * to calculate hashvalue 1498 * @param xfrmbuflen Lengh of buffer 1499 * 1500 * @note if xfrmbuf is null (default) malloc/free will be made 1501 * if xfrmbuf is not null but length is too short, method will fail 1502 * Only for use with natively partitioned tables. 1503 * 1504 * @return 0 - ok - hashvalueptr is set 1505 * else - fail, return error code 1506 */ 1507 static int computeHash(Uint32* hashvalueptr, 1508 const NdbDictionary::Table*, 1509 const struct Key_part_ptr * keyData, 1510 void* xfrmbuf = 0, Uint32 xfrmbuflen = 0); 1511 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1512 static int computeHash(Uint32* hashvalueptr, 1513 const NdbRecord *keyRec, const char *keyData, 1514 void* xfrmbuf, Uint32 xfrmbuflen); 1515 #endif 1516 /** 1517 * Close a transaction. 1518 * 1519 * @note should be called after the transaction has completed, irrespective 1520 * of success or failure 1521 */ 1522 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1523 /** 1524 * @note It is not allowed to call Ndb::closeTransaction after sending the 1525 * transaction asynchronously with either 1526 * Ndb::sendPreparedTransactions or 1527 * Ndb::sendPollNdb before the callback method has been called. 1528 * (The application should keep track of the number of 1529 * outstanding transactions and wait until all of them 1530 * has completed before calling Ndb::closeTransaction). 1531 * If the transaction is not committed it will be aborted. 1532 */ 1533 #endif 1534 void closeTransaction(NdbTransaction*); 1535 1536 /** @} *********************************************************************/ 1537 1538 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1539 // to be documented later 1540 /** 1541 * @name Asynchronous Transactions 1542 * @{ 1543 */ 1544 1545 /** 1546 * Wait for prepared transactions. 1547 * Will return as soon as at least 'minNoOfEventsToWakeUp' 1548 * of them have completed, or the maximum time given as timeout has passed. 1549 * 1550 * @param aMillisecondNumber 1551 * Maximum time to wait for transactions to complete. Polling 1552 * without wait is achieved by setting the timer to zero. 1553 * Time is expressed in milliseconds. 1554 * @param minNoOfEventsToWakeup Minimum number of transactions 1555 * which has to wake up before the poll-call will return. 1556 * If minNoOfEventsToWakeup is 1557 * set to a value larger than 1 then this is the minimum 1558 * number of transactions that need to complete before the 1559 * poll will return. 1560 * Setting it to zero means that one should wait for all 1561 * outstanding transactions to return before waking up. 1562 * @return Number of transactions polled. 1563 */ 1564 int pollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT, 1565 int minNoOfEventsToWakeup = 1); 1566 1567 /** 1568 * This send method will send all prepared database operations. 1569 * The default method is to do it non-force and instead 1570 * use the adaptive algorithm. (See Section @ref secAdapt.) 1571 * The second option is to force the sending and 1572 * finally there is the third alternative which is 1573 * also non-force but also making sure that the 1574 * adaptive algorithm do not notice the send. 1575 * In this case the sending will be performed on a 1576 * cyclical 10 millisecond event. 1577 * 1578 * @param forceSend When operations should be sent to NDB Kernel. 1579 * (See @ref secAdapt.) 1580 * - 0: non-force, adaptive algorithm notices it (default); 1581 * - 1: force send, adaptive algorithm notices it; 1582 * - 2: non-force, adaptive algorithm do not notice the send. 1583 */ 1584 void sendPreparedTransactions(int forceSend = 0); 1585 1586 /** 1587 * This is a send-poll variant that first calls 1588 * Ndb::sendPreparedTransactions and then Ndb::pollNdb. 1589 * It is however somewhat faster than calling the methods 1590 * separately, since some mutex-operations are avoided. 1591 * See documentation of Ndb::pollNdb and Ndb::sendPreparedTransactions 1592 * for more details. 1593 * 1594 * @param aMillisecondNumber Timeout specifier 1595 * Polling without wait is achieved by setting the 1596 * millisecond timer to zero. 1597 * @param minNoOfEventsToWakeup Minimum number of transactions 1598 * which has to wake up before the poll-call will return. 1599 * If minNoOfEventsToWakeup is 1600 * set to a value larger than 1 then this is the minimum 1601 * number of transactions that need to complete before the 1602 * poll-call will return. 1603 * Setting it to zero means that one should wait for all 1604 * outstanding transactions to return before waking up. 1605 * @param forceSend When operations should be sent to NDB Kernel. 1606 * (See @ref secAdapt.) 1607 * - 0: non-force, adaptive algorithm notices it (default); 1608 * - 1: force send, adaptive algorithm notices it; 1609 * - 2: non-force, adaptive algorithm does not notice the send. 1610 * @return Number of transactions polled. 1611 */ 1612 int sendPollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT, 1613 int minNoOfEventsToWakeup = 1, 1614 int forceSend = 0); 1615 /** @} *********************************************************************/ 1616 #endif 1617 1618 /** 1619 * @name Error Handling 1620 * @{ 1621 */ 1622 1623 /** 1624 * Get the NdbError object 1625 * 1626 * @note The NdbError object is valid until a new NDB API method is called. 1627 */ 1628 const NdbError & getNdbError() const; 1629 1630 /** 1631 * Get a NdbError object for a specific error code 1632 * 1633 * The NdbError object is valid until you call a new NDB API method. 1634 */ 1635 const NdbError & getNdbError(int errorCode); 1636 1637 /** 1638 * Get a string containing any extra error details in the supplied 1639 * buffer 1640 * Where there is extra detail available a ptr to the start of 1641 * the supplied buffer will be returned. 1642 * If the extra detail string is longer than the passed buffer 1643 * then it will be truncated to fit. 1644 * Where there is no extra detail, NULL will be returned. 1645 */ 1646 const char* getNdbErrorDetail(const NdbError& err, 1647 char* buff, 1648 Uint32 buffLen) const; 1649 1650 /** @} *********************************************************************/ 1651 1652 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL 1653 /** 1654 * Get the application node identity. 1655 * 1656 * @return Node id of this application. 1657 */ 1658 int getNodeId(); 1659 1660 bool usingFullyQualifiedNames(); 1661 1662 /** 1663 * Different types of tampering with the NDB Cluster. 1664 * <b>Only for debugging purposes only.</b> 1665 */ 1666 enum TamperType { 1667 LockGlbChp = 1, ///< Lock GCP 1668 UnlockGlbChp, ///< Unlock GCP 1669 CrashNode, ///< Crash an NDB node 1670 ReadRestartGCI, ///< Request the restart GCI id from NDB Cluster 1671 InsertError ///< Execute an error in NDB Cluster 1672 ///< (may crash system) 1673 }; 1674 1675 /** 1676 * Return a unique tuple id for a table. The id sequence is 1677 * ascending but may contain gaps. Methods which have no 1678 * TupleIdRange argument use NDB API dict cache. They may 1679 * not be called from mysqld. 1680 * 1681 * @param aTableName table name 1682 * 1683 * @param cacheSize number of values to cache in this Ndb object 1684 * 1685 * @return 0 or -1 on error, and tupleId in out parameter 1686 */ 1687 struct TupleIdRange { TupleIdRangeNdb::TupleIdRange1688 TupleIdRange() {} 1689 Uint64 m_first_tuple_id; 1690 Uint64 m_last_tuple_id; 1691 Uint64 m_highest_seen; resetNdb::TupleIdRange1692 void reset() { 1693 m_first_tuple_id = ~(Uint64)0; 1694 m_last_tuple_id = ~(Uint64)0; 1695 m_highest_seen = 0; 1696 }; 1697 }; 1698 1699 int initAutoIncrement(); 1700 1701 int getAutoIncrementValue(const char* aTableName, 1702 Uint64 & autoValue, Uint32 cacheSize, 1703 Uint64 step = 1, Uint64 start = 1); 1704 int getAutoIncrementValue(const NdbDictionary::Table * aTable, 1705 Uint64 & autoValue, Uint32 cacheSize, 1706 Uint64 step = 1, Uint64 start = 1); 1707 int getAutoIncrementValue(const NdbDictionary::Table * aTable, 1708 TupleIdRange & range, Uint64 & autoValue, 1709 Uint32 cacheSize, 1710 Uint64 step = 1, Uint64 start = 1); 1711 int readAutoIncrementValue(const char* aTableName, 1712 Uint64 & autoValue); 1713 int readAutoIncrementValue(const NdbDictionary::Table * aTable, 1714 Uint64 & autoValue); 1715 int readAutoIncrementValue(const NdbDictionary::Table * aTable, 1716 TupleIdRange & range, Uint64 & autoValue); 1717 int setAutoIncrementValue(const char* aTableName, 1718 Uint64 autoValue, bool modify); 1719 int setAutoIncrementValue(const NdbDictionary::Table * aTable, 1720 Uint64 autoValue, bool modify); 1721 int setAutoIncrementValue(const NdbDictionary::Table * aTable, 1722 TupleIdRange & range, Uint64 autoValue, 1723 bool modify); 1724 #ifdef NDBAPI_50_COMPAT getAutoIncrementValue(const NdbDictionary::Table * aTable,Uint32 cacheSize=1)1725 Uint64 getAutoIncrementValue(const NdbDictionary::Table * aTable, 1726 Uint32 cacheSize = 1) 1727 { 1728 Uint64 val; 1729 if (getAutoIncrementValue(aTable, val, cacheSize, 1, 1) == -1) 1730 return ~(Uint64)0; 1731 return val; 1732 } 1733 #endif 1734 bool checkUpdateAutoIncrementValue(TupleIdRange & range, Uint64 autoValue); 1735 private: 1736 int getTupleIdFromNdb(const NdbTableImpl* table, 1737 TupleIdRange & range, Uint64 & tupleId, 1738 Uint32 cacheSize, Uint64 step = 1, Uint64 start = 1); 1739 int readTupleIdFromNdb(const NdbTableImpl* table, 1740 TupleIdRange & range, Uint64 & tupleId); 1741 int setTupleIdInNdb(const NdbTableImpl* table, 1742 TupleIdRange & range, Uint64 tupleId, bool modify); 1743 int checkTupleIdInNdb(TupleIdRange & range, 1744 Uint64 tupleId); 1745 int opTupleIdOnNdb(const NdbTableImpl* table, 1746 TupleIdRange & range, Uint64 & opValue, Uint32 op); 1747 public: 1748 1749 /** 1750 */ 1751 NdbTransaction* hupp( NdbTransaction* ); getReference() const1752 Uint32 getReference() const { return theMyRef;} 1753 1754 struct Free_list_usage 1755 { 1756 const char * m_name; 1757 Uint32 m_created; 1758 Uint32 m_free; 1759 Uint32 m_sizeof; 1760 }; 1761 1762 Free_list_usage * get_free_list_usage(Free_list_usage*); 1763 1764 /* Get minimum known DB node version */ 1765 Uint32 getMinDbNodeVersion() const; 1766 1767 /* Get/Set per-Ndb custom data pointer */ 1768 void setCustomData(void*); 1769 void* getCustomData() const; 1770 1771 /* Some client behaviour counters to assist 1772 * optimisation 1773 */ 1774 enum ClientStatistics 1775 { 1776 /* Latency avoidance : */ 1777 /* Number of times user thread blocked waiting for data node response */ 1778 WaitExecCompleteCount = 0, /* Waiting for PK/UK/Scan requests to complete */ 1779 WaitScanResultCount = 1, /* Waiting for next scan batch(es) to arrive */ 1780 WaitMetaRequestCount = 2, /* Waiting for some meta data operation to complete */ 1781 1782 /* Measured latency */ 1783 WaitNanosCount = 3, /* Nanoseconds spent waiting for kernel response */ 1784 1785 /* Data transfer */ 1786 BytesSentCount = 4, /* Bytes sent to kernel by this object */ 1787 BytesRecvdCount = 5, /* Bytes received from kernel by this object */ 1788 1789 /* Work performed */ 1790 TransStartCount = 6, /* Transactions started */ 1791 TransCommitCount = 7, /* Transactions committed */ 1792 TransAbortCount = 8, /* Transactions aborted */ 1793 TransCloseCount = 9, /* Transactions closed */ 1794 1795 PkOpCount = 10, /* Primary key operation count */ 1796 UkOpCount = 11, /* Unique key operation count */ 1797 TableScanCount = 12, /* Table scans */ 1798 RangeScanCount = 13, /* Range scans */ 1799 1800 /* Efficiency */ 1801 PrunedScanCount = 14, /* Count of scans scanning 1 fragment */ 1802 ScanBatchCount = 15, /* Count of scan batches received */ 1803 ReadRowCount = 16, /* Rows returned to API, from PK/UK/Scan */ 1804 TransLocalReadRowCount = 17, /* Rows returned to API from trans node */ 1805 1806 /* Event Api */ 1807 DataEventsRecvdCount = 18, /* Number of table data change events received */ 1808 NonDataEventsRecvdCount = 19, /* Number of non-data events received */ 1809 EventBytesRecvdCount = 20, /* Number of bytes of event data received */ 1810 1811 NumClientStatistics = 21 /* End marker */ 1812 }; 1813 1814 Uint64 getClientStat(Uint32 id) const; 1815 const char* getClientStatName(Uint32 id) const; 1816 #endif 1817 1818 private: 1819 /***************************************************************************** 1820 * These are service routines used by the other classes in the NDBAPI. 1821 ****************************************************************************/ 1822 Uint32 _unused; 1823 void *_unused2; 1824 1825 Ndb(const Ndb&); // Not impl. 1826 Ndb&operator=(const Ndb&); 1827 1828 void setup(Ndb_cluster_connection *ndb_cluster_connection, 1829 const char* aCatalogName, const char* aSchemaName); 1830 1831 void connected(Uint32 block_reference); 1832 1833 1834 NdbTransaction* startTransactionLocal(Uint32 aPrio, Uint32 aNode, 1835 Uint32 instance); 1836 1837 // Connect the connection object to the Database. 1838 int NDB_connect(Uint32 tNode, Uint32 instance); 1839 NdbTransaction* doConnect(Uint32 nodeId, Uint32 instance); 1840 void doDisconnect(); 1841 1842 NdbReceiver* getNdbScanRec();// Get a NdbScanReceiver from idle list 1843 NdbLabel* getNdbLabel(); // Get a NdbLabel from idle list 1844 NdbBranch* getNdbBranch(); // Get a NdbBranch from idle list 1845 NdbSubroutine* getNdbSubroutine();// Get a NdbSubroutine from idle 1846 NdbCall* getNdbCall(); // Get a NdbCall from idle list 1847 NdbApiSignal* getSignal(); // Get an operation from idle list 1848 NdbRecAttr* getRecAttr(); // Get a receeive attribute object from 1849 // idle list of the Ndb object. 1850 NdbOperation* getOperation(); // Get an operation from idle list 1851 NdbIndexScanOperation* getScanOperation(); // Get a scan operation from idle 1852 NdbIndexOperation* getIndexOperation();// Get an index operation from idle 1853 1854 NdbBlob* getNdbBlob();// Get a blob handle etc 1855 1856 NdbLockHandle* getLockHandle(); // Get a lock handle. 1857 1858 void releaseSignal(NdbApiSignal* anApiSignal); 1859 void releaseSignals(Uint32, NdbApiSignal*, NdbApiSignal*); 1860 void releaseSignalsInList(NdbApiSignal** pList); 1861 void releaseNdbScanRec(NdbReceiver* aNdbScanRec); 1862 void releaseNdbLabel(NdbLabel* anNdbLabel); 1863 void releaseNdbBranch(NdbBranch* anNdbBranch); 1864 void releaseNdbSubroutine(NdbSubroutine* anNdbSubroutine); 1865 void releaseNdbCall(NdbCall* anNdbCall); 1866 void releaseRecAttr (NdbRecAttr* aRecAttr); 1867 void releaseOperation(NdbOperation* anOperation); 1868 void releaseScanOperation(NdbIndexScanOperation*); 1869 void releaseNdbBlob(NdbBlob* aBlob); 1870 void releaseLockHandle(NdbLockHandle* lh); 1871 1872 void check_send_timeout(); 1873 void remove_sent_list(Uint32); 1874 Uint32 insert_completed_list(NdbTransaction*); 1875 Uint32 insert_sent_list(NdbTransaction*); 1876 1877 // Handle a received signal. Used by both 1878 // synchronous and asynchronous interface 1879 void handleReceivedSignal(const NdbApiSignal* anApiSignal, 1880 const struct LinearSectionPtr ptr[3]); 1881 1882 int sendRecSignal(Uint16 aNodeId, 1883 Uint32 aWaitState, 1884 NdbApiSignal* aSignal, 1885 Uint32 nodeSequence, 1886 Uint32 *ret_conn_seq= 0); 1887 1888 // Get block number of this NDBAPI object 1889 int getBlockNumber(); 1890 1891 /**************************************************************************** 1892 * These are local service routines used by this class. 1893 ***************************************************************************/ 1894 1895 int createConIdleList(int aNrOfCon); 1896 int createOpIdleList( int nrOfOp ); 1897 1898 void freeOperation(); // Free the first idle operation. 1899 void freeScanOperation(); // Free the first idle scan operation. 1900 void freeIndexOperation(); // Free the first idle index operation. 1901 void freeNdbCon(); // Free the first idle connection. 1902 void freeSignal(); // Free the first idle signal 1903 void freeRecAttr(); // Free the first idle receive attr obj 1904 void freeNdbLabel(); // Free the first idle NdbLabel obj 1905 void freeNdbBranch();// Free the first idle NdbBranch obj 1906 void freeNdbSubroutine();// Free the first idle NdbSubroutine obj 1907 void freeNdbCall(); // Free the first idle NdbCall obj 1908 void freeNdbScanRec(); // Free the first idle NdbScanRec obj 1909 void freeNdbBlob(); // Free the first etc 1910 1911 NdbTransaction* getNdbCon(); // Get a connection from idle list 1912 1913 /** 1914 * Get a connected NdbTransaction to nodeId 1915 * Returns NULL if none found 1916 */ 1917 NdbTransaction* getConnectedNdbTransaction(Uint32 nodeId, Uint32 instance); 1918 1919 // Release and disconnect from DBTC a connection 1920 // and seize it to theConIdleList 1921 void releaseConnectToNdb (NdbTransaction*); 1922 1923 // Release a connection to idle list 1924 void releaseNdbCon (NdbTransaction*); 1925 1926 int checkInitState(); // Check that we are initialized 1927 void report_node_failure(Uint32 node_id); // Report Failed node 1928 void report_node_failure_completed(Uint32 node_id); // Report Failed node(NF comp.) 1929 1930 void checkFailedNode(); // Check for failed nodes 1931 1932 int NDB_connect(); // Perform connect towards NDB Kernel 1933 1934 // Release arrays of NdbTransaction pointers 1935 void releaseTransactionArrays(); 1936 1937 Uint32 pollCompleted(NdbTransaction** aCopyArray); 1938 void sendPrepTrans(int forceSend); 1939 void reportCallback(NdbTransaction** aCopyArray, Uint32 aNoOfComplTrans); 1940 int poll_trans(int milliSecs, int noOfEventsToWaitFor, PollGuard *pg); 1941 void waitCompletedTransactions(int milliSecs, int noOfEventsToWaitFor, 1942 PollGuard *pg); 1943 void completedTransaction(NdbTransaction* aTransaction); 1944 void completedScanTransaction(NdbTransaction* aTransaction); 1945 1946 void abortTransactionsAfterNodeFailure(Uint16 aNodeId); 1947 1948 static 1949 const char * externalizeTableName(const char * internalTableName, 1950 bool fullyQualifiedNames); 1951 const char * externalizeTableName(const char * internalTableName); 1952 const BaseString internalize_table_name(const char * external_name) const; 1953 1954 static 1955 const char * externalizeIndexName(const char * internalIndexName, 1956 bool fullyQualifiedNames); 1957 const char * externalizeIndexName(const char * internalIndexName); 1958 const BaseString old_internalize_index_name(const NdbTableImpl * table, 1959 const char * external_name) const; 1960 const BaseString internalize_index_name(const NdbTableImpl * table, 1961 const char * external_name) const; 1962 1963 static 1964 const BaseString getDatabaseFromInternalName(const char * internalName); 1965 static 1966 const BaseString getSchemaFromInternalName(const char * internalName); 1967 1968 void* int2void (Uint32 val); 1969 NdbReceiver* void2rec (void* val); 1970 NdbTransaction* void2con (void* val); 1971 NdbOperation* void2rec_op (void* val); 1972 NdbIndexOperation* void2rec_iop (void* val); 1973 NdbTransaction* lookupTransactionFromOperation(const class TcKeyConf *); 1974 1975 Uint64 allocate_transaction_id(); 1976 1977 /****************************************************************************** 1978 * These are the private variables in this class. 1979 *****************************************************************************/ 1980 NdbTransaction** thePreparedTransactionsArray; 1981 NdbTransaction** theSentTransactionsArray; 1982 NdbTransaction** theCompletedTransactionsArray; 1983 1984 Uint32 theNoOfPreparedTransactions; 1985 Uint32 theNoOfSentTransactions; 1986 Uint32 theNoOfCompletedTransactions; 1987 Uint32 theRemainingStartTransactions; 1988 Uint32 theMaxNoOfTransactions; 1989 Uint32 theMinNoOfEventsToWakeUp; 1990 1991 Uint32 theNextConnectNode; 1992 1993 bool fullyQualifiedNames; 1994 1995 1996 1997 class NdbImpl * theImpl; 1998 class NdbDictionaryImpl* theDictionary; 1999 class NdbEventBuffer* theEventBuffer; 2000 2001 NdbTransaction* theTransactionList; 2002 NdbTransaction** theConnectionArray; 2003 2004 Uint32 theMyRef; // My block reference 2005 Uint32 theNode; // The node number of our node 2006 2007 Uint64 the_last_check_time; 2008 Uint64 theFirstTransId; 2009 // The tupleId is retrieved from DB 2010 const NdbDictionary::Table *m_sys_tab_0; 2011 2012 Uint32 theRestartGCI; // the Restart GCI used by DIHNDBTAMPER 2013 2014 NdbError theError; 2015 2016 Int32 theNdbBlockNumber; 2017 2018 enum InitType { 2019 NotConstructed, 2020 NotInitialised, 2021 StartingInit, 2022 Initialised, 2023 InitConfigError 2024 } theInitState; 2025 2026 NdbApiSignal* theCommitAckSignal; 2027 2028 /* Cached minimum connected Db node version */ 2029 Uint32 theCachedMinDbNodeVersion; 2030 2031 2032 #ifdef POORMANSPURIFY 2033 int cfreeSignals; 2034 int cnewSignals; 2035 int cgetSignals; 2036 int creleaseSignals; 2037 #endif 2038 2039 #ifdef VM_TRACE 2040 #include <my_attribute.h> 2041 void printState(const char* fmt, ...) 2042 ATTRIBUTE_FORMAT(printf, 2, 3); 2043 #endif 2044 }; 2045 2046 #endif 2047