# 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