Ndb Class Reference

Represents the NDB kernel and is the main class of the NDB API. More...

#include <Ndb.hpp>

Classes
struct	Free_list_usage
struct	Key_part_ptr
struct	PartitionSpec
struct	PartitionSpec_v1
struct	TupleIdRange

Public Types
enum	TamperType {   LockGlbChp = 1, UnlockGlbChp, CrashNode, ReadRestartGCI,   InsertError }
enum	ClientStatistics {   WaitExecCompleteCount = 0, WaitScanResultCount = 1, WaitMetaRequestCount = 2, WaitNanosCount = 3,   BytesSentCount = 4, BytesRecvdCount = 5, TransStartCount = 6, TransCommitCount = 7,   TransAbortCount = 8, TransCloseCount = 9, PkOpCount = 10, UkOpCount = 11,   TableScanCount = 12, RangeScanCount = 13, PrunedScanCount = 14, ScanBatchCount = 15,   ReadRowCount = 16, TransLocalReadRowCount = 17, DataEventsRecvdCount = 18, NonDataEventsRecvdCount = 19,   EventBytesRecvdCount = 20, NumClientStatistics = 21 }

Public Member Functions
int	getNodeId ()
bool	usingFullyQualifiedNames ()
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)
bool	checkUpdateAutoIncrementValue (TupleIdRange &range, Uint64 autoValue)
NdbTransaction *	hupp (NdbTransaction *)
Uint32	getReference () const
Free_list_usage *	get_free_list_usage (Free_list_usage *)
Uint32	getMinDbNodeVersion () const
void	setCustomData (void *)
void *	getCustomData () const
Uint64	getClientStat (Uint32 id) const
const char *	getClientStatName (Uint32 id) const
General
	Ndb (Ndb_cluster_connection *ndb_cluster_connection, const char *aCatalogName="", const char *aSchemaName="def")
	~Ndb ()
Ndb_cluster_connection &	get_ndb_cluster_connection ()
const char *	getCatalogName () const
int	setCatalogName (const char *aCatalogName)
const char *	getSchemaName () const
int	setSchemaName (const char *aSchemaName)
const char *	getDatabaseName () const
int	setDatabaseName (const char *aDatabaseName)
const char *	getDatabaseSchemaName () const
int	setDatabaseSchemaName (const char *aDatabaseSchemaName)
int	setDatabaseAndSchemaName (const NdbDictionary::Table *t)
int	init (int maxNoOfTransactions=4)
int	waitUntilReady (int timeout=60)
Meta Information
class NdbDictionary::Dictionary *	getDictionary () const
Event subscriptions
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)
int	flushIncompleteEvents (Uint64 gci)
NdbEventOperation *	getEventOperation (NdbEventOperation *eventOp=0)
Uint64	getLatestGCI ()
void	forceGCP ()
void	setReportThreshEventGCISlip (unsigned thresh)
void	setReportThreshEventFreeMem (unsigned thresh)
Asynchronous Transactions
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)
Error Handling
const NdbError &	getNdbError () const
const NdbError &	getNdbError (int errorCode)
const char *	getNdbErrorDetail (const NdbError &err, char *buff, Uint32 buffLen) const

Friends
class	NdbReceiver
class	NdbOperation
class	NdbEventOperationImpl
class	NdbEventBuffer
class	NdbTransaction
class	Table
class	NdbApiSignal
class	NdbIndexOperation
class	NdbScanOperation
class	NdbIndexScanOperation
class	NdbDictionary::Dictionary
class	NdbDictionaryImpl
class	NdbDictInterface
class	NdbBlob
class	NdbImpl
class	Ndb_cluster_connection
class	Ndb_cluster_connection_impl
class	Ndb_internal
class	NdbScanFilterImpl
class	PollGuard
class	NdbQueryImpl
class	NdbQueryOperationImpl

Starting and Closing Transactions
NdbTransaction *	startTransaction (const NdbDictionary::Table *table=0, const char *keyData=0, Uint32 keyLen=0)
NdbTransaction *	startTransaction (const NdbDictionary::Table *table, const struct Key_part_ptr *keyData, void *xfrmbuf=0, Uint32 xfrmbuflen=0)
NdbTransaction *	startTransaction (const NdbRecord *keyRec, const char *keyData, void *xfrmbuf, Uint32 xfrmbuflen)
NdbTransaction *	startTransaction (const NdbDictionary::Table *table, Uint32 partitionId)
void	closeTransaction (NdbTransaction *)
static int	computeHash (Uint32 *hashvalueptr, const NdbDictionary::Table *, const struct Key_part_ptr *keyData, void *xfrmbuf=0, Uint32 xfrmbuflen=0)
static int	computeHash (Uint32 *hashvalueptr, const NdbRecord *keyRec, const char *keyData, void *xfrmbuf, Uint32 xfrmbuflen)

Detailed Description

Represents the NDB kernel and is the main class of the NDB API.

Always start your application program by creating an Ndb object. By using several Ndb objects it is possible to design a multi-threaded application, but note that Ndb objects cannot be shared by several threads. Different threads should use different Ndb objects. A thread might however use multiple Ndb objects. Currently there is a limit of maximum 128 Ndb objects per application process.

Note

It is not allowed to call methods in the NDB API on the same Ndb object in different threads simultaneously (without special handling of the Ndb object).

The Ndb object is multi-thread safe in the following manner. Each Ndb object can ONLY be handled in one thread. If an Ndb object is handed over to another thread then the application must ensure that a memory barrier is used to ensure that the new thread see all updates performed by the previous thread. Semaphores, mutexes and so forth are easy ways of issuing memory barriers without having to bother about the memory barrier concept.

Definition at line 1052 of file Ndb.hpp.

Member Enumeration Documentation

enum Ndb::TamperType

Different types of tampering with the NDB Cluster. Only for debugging purposes only.

Enumerator:

LockGlbChp	Lock GCP.
UnlockGlbChp	Unlock GCP.
CrashNode	Crash an NDB node.
ReadRestartGCI	Request the restart GCI id from NDB Cluster.
InsertError	Execute an error in NDB Cluster (may crash system)

Definition at line 1659 of file Ndb.hpp.

Constructor & Destructor Documentation

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

The Ndb object represents a connection to a database.

Note

The init() method must be called before the Ndb object may actually be used.

Parameters

ndb_cluster_connection	is a connection to the cluster containing the database to be used
aCatalogName	is the name of the catalog to be used.

Note

The catalog name provides a namespace for the tables and indexes created in any connection from the Ndb object.

Parameters

aSchemaName

is the name of the schema you want to use.

Note

The schema name provides an additional namespace for the tables and indexes created in a given catalog.

Definition at line 34 of file Ndbinit.cpp.

Member Function Documentation

void Ndb::closeTransaction

(

NdbTransaction *

aConnection

)

Close a transaction.

Note

should be called after the transaction has completed, irrespective of success or failure

It is not allowed to call Ndb::closeTransaction after sending the transaction asynchronously with either Ndb::sendPreparedTransactions or Ndb::sendPollNdb before the callback method has been called. (The application should keep track of the number of outstanding transactions and wait until all of them has completed before calling Ndb::closeTransaction). If the transaction is not committed it will be aborted.

When a SCAN timed-out, returning the NdbTransaction leads to reuse. And TC crashes when the API tries to reuse it to something else...

Something timed-out, returning the NdbTransaction leads to reuse. And TC crashes when the API tries to reuse it to something else...

NOTE: It's ok to call getNodeSequence() here wo/ having mutex,

Put it back in idle list for that node

Definition at line 954 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int Ndb::computeHash ( Uint32 *  hashvalueptr, const NdbDictionary::Table *  table, const struct Key_part_ptr *  keyData, void *  xfrmbuf = 0, Uint32  xfrmbuflen = 0  )

static

Compute distribution hash value given table/keys

Parameters

hashvalueptr	- OUT, is set to hashvalue if return value is 0
table	Pointer to table object
keyData	Null-terminated array of pointers to keyParts that is part of distribution key. Length of resp. keyPart will be read from metadata and checked against passed value
xfrmbuf	Pointer to temporary buffer that will be used to calculate hashvalue
xfrmbuflen	Lengh of buffer

Note

if xfrmbuf is null (default) malloc/free will be made if xfrmbuf is not null but length is too short, method will fail Only for use with natively partitioned tables.

Returns

0 - ok - hashvalueptr is set else - fail, return error code

Definition at line 373 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbEventOperation * Ndb::createEventOperation

(

const char *

eventName

)

Create a subcription to an event defined in the database

Parameters

eventName

unique identifier of the event

Returns

Object representing an event, NULL on failure

Definition at line 1925 of file Ndb.cpp.

int Ndb::dropEventOperation

(

NdbEventOperation *

eventOp

)

Drop a subscription to an event

Parameters

eventOp

Event operation

Returns

0 on success

Definition at line 1945 of file Ndb.cpp.

Here is the call graph for this function:

Ndb_cluster_connection & Ndb::get_ndb_cluster_connection

(

)

The current ndb_cluster_connection get_ndb_cluster_connection.

Returns

the current connection

Definition at line 1632 of file Ndb.cpp.

const char * Ndb::getCatalogName

(

)

const

The current catalog name can be fetched by getCatalogName.

Returns

the current catalog name

Definition at line 1637 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

const char * Ndb::getDatabaseName

(

)

const

The current database name can be fetched by getDatabaseName.

Returns

the current database name

Definition at line 1676 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

const char * Ndb::getDatabaseSchemaName

(

)

const

The current database schema name can be fetched by getDatabaseSchemaName.

Returns

the current database schema name

Definition at line 1686 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbDictionary::Dictionary * Ndb::getDictionary

(

)

const

Get an object for retrieving or manipulating database schema information

Note

this object operates outside any transaction

Returns

Object containing meta information about all tables in NDB Cluster.

Definition at line 1069 of file Ndb.cpp.

Here is the caller graph for this function:

const NdbEventOperation * Ndb::getGCIEventOperations	(	Uint32 *	iter,
		Uint32 *	event_types
	)

Iterate over distinct event operations which are part of current GCI. Valid after nextEvent. Used to get summary information for the epoch (e.g. list of all tables) before processing event data.

Set *iter=0 to start. Returns NULL when no more. If event_types is not NULL, it returns bitmask of received event types.

Definition at line 2000 of file Ndb.cpp.

const NdbError & Ndb::getNdbError

(

)

const

Get the NdbError object

Note

The NdbError object is valid until a new NDB API method is called.

Definition at line 38 of file Ndberr.cpp.

Here is the caller graph for this function:

const NdbError & Ndb::getNdbError

(

int

errorCode

)

Get a NdbError object for a specific error code

The NdbError object is valid until you call a new NDB API method.

Definition at line 30 of file Ndberr.cpp.

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

Get a string containing any extra error details in the supplied buffer Where there is extra detail available a ptr to the start of the supplied buffer will be returned. If the extra detail string is longer than the passed buffer then it will be truncated to fit. Where there is no extra detail, NULL will be returned.

Definition at line 2107 of file Ndb.cpp.

Here is the call graph for this function:

int Ndb::getNodeId

(

)

Get the application node identity.

Returns

Node id of this application.

Definition at line 1079 of file Ndb.cpp.

const char * Ndb::getSchemaName

(

)

const

The current schema name can be fetched by getSchemaName.

Returns

the current schema name

Definition at line 1656 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int Ndb::init

(

int

maxNoOfTransactions = 4

)

Initializes the Ndb object

Parameters

maxNoOfTransactions

Maximum number of parallel NdbTransaction objects that can be handled by the Ndb object. Maximum value is 1024.

Note

each scan or index scan operation uses one extra NdbTransaction object

Returns

0 if successful, -1 otherwise.

Definition at line 54 of file Ndbif.cpp.

bool Ndb::isConsistent

(

Uint64 &

gci

)

Check if all events are consistent If node failure occurs during resource exaustion events may be lost and the delivered event data might thus be incomplete.

Parameters

OUT	aGCI any inconsistent GCI found

Returns

true if all received events are consistent, false if possible inconsistency

Definition at line 1988 of file Ndb.cpp.

bool Ndb::isConsistentGCI

(

Uint64

gci

)

Check if all events in a GCI are consistent If node failure occurs during resource exaustion events may be lost and the delivered event data might thus be incomplete.

Parameters

aGCI	the GCI to check

Returns

true if GCI is consistent, false if possible inconsistency

Definition at line 1994 of file Ndb.cpp.

NdbEventOperation * Ndb::nextEvent

(

)

Returns an event operation that has data after a pollEvents

Returns

an event operations that has data, NULL if no events left with data.

Definition at line 1982 of file Ndb.cpp.

int Ndb::pollEvents	(	int	aMillisecondNumber,
		Uint64 *	latestGCI = 0
	)

Wait for an event to occur. Will return as soon as an event is detected on any of the created events.

Parameters

aMillisecondNumber

maximum time to wait

Returns

> 0 if events available, 0 if no events available, < 0 on failure

Definition at line 1968 of file Ndb.cpp.

int Ndb::pollNdb	(	int	aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
		int	minNoOfEventsToWakeup = 1
	)

Wait for prepared transactions. Will return as soon as at least 'minNoOfEventsToWakeUp' of them have completed, or the maximum time given as timeout has passed.

Parameters

aMillisecondNumber	Maximum time to wait for transactions to complete. Polling without wait is achieved by setting the timer to zero. Time is expressed in milliseconds.
minNoOfEventsToWakeup	Minimum number of transactions which has to wake up before the poll-call will return. If minNoOfEventsToWakeup is set to a value larger than 1 then this is the minimum number of transactions that need to complete before the poll will return. Setting it to zero means that one should wait for all outstanding transactions to return before waking up.

Returns

Number of transactions polled.

Definition at line 1359 of file Ndbif.cpp.

int Ndb::sendPollNdb	(	int	aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
		int	minNoOfEventsToWakeup = 1,
		int	forceSend = 0
	)

This is a send-poll variant that first calls Ndb::sendPreparedTransactions and then Ndb::pollNdb. It is however somewhat faster than calling the methods separately, since some mutex-operations are avoided. See documentation of Ndb::pollNdb and Ndb::sendPreparedTransactions for more details.

Parameters

aMillisecondNumber	Timeout specifier Polling without wait is achieved by setting the millisecond timer to zero.
minNoOfEventsToWakeup	Minimum number of transactions which has to wake up before the poll-call will return. If minNoOfEventsToWakeup is set to a value larger than 1 then this is the minimum number of transactions that need to complete before the poll-call will return. Setting it to zero means that one should wait for all outstanding transactions to return before waking up.
forceSend	When operations should be sent to NDB Kernel. (See Adaptive Send Algorithm.) 0: non-force, adaptive algorithm notices it (default); 1: force send, adaptive algorithm notices it; 2: non-force, adaptive algorithm does not notice the send.

Returns

Number of transactions polled.

Definition at line 1315 of file Ndbif.cpp.

Here is the caller graph for this function:

void Ndb::sendPreparedTransactions

(

int

forceSend = 0

)

This send method will send all prepared database operations. The default method is to do it non-force and instead use the adaptive algorithm. (See Section Adaptive Send Algorithm.) The second option is to force the sending and finally there is the third alternative which is also non-force but also making sure that the adaptive algorithm do not notice the send. In this case the sending will be performed on a cyclical 10 millisecond event.

Parameters

forceSend

When operations should be sent to NDB Kernel. (See Adaptive Send Algorithm.) 0: non-force, adaptive algorithm notices it (default); 1: force send, adaptive algorithm notices it; 2: non-force, adaptive algorithm do not notice the send.

Definition at line 1298 of file Ndbif.cpp.

Here is the caller graph for this function:

int Ndb::setCatalogName

(

const char *

aCatalogName

)

The current catalog name can be set by setCatalogName.

Parameters

aCatalogName

is the new name of the current catalog

Definition at line 1642 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int Ndb::setDatabaseAndSchemaName

(

const NdbDictionary::Table *

t

)

Set database and schema name to match previously retrieved table

Returns non-zero if table internal name does not contain non-empty database and schema names

Definition at line 1696 of file Ndb.cpp.

Here is the call graph for this function:

int Ndb::setDatabaseName

(

const char *

aDatabaseName

)

The current database name can be set by setDatabaseName.

Parameters

aDatabaseName

is the new name of the current database

Definition at line 1681 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int Ndb::setDatabaseSchemaName

(

const char *

aDatabaseSchemaName

)

The current database schema name can be set by setDatabaseSchemaName.

Parameters

aDatabaseSchemaName

is the new name of the current database schema

Definition at line 1691 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int Ndb::setSchemaName

(

const char *

aSchemaName

)

The current schema name can be set by setSchemaName.

Parameters

aSchemaName

is the new name of the current schema

Definition at line 1661 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

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

Start a transaction

Note

When the transaction is completed it must be closed using Ndb::closeTransaction or NdbTransaction::close. The transaction must be closed independent of its outcome, i.e. even if there is an error.

Parameters

table	Pointer to table object used for deciding which node to run the Transaction Coordinator on
keyData	Pointer to partition key corresponding to table
keyLen	Length of partition key expressed in bytes

Returns

NdbTransaction object, or NULL on failure.

If the user supplied key data We will make a qualified quess to which node is the primary for the the fragment and contact that node

Make this unlikely...assume new interface(s) are prefered

Definition at line 771 of file Ndb.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbTransaction * Ndb::startTransaction	(	const NdbDictionary::Table *	table,
		const struct Key_part_ptr *	keyData,
		void *	xfrmbuf = 0,
		Uint32	xfrmbuflen = 0
	)

Start a transaction

Note

When the transaction is completed it must be closed using Ndb::closeTransaction or NdbTransaction::close. The transaction must be closed independent of its outcome, i.e. even if there is an error.

Parameters

table	Pointer to table object used for deciding which node to run the Transaction Coordinator on
keyData	Null-terminated array of pointers to keyParts that is part of distribution key. Length of resp. keyPart will be read from metadata and checked against passed value
xfrmbuf	Pointer to temporary buffer that will be used to calculate hashvalue
xfrmbuflen	Lengh of buffer

Note

if xfrmbuf is null (default) malloc/free will be made if xfrmbuf is not null but length is too short, method will fail

Returns

NdbTransaction object, or NULL on failure.

Definition at line 724 of file Ndb.cpp.

Here is the call graph for this function:

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

Start a transaction, specifying table+partition as hint for TC-selection

Definition at line 740 of file Ndb.cpp.

Here is the call graph for this function:

int Ndb::waitUntilReady

(

int

timeout = 60

)

Wait for Ndb object to successfully set-up connections to the NDB kernel. Starting to use the Ndb object without using this method gives unspecified behavior.

Parameters

timeout

The maximum time we will wait for the initiation process to finish. Timeout is expressed in seconds.

Returns

0: Ndb is ready and timeout has not occurred.
-1: Timeout has expired

Definition at line 328 of file Ndb.cpp.

Here is the call graph for this function:

Friends And Related Function Documentation

friend class NdbIndexOperation

friend

Sender(s)

Definition at line 1062 of file Ndb.hpp.

friend class NdbOperation

friend

Sender(s)

Definition at line 1056 of file Ndb.hpp.

---

The documentation for this class was generated from the following files:

• storage/ndb/include/ndbapi/Ndb.hpp
• storage/ndb/src/ndbapi/Ndb.cpp
• storage/ndb/src/ndbapi/Ndberr.cpp
• storage/ndb/src/ndbapi/Ndbif.cpp
• storage/ndb/src/ndbapi/NdbImpl.hpp
• storage/ndb/src/ndbapi/Ndbinit.cpp
• storage/ndb/src/ndbapi/Ndblist.cpp