MySQL :: MySQL NDB Cluster API Developer Guide :: 2.3.12 The Ndb_cluster

Ndb_cluster_connection Class Overview

Parent class

None

Child classes

None

Description

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.

Methods

The following table lists the public methods of this class and the purpose or use of each method:

Table 2.33 Ndb_cluster_connection class methods and descriptions

Name	Description
`Ndb_cluster_connection()`	Constructor; creates a connection to a cluster of data nodes.
`configure_tls()`	Provides TLS configuration data.
`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_tls_certificate_path()`	Get the path to the active TLS certificate.
`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.

Ndb_cluster_connection Class Constructor

Description

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.

Signatures

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,
      int force_api_nodeid
    )

Parameters

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.

Return value

An instance of Ndb_cluster_connection.

Ndb_cluster_connection::configure_tls()

Description

Provides configuration information needed for a TLS connection.

If the node finds active NDB TLS node keys and certificates (created using ndb_sign_keys or another tool) in the search path, it can connect securely to other nodes. If this mehtod is not called for a connection, the search path is the compiled-in default (WITH_NDB_TLS_SEARCH_PATH), and the TLS level is 0 (relaxed).

Signature

void configure_tls
  (
    const char *tls_search_path, 
    int mgm_tls_level
  )

Parameters

tls_search_path: A colon-delimited list of directories that may contain TLS private key files or signed public key certificates. A directory reference contained in the search path may be absolute or relative. Environment variables are expanded.
mgm_tls_level: This is 0 or 1 to specify the TLS requirement for securing the MGM protocol connection between this node and the NDB Management server. 0 means the requirement for TLS is relaxed; the node attempts to use TLS, but the connection succeeds even if TLS does not do so. 1 sets a strict requirement for TLS; failure to establish TLS is treated as an error (and a connection cannot be established).

Return value

none

Ndb_cluster_connection::connect()

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. 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).

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.

Ndb_cluster_connection::get_auto_reconnect()

Description

This method retrieves the current AutoReconnect setting for a given Ndb_cluster_connection. For more detailed information, see 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.

Ndb_cluster_connection::get_latest_error()

Description

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.

Signature

int get_latest_error
    (
      void
    ) const

Parameters

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.

Ndb_cluster_connection::get_latest_error_msg()

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
    ) const

Parameters

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.

Ndb_cluster_connection::get_max_adaptive_send_time()

Description

Get the minimum time in milliseconds that is permit to lapse before the adaptive send mechanism forces all pending signals to be sent.

Signature

Uint32 get_max_adaptive_send_time
    (

    )

Parameters

None.

Return value

Wait time as a number of milliseconds. This should always be a value between 0 and 10, inclusive.

Ndb_cluster_connection::get_next_ndb_object()

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.

Ndb_cluster_connection::get_num_recv_threads()

Description

Get the number of receiver threads.

Signature

int get_num_recv_threads
    (
      void
    ) const

Parameters

None.

Return value

The number of receiver threads.

Ndb_cluster_connection::get_recv_thread_activation_threshold()

Description

Get the level set for activating the receiver thread bound by set_recv_thread_cpu().

Signature

int get_recv_thread_activation_threshold
    (
      void
    ) const

Parameters

None.

Return value

An integer threshold value. See Ndb_cluster_connection::set_recv_thread_activation_threshold(), for information about interpreting this value.

Ndb_cluster_connection::get_system_name()

Description

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.

Signature

const char* get_system_name
    (
      void
    ) const

Parameters

None.

Return value

The cluster system name. If not set in the cluster configuration file, this is a generated value in the form MC_timestamp (for example, MC_20170426182343), using the time that the management server was started.

Ndb_cluster_connection::get_tls_certificate_path()

Description

Retrieve the pathname for the active TLS certificate file. Call after calling connect().

Returns null if connect() has not yet been called, or no valid key and certificate can be found in the TLS search path (whether supplied to configure_tls() or the default).

This method was added in NDB 8.3.0.

Signature

const char *get_tls_certificate_path
  (
    void
  ) 
  const

Parameters

None.

Return value

The absolute path to the TLS certificate file that is currently active.

ndb_cluster_connection::lock_ndb_objects()

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
    ) const

This method is const beginning with NDB 7.4.13 (Bug #23709232).

For more information, see Ndb_cluster_connection::get_next_ndb_object().

Parameters

None.

Return value

None.

Ndb_cluster_connection::set_auto_reconnect()

Description: 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.

Important

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.

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.

Ndb_cluster_connection::set_data_node_neighbour()

Description

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.

Signature

void set_data_node_neighbour
    (
      Uint32 neighbour_node
    )

Parameters

The ID of the node to be used as the neighbor.

Return value

None.

Ndb_cluster_connection::set_max_adaptive_send_time()

Description

Set the minimum time in milliseconds that is permit to lapse before the adaptive send mechanism forces all pending signals to be sent.

Signature

void set_max_adaptive_send_time
    (
      Uint32 milliseconds
    )

Parameters

Wait time in milliseconds. The range is 0-10, with 10 being the default value.

Return value

None.

Ndb_cluster_connection::set_name()

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.

Ndb_cluster_connection::set_num_recv_threads()

Description

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.

Signature

int set_num_recv_threads
    (
      Uint32 num_recv_threads
    )

Parameters

The number of receive threads. The only supported value is 1.

Return value

-1 indicates an error; any other value indicates success.

Ndb_cluster_connection::set_optimized_node_selection()

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.

Ndb_cluster_connection::set_recv_thread_activation_threshold()

Description

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.

Signature

int set_recv_thread_activation_threshold
    (
      Uint32 threshold
    )

Parameters

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.

Return value

-1 indicates an error; any other value indicates success.

Ndb_cluster_connection::set_service_uri()

Description

Beginning with NDB 7.5.7, this method can be used to create a URI for publication in service_URI column of 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.

Signature

int set_service_uri
    (
      const char* scheme,
      const char* host,
      int port,
      const char* path
    )

Parameters

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 (//).

Return value

0 on success, 1 in the event of a syntax error.

Ndb_cluster_connection::set_recv_thread_cpu()

Description

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().

Signature

int set_recv_thread_cpu
    (
      Uint16* cpuid_array,
      Uint32 array_len,
      Uint32 recv_thread_id = 0
    )

Parameters

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.

Return value

-1 indicates an error; any other value indicates success.

Ndb_cluster_connection::set_timeout()

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 MGM API function 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.

Ndb_cluster_connection::unlock_ndb_objects()

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
    ) const

This method is const beginning with NDB 7.4.13 (Bug #23709232).

For more information, see Ndb_cluster_connection::get_next_ndb_object().

Parameters

None.

Return value

None.

Ndb_cluster_connection::unset_recv_thread_cpu()

Description

Unset the CPU or CPUs to which the receiver thread was bound using set_recv_thread_cpu().

Signature

int unset_recv_thread_cpu
    (
      Uint32 recv_thread_id
    )

Parameters

The thread ID of the receiver thread to be unbound.

Return value

-1 indicates an error; any other value indicates success.

Ndb_cluster_connection::wait_until_ready()

Description

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.

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.

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.

2.3.12 The Ndb_cluster_connection Class

Ndb_cluster_connection Class Overview

Ndb_cluster_connection Class Constructor

Ndb_cluster_connection::configure_tls()

Ndb_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_max_adaptive_send_time()

Ndb_cluster_connection::get_next_ndb_object()

Ndb_cluster_connection::get_num_recv_threads()

Ndb_cluster_connection::get_recv_thread_activation_threshold()

Ndb_cluster_connection::get_system_name()

Ndb_cluster_connection::get_tls_certificate_path()

ndb_cluster_connection::lock_ndb_objects()

Ndb_cluster_connection::set_auto_reconnect()

Ndb_cluster_connection::set_data_node_neighbour()

Ndb_cluster_connection::set_max_adaptive_send_time()

Ndb_cluster_connection::set_name()

Ndb_cluster_connection::set_num_recv_threads()

Ndb_cluster_connection::set_optimized_node_selection()

Ndb_cluster_connection::set_recv_thread_activation_threshold()

Ndb_cluster_connection::set_service_uri()

Ndb_cluster_connection::set_recv_thread_cpu()

Ndb_cluster_connection::set_timeout()

Ndb_cluster_connection::unlock_ndb_objects()

Ndb_cluster_connection::unset_recv_thread_cpu()

Ndb_cluster_connection::wait_until_ready()