Skip navigation links
2.3.25 The NdbRecord Interface »
Section Navigation      [Toggle]

2.3.24.1. Ndb_cluster_connection Methods

[+/-]

2.3.24.1.1. Ndb_cluster_connection Class Constructor
2.3.24.1.2. Ndb_cluster_connection::set_name()
2.3.24.1.3. Ndb_cluster_connection::set_timeout()
2.3.24.1.4. Ndb_cluster_connection::connect()
2.3.24.1.5. Ndb_cluster_connection::wait_until_ready()
2.3.24.1.6. Ndb_cluster_connection::set_optimized_node_selection()
2.3.24.1.7. ndb_cluster_connection::get_next_ndb_object()
2.3.24.1.8. ndb_cluster_connection::lock_ndb_objects()
2.3.24.1.9. ndb_cluster_connection::unlock_ndb_objects()
2.3.24.1.10. Ndb_cluster_connection::set_auto_reconnect()
2.3.24.1.11. Ndb_cluster_connection::get_auto_reconnect()
2.3.24.1.1. Ndb_cluster_connection Class Constructor

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.8, “The Ndb Class”.) Thus, every NDB API application requires the use of an Ndb_cluster_connection.

Signature.  

Ndb_cluster_connection
    (
      const char* connectstring = 0
    )

Parameters.  This method requires a single parameter — a connectstring pointing to the location of the management server.

Return value.  An instance of Ndb_cluster_connection.

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

2.3.24.1.3. 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 function ndb_mgm_set_timeout(). For more information, see Section 3.2.4.11, “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.

2.3.24.1.4. Ndb_cluster_connection::connect()

Description.  This method connects to a cluster management server.

Signature.  

int connect
    (
      int retries = 0,
      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 (0) means that no additional attempts to connect will be made in the event of failure; 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.

2.3.24.1.5. Ndb_cluster_connection::wait_until_ready()

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.

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

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

  1. Invoke the lock_ndb_objects() method. This prevents the creation of any new instances of Ndb until the unlock_ndb_objects() method is called.

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

  3. After you have retrieved all desired Ndb objects, you should re-enable Ndb object creation by calling the unlock_ndb_objects() method.

See also Section 2.3.24.1.8, “ndb_cluster_connection::lock_ndb_objects()”, and Section 2.3.24.1.9, “ndb_cluster_connection::unlock_ndb_objects()”.

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

Parameters.  None.

Return value.  None.

This method was added in MySQL Cluster NDB 6.1.4. For more information, see Section 2.3.24.1.7, “ndb_cluster_connection::get_next_ndb_object()”.

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

Parameters.  None.

Return value.  None.

For more information, see Section 2.3.24.1.7, “ndb_cluster_connection::get_next_ndb_object()”.

2.3.24.1.10. Ndb_cluster_connection::set_auto_reconnect()

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 allowing this also sometimes allowed 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.

Important

When called, this method overrides any setting for AutoReconnect made in the config.ini file.

For information about AutoReconnect, 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 allows API nodes to re-use existing connections to the cluster.

Return value.  None.

2.3.24.1.11. Ndb_cluster_connection::get_auto_reconnect()

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.24.1.10, “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; 1 allows API nodes to re-use existing connections.