C API Cluster Samples

The eXtremeDB Cluster packages include sample applications that demonstrate basic distributed database functionality. The samples require running multiple instances (at least two) of the application as separate processes on the same machine (node) or on different nodes in a network. Most of the samples are started with command line parameters that specify the size of the cluster (n_nodes) and the node_id of this instance.

By default, all sample executables are built in the target/bin directory, so after building the sample(s) it is convenient to cd to target/bin to run one instance of the cluster sample and run another instance in the development system debugger. The following general instructions apply to all Cluster samples. For descriptions and instructions for running individual samples see Instructions for running the Cluster Samples below.

Single Processor example

For example, to run two instances of a sample the first instance would be started with a command line like:

 
    cluster_sample 2 0
     

This starts the application as the first of two processes (nodes) with node_id = 0 (a zero-based integer counter). Then in a separate command window start the second instance with node_id = 1:

 
    cluster_sample 2 1
     

In this case the list of nodes will automatically be populated with the IP address and port values: 127.0.0.1:20000, 127.0.0.1:20100.

Multiple Processor example

When running on different network nodes, it is necessary to specify a list of nodes. This can be done directly on the command line using the -nodelist option, or in a node description file by specifying the –nodefile option. The format for the nodelist argument is

 
    <IP_address1> [: <port1>]; <IP_address2> [: <port2> ];....; <IP_addressN> [: <portN>]
     

For example, to run this 2-node sample on the two network nodes 192.168.1.1 and 192.168.1.2, the following command line arguments would be used on the indicated nodes:

 
    192.168.1.1>:cluster_sample --nodelist "192.168.1.1:10000; 192.168.1.2:10000" 0
     
    192.168.1.2>:cluster_sample --nodelist "192.168.1.1:10000; 192.168.1.2:10000" 1
     

Note that the nodelist argument must be the same on all nodes, and the node_id must correspond to the serial number of the node in the list (starting with 0). In the above case 192.168.1.1 is the first in the list, so on node 192.168.1.1 the node_id of 0 is specified; on node 192.168.1.2 the node_id is 1.

Node file example

It may be more convenient to specify the nodes in a file and use the –nodefile option. The node file entries specify the IP address and (optional) port number for each node. For example this 2-node sample would use a file like the following:

nodelist.txt:

 
    192.168.1.1:10000
    192.168.1.2:10000
     

In this case the following command lines would be used to start the two sample instances:

 
    192.168.1.1>:cluster_sample --nodefile nodelist.txt 0
     
    192.168.1.2>:cluster_sample --nodefile nodelist.txt 1
     

Other command line options

The following other options can be specified on the command line to change the default values in the mco_cluster_params_t structure used to control the sample application:

--winlen N	(mco_cluster_params_t:: window::length): the maximum window size in transactions
--winsz N	(mco_cluster_params_t:: window::bsize): the maximum window size in bytes
--winto N	(mco_cluster_params_t::window::timeout): the window timeout value
--sndbuf N	(mco_cluster_params_t::nw::tcp::so_sndbuf): the maximum TCP socket send buffer size in bytes
--rcvbuf N	(mco_cluster_params_t::nw::tcp::so_rcvbuf): the maximum TCP socket receive buffer size in bytes
--connto N	(mco_cluster_params_t::nw::tcp::connect_timeout): the timeout threshold for connecting nodes to each other in milliseconds
--connint N	(mco_cluster_params_t::nw::tcp::connect_interval): the time between attempts to connect to other nodes in milliseconds
--katime N	(mco_cluster_params_t::nw::tcp::keepalive_time): the time between keep-alive messages in milliseconds
--kaprobes N	(mco_cluster_params_t::nw::tcp::keepalive_probes): the maximum number of keep-alive probes to send before a node disconnects
--cpfact N	(mco_cluster_params_t::conn_pool_factor): the maximum percent of cached connections
--debug	(mco_cluster_params_t::mode_mask = MCO_CLUSTER_MODE_DEBUG_OUTPUT): enables debug output to stdout (works only with _debug libraries version)

Instructions for running the Cluster Samples

Please use the links below to view descriptions and specific instructions for the individual Cluster samples:

cluster_attach	Demonstrates how to re-attach a node to a cluster
cluster_binev	Demonstrates using the eXtremeDB Binary Schema Evolution feature to open different versions of a database on different cluster nodes
cluster_demo	Demonstrates basic cluster performance
cluster_discover	Demonstrates how to determine the list of active nodes in a cluster
cluster_dynamic	Demonstrates how to connect a node to a cluster if it was not known in advance
cluster_events	Demonstrates the use of synchronous and asynchronous events in a cluster environment
cluster_mt	Demonstrates the use of multiple listener threads
cluster_nodes	Demonstrates cluster synchronization when one of the nodes in a cluster fails
cluster_open	The simplest cluster example - demonstrates how to create a cluster database
cluster_perf	Shows basic performance statistics
cluster_quorum	Demonstrates how to use the quorum callback technique
cluster_rw	Demonstrates how to tune read-write workload on a per-thread basis
cluster_scatter	Demonstrates how to manually synchronize database content distributed on different nodes
cluster_shared	Demonstrates the use of shared memory in a cluster environment
cluster_window	Demonstrates the use of the transaction window feature to increase overall cluster performance