Ndb_cluster_connection Class ConstructorNdb_cluster_connection::connect()Ndb_cluster_connection::get_auto_reconnect()Ndb_cluster_connection::get_latest_error()Ndb_cluster_connection::get_latest_error_msg()ndb_cluster_connection::get_next_ndb_object()ndb_cluster_connection::lock_ndb_objects()Ndb_cluster_connection::set_auto_reconnect()Ndb_cluster_connection::set_name()Ndb_cluster_connection::set_optimized_node_selection()Ndb_cluster_connection::set_timeout()ndb_cluster_connection::unlock_ndb_objects()Ndb_cluster_connection::wait_until_ready()
This section describes the methods belonging to the
Ndb_cluster_connection class.
Description.
This method creates a connection to a MySQL cluster, that is,
to a cluster of data nodes. The object returned by this method
is required in order to instantiate an
Ndb object. (See
Section 2.3.14, “The Ndb Class”.) Thus, every NDB API application
requires the use of an
Ndb_cluster_connection.
Prior to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4,
Ndb_cluster_connection had a
single constructor, whose signature is shown here:
Signature.
Ndb_cluster_connection
(
const char* connectstring = 0
)
Parameters.
This version of the constructor requires a single
connectstring parameter, pointing
to the location of the management server.
Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, a second constructor is provided which takes a node ID in addition to the connectstring argument. Its signature and parameters are shown here:
Signature.
Ndb_cluster_connection
(
const char* connectstring,
int force_api_nodeid
)
Parameters.
This version of the constructor takes two arguments, a
connectstring and the node ID
(force_api_nodeid) to be used by
this API node. This node ID overrides any node ID value set in
the connectstring argument.
Return value.
(Both versions:) An instance of
Ndb_cluster_connection.
Description. This method connects to a cluster management server.
Signature.
int connect
(
int retries = 30,
int delay = 1,
int verbose = 0
)
Parameters. This method takes three parameters, all of which are optional:
retries specifies the number of
times to retry the connection in the event of failure.
Beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster
NDB 7.1.6, the default value is 30. (Previously the default
was 0.)
0 means that no additional attempts to
connect are made in the event of failure; using a negative
value for retries results in the
connection attempt being repeated indefinitely.
The delay represents the number
of seconds between reconnect attempts; the default is
1 second.
verbose indicates whether the
method should output a report of its progress, with
1 causing this reporting to be enabled;
the default is 0 (reporting disabled).
Return value.
This method returns an int, which can have
one of the following 3 values:
0: The connection attempt was successful.
1: Indicates a recoverable error.
-1: Indicates an unrecoverable error.
Description.
Introduced in MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB
7.0.7, this method retrieves the current
AutoReconnect setting
for a given
Ndb_cluster_connection. For
more detailed information, see
Section 2.3.15.1.8, “Ndb_cluster_connection::set_auto_reconnect()”.
Signature.
int get_auto_reconnect
(
void
)Parameters. None.
Return value.
An integer value 0 or 1,
corresponding to the current
AutoReconnect setting
in effect for for this connection. 0 forces
API nodes to use new connections to the cluster, while
1 enables API nodes to re-use existing
connections.
Description.
This method was introduced in MySQL Cluster NDB 6.3.20 and
MySQL Cluster NDB 6.4.0. It can be used to determine whether
or not the most recent
connect()
attempt made by this
Ndb_cluster_connection
succeeded . If the connection succeeded,
get_latest_error() returns
0; otherwise, it returns
1. If the connection attempt failed, use
Ndb_cluster_connection::get_latest_error_msg()
to obtain an error message giving the reason for the failure.
Signature.
int get_latest_error
(
void
) constParameters. None.
Return value.
1 or 0. A return value
of 1 indicates that the latest attempt to
connect failed; if the attempt succeeded, a
0 is returned.
Description.
If the most recent connection attempt by this
Ndb_cluster_connection failed
(as determined by calling
get_latest_error()),
this method provides an error message supplying information
about the reason for the failure.
Signature.
const char* get_latest_error_msg
(
void
) constParameters. None.
Return value.
A string containing an error message describing a failure by
Ndb_cluster_connection::connect().
If the most recent connection attempt succeeded, an empty
string is returned.
Description.
This method is used to iterate over a set of
Ndb objects, retrieving them
one at a time.
Signature.
const Ndb* get_next_ndb_object
(
const Ndb* p
)
Parameters.
This method takes a single parameter, a pointer to the last
Ndb object to have been
retrieved or NULL.
Return value.
Returns the next Ndb object,
or NULL if no more
Ndb objects are available.
Iterating over Ndb objects.
To retrieve all existing Ndb
objects, perform the following three steps:
Invoke the
lock_ndb_objects()
method. This prevents the creation of any new instances of
Ndb until the
unlock_ndb_objects()
method is called.
Retrieve the first available
Ndb object by passing
NULL to
get_next_ndb_object().
You can retrieve the second Ndb object by
passing the pointer retrieved by the first call to the next
get_next_ndb_object()
call, and so on. When a pointer to the last available
Ndb instance is used, the
method returns NULL.
After you have retrieved all desired
Ndb objects, you should
re-enable Ndb object
creation by calling the
unlock_ndb_objects()
method.
Description.
Calling this method prevents the creation of new instances of
the Ndb class. This method
must be called prior to iterating over multiple
Ndb objects using
get_next_ndb_object().
Signature.
void lock_ndb_objects
(
void
)Parameters. None.
Return value. None.
This method was added in MySQL Cluster NDB 6.1.4. For more
information, see
Section 2.3.15.1.6, “ndb_cluster_connection::get_next_ndb_object()”.
Description.
Prior to MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7,
an API node that was disconnected from the cluster tried to
re-use an existing
Ndb_cluster_connection object
when reconnecting; however, it was discovered that permitting
this also sometimes made it possible for multiple API nodes to
try to connect using the same node ID during a restart of the
cluster. (Bug #45921) Beginning with these versions, API nodes
are instead forced to use a new connection object, unless this
behavior is overridden by setting AutoReconnect =
1 in the config.ini file or
calling this method with 1 as the input value. Calling the
method with 0 for the value has the same effect as setting the
AutoReconnect
configuration parameter (also introduced in those MySQL
Cluster versions) to 0; that is, API nodes are forced to
create new connections.
When called, this method overrides any setting for
AutoReconnect made in
the config.ini file.
For more information, see Defining SQL and Other API Nodes in a MySQL Cluster.
Signature.
void set_auto_reconnect
(
int value
)
Parameters.
A value of 0 or 1 which determines
API node reconnection behavior. 0 forces API nodes to use new
connections
(Ndb_cluster_connection
objects); 1 permits API nodes to re-use existing connections
to the cluster.
Return value. None.
Description. Sets a name for the connection. If the name is specified, it is reported in the cluster log.
Signature.
void set_name
(
const char* name
)
Parameters.
The name to be used as an
identifier for the connection.
Return value. None.
Description.
This method can be used to override the
connect() method's default behavior as
regards which node should be connected to first.
Signature.
void set_optimized_node_selection
(
int value
)
Parameters.
An integer value.
Return value. None.
Description. Used to set a timeout for the connection, to limit the amount of time that we may block when connecting.
This method is actually a wrapper for the function
ndb_mgm_set_timeout(). For more information,
see Section 3.2.4.12, “ndb_mgm_set_timeout()”.
Signature.
int set_timeout
(
int timeout_ms
)
Parameters.
The length of the timeout, in milliseconds
(timeout_ms). Currently, only
multiples of 1000 are accepted.
Return value. 0 on success; any other value indicates failure.
Description.
This method undoes the effects of the
lock_ndb_objects()
method, making it possible to create new instances of
Ndb.
unlock_ndb_objects()
should be called after you have finished retrieving
Ndb objects using the
get_next_ndb_object()
method.
Signature.
void unlock_ndb_objects
(
void
)Parameters. None.
Return value. None.
For more information, see
Section 2.3.15.1.6, “ndb_cluster_connection::get_next_ndb_object()”.
Description. This method waits until the requested connection with one or more data nodes is successful.
Signature.
int wait_until_ready
(
int timeoutBefore,
int timeoutAfter
)
Parameters. This method takes two parameters:
timeoutBefore determines the
number of seconds to wait until the first
“live” node is detected. If this amount of time
is exceeded with no live nodes detected, then the method
immediately returns a negative value.
timeoutAfter determines the
number of seconds to wait after the first
“live” node is detected for all nodes to become
active. If this amount of time is exceeded without all nodes
becoming active, then the method immediately returns a value
greater than zero.
If this method returns 0, then all nodes are
“live”.
Return value.
wait_until_ready() returns an
int, whose value is interpreted as follows:
= 0: All nodes are “live”.
> 0: At least one node is
“live” (however, it is not known whether
all nodes are “live”).
< 0: An error occurred.