MySQL NDB Cluster API Developer Guide
This section provides information about the
Ndb_cluster_connection
class, which models a
connection by a management server (ndb_mgmd) to a
set of data nodes.
None
None
An NDB application program should begin with the creation of
a single Ndb_cluster_connection
object,
and typically makes use of a single
Ndb_cluster_connection
. The application
connects to a cluster management server when this
object's
connect()
method is called. By using the
wait_until_ready()
method it is possible to wait for the connection to reach
one or more data nodes.
An instance of Ndb_cluster_connection
is
used to create an Ndb
object. Prior to NDB 7.3.8 and NDB 7.4.3, it was possible to
delete the Ndb_cluster_connection
used to
create a given instance of Ndb
without
first deleting the dependent Ndb
object.
(Bug #19999242)
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.32 Ndb_cluster_connection class methods and descriptions
Name | Description |
---|---|
Ndb_cluster_connection() |
Constructor; creates a connection to a cluster of data nodes. |
connect() |
Connects to a cluster management server. |
get_auto_reconnect() |
Gets the auto-reconnection setting for API nodes using this
Ndb_cluster_connection . |
get_latest_error() |
Whether or not the most recent attempt to connect succeeded. |
get_latest_error_msg() |
If the most recent attempt to connect failed, provides the reason. |
get_max_adaptive_send_time() |
Get timeout before adaptive send forces the sending of all pending signals. |
get_num_recv_threads() |
Get number of receive threads. |
get_next_ndb_object() |
Used to iterate through multiple Ndb
objects. |
get_recv_thread_activation_threshold() |
Get activation level for bound receive threads. |
get_system_name() |
Get the cluster's system name. |
lock_ndb_objects() |
Disables the creation of new Ndb
objects. |
set_auto_reconnect() |
Enables or disables auto-reconnection of API nodes using this
Ndb_cluster_connection . |
set_data_node_neighbour() |
Sets a neighbor node for for optimal transaction coordinator placement |
set_max_adaptive_send_time() |
Set timeout to elapse before adaptive send forces the sending of all pending signals. |
set_name() |
Provides a name for the connection |
set_num_recv_threads() |
Set number of receive threads to be bound. |
set_recv_thread_cpu() |
Set one or more CPUs to bind receive threads to. |
set_optimized_node_selection() |
Used to control node-selection behavior. |
set_service_uri() |
Set a URI for publication in the
ndbinfo.processes
table |
set_timeout() |
Sets a connection timeout |
unlock_ndb_objects() |
Enables the creation of new Ndb
objects. |
unset_recv_thread_cpu() |
Unset the binding of the receive thread to one or more CPUs. |
wait_until_ready() |
Waits until a connection with one or more data nodes is successful. |
This method creates a connection to an NDB Cluster, that is,
to a cluster of data nodes. The object returned by this
method is required in order to instantiate an
Ndb
object. Thus, every NDB
API application requires the use of an
Ndb_cluster_connection
.
Ndb_cluster_connection
has two
constructors. The first of these is shown here:
Ndb_cluster_connection
(
const char* connection_string
= 0
)
The second constructor takes a node ID in addition to the connection string argument. Its signature and parameters are shown here:
Ndb_cluster_connection ( const char*connection_string
, intforce_api_nodeid
)
The first version of the constructor requires a single
connection_string
parameter,
pointing to the location of the management server.
The second version of the constructor takes two arguments, a
connection_string
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 connection_string
argument.
An instance of Ndb_cluster_connection
.
This method connects to a cluster management server.
int connect ( intretries
= 30, intdelay
= 1, intverbose
= 0 )
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. The default value is 30.
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).
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.
This method retrieves the current
AutoReconnect
setting
for a given
Ndb_cluster_connection
. For
more detailed information, see
Ndb_cluster_connection::set_auto_reconnect().
int get_auto_reconnect ( void )
None.
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.
This method 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.
int get_latest_error ( void ) const
None.
1
or 0
. A return value
of 1
indicates that the latest attempt to
connect failed; if the attempt succeeded, a
0
is returned.
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.
const char* get_latest_error_msg ( void ) const
None.
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.
Get the minimum time in milliseconds that is permit to lapse before the adaptive send mechanism forces all pending signals to be sent.
Uint32 get_max_adaptive_send_time ( )
None.
Wait time as a number of milliseconds. This should always be a value between 0 and 10, inclusive.
This method is used to iterate over a set of
Ndb
objects, retrieving
them one at a time.
const Ndb* get_next_ndb_object
(
const Ndb* p
)
This method takes a single parameter, a pointer to the last
Ndb
object to have been
retrieved or NULL
.
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.
Get the number of receiver threads.
int get_num_recv_threads ( void ) const
None.
The number of receiver threads.
Get the level set for activating the receiver thread bound
by
set_recv_thread_cpu()
.
int get_recv_thread_activation_threshold ( void ) const
None.
An integer threshold value. See Ndb_cluster_connection::set_recv_thread_activation_threshold(), for information about interpreting this value.
Gets the system name from the cluster configuration. This is
the value of the
Name
system
configuration parameter set in the cluster's
config.ini
configuration file.
const char* get_system_name ( void ) const
None.
The cluster system name. If not set in the cluster
configuration file, this is a generated value in the form
MC_
(for example, timestamp
MC_20170426182343
), using
the time that the management server was started.
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()
.
void lock_ndb_objects ( void ) const
This method was made const
in NDB 7.3.15,
7.4.13, and 7.5.4 (Bug #23709232).
For more information, see Ndb_cluster_connection::get_next_ndb_object().
None.
None.
An API node that is disconnected from the cluster is forced
to use a new connection object to reconnect, 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 NDB
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 an NDB Cluster.
void set_auto_reconnect
(
int value
)
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.
None.
Set data node neighbor of the connection, used for optimal
placement of the transaction coordinator. This method be
used after creating the
Ndb_cluster_connection
, but prior to
starting any query threads. This is due to the fact that
this method may change the internal state of the
Ndb_cluster_connection
shared by the
threads using it. This state is not thread-safe; changing it
can lead to non-optimal node selection at the time of the
change.
You can use the
ndb_data_node_neighbour
server system variable to set a data node neighbor for an
NDB Cluster SQL node.
This method was added in NDB 7.5.2.
void set_data_node_neighbour
(
Uint32 neighbour_node
)
The ID of the node to be used as the neighbor.
None.
Set the minimum time in milliseconds that is permit to lapse before the adaptive send mechanism forces all pending signals to be sent.
void set_max_adaptive_send_time
(
Uint32 milliseconds
)
Wait time in milliseconds. The range is 0-10, with 10 being the default value.
None.
Sets a name for the connection. If the name is specified, it is reported in the cluster log.
void set_name
(
const char* name
)
The name
to be used as an
identifier for the connection.
None.
Set the number of receiver threads bound to the CPU (or
CPUs) determined using
set_recv_thread_cpu()
and with the threshold set by
set_recv_thread_activation_threshold()
.
This method should be invoked before trying to connect to any other nodes.
int set_num_recv_threads
(
Uint32 num_recv_threads
)
The number of receive threads. The only supported value is
1
.
-1
indicates an error; any other value
indicates success.
This method can be used to override the
connect()
method's default behavior
as regards which node should be connected to first.
void set_optimized_node_selection
(
int value
)
An integer value
.
None.
Set the level for activating the receiver thread bound by
set_recv_thread_cpu()
.
Below this level, normal user threads are used to receive
signals.
int set_recv_thread_activation_threshold
(
Uint32 threshold
)
An integer threshold
value. 16 or
higher means that receive threads are never used as
receivers. 0 means that the receive thread is always active,
and that retains poll rights for its own exclusive use,
effectively blocking all user threads from becoming
receivers. In such cases care should be taken to ensure that
the receive thread does not compete with the user thread for
CPU resources; it is preferable for it to be locked to a CPU
for its own exclusive use. The default is 8.
-1
indicates an error; any other value
indicates success.
Beginning with NDB 7.5.7 and NDB 7.6.2, this method can be
used to create a URI for publication in
service_URI
column of the the
application's row in the
ndbinfo.processes
table.
Provided that this method is called prior to invoking
connect()
,
the service URI is published immediately upon connection;
otherwise, it is published after a delay of up to
HeartbeatIntervalDbApi
milliseconds.
int set_service_uri ( const char*scheme
, const char*host
, intport
, const char*path
)
This method takes the parameters listed here:
scheme: The URI scheme. This is resticted to lowercase
letters, numbers, and the characters
.
, +
, and
-
(period, plus sign, and dash). The
maximu length is 16 characters; any characters over this
limit are truncated.
host
: The URI network address
or host name. The maximum length is 48 characters
(sufficient for an IPv6 network address); any characters
over this limit are truncated. If null, each data node
reports the network address from its own connection to
this node. An Ndb_cluster_connection
that uses multiple transporters or network addresses to
connect to different data nodes is reflected in multiple
rows in the
ndbinfo.processes
table.
port
: The URI port. This is
not published if it is equal to 0.
path
: The URI path, possibly
followed by a query string beginning with
?
. The maximum combined length of the
path and query may not exceed 128 characters; if longer,
it is truncated to this length.
The path may not begin with a double slash
(//
).
0 on success, 1 in the event of a syntax error.
Set the CPU or CPUs to which the receiver thread should be
bound. Set the level for activating the receiver thread as a
receiver by invoking
set_recv_thread_activation_threshold()
.
Unset the binding for this receiver thread by invoking
unset_recv_thread_cpu()
.
int set_recv_thread_cpu ( Uint16*cpuid_array
, Uint32array_len
, Uint32recv_thread_id
= 0 )
This method takes three parameters, listed here:
An array of one or more CPU IDs to which the receive thread should be bound
The length of this array
The thread ID of the receive thread to bind. The default
value is 0
.
-1
indicates an error; any other value
indicates success.
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 MGM API function
ndb_mgm_set_timeout()
.
int set_timeout
(
int timeout_ms
)
The length of the timeout, in milliseconds
(timeout_ms
). Currently, only
multiples of 1000 are accepted.
0 on success; any other value indicates failure.
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.
void unlock_ndb_objects ( void ) const
This method was made const
in NDB 7.3.15,
7.4.13, and 7.5.4 (Bug #23709232).
For more information, see Ndb_cluster_connection::get_next_ndb_object().
None.
None.
Unset the CPU or CPUs to which the receiver thread was bound
using
set_recv_thread_cpu()
.
int unset_recv_thread_cpu
(
Uint32 recv_thread_id
)
The thread ID of the receiver thread to be unbound.
-1
indicates an error; any other value
indicates success.
This method is needed to establish connections with the data nodes. It waits until the requested connection with one or more data nodes is successful, or until a timeout condition is met.
int wait_until_ready ( inttimeoutBefore
, inttimeoutAfter
)
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.
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.