Apache Ignite C++ Documentation

The apacheignite-cpp Developer Hub

Welcome to the apacheignite-cpp developer hub. You'll find comprehensive guides and documentation to help you start working with apacheignite-cpp as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Thin Client

Lightweight client connection

Thin Client is a lightweight Ignite connection mode. It does not start in JVM process (Java is not required at all), does not participate in cluster, never holds any data (except for metadata), or performs computations.

What it does is establish a socket connection to one or more Ignite nodes, and perform all operations through these nodes.

Thin Client mode is perfect for short-lived and resource-restricted applications, memory and CPU usage is minimal.

Installation

Thin client API is distributed along with the Ignite C++ and shares many classes, headers and libraries with full Ignite C++ API, so you can easily switch from one API to another. Basic installation and building procedure is the same: Getting Started.

Requirements

All requirements are the same as for the thick client, except for the Java part: Java is NOT required.

Configuring Server Nodes

Thin client connector is enabled in Ignite server nodes by default. It can be disabled by setting IgniteConfiguration.clientConnectorConfiguration to null in Java or Spring XML.

Connector settings can be adjusted like this:

<bean  class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="clientConnectorConfiguration">
        <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
            <property name="host" value="myHost"/>
            <property name="port" value="11110"/>
            <property name="portRange" value="30"/>
        </bean>
    </property>
</bean>

Connecting to Cluster

The API for thin client is located under the ignite::thin C++ namespace. The thin client API entry point is the IgniteClient::Start(IgniteClientConfiguration) method. You can use IgniteClientConfiguration class to specify client settings, such as list of server nodes to connect to, security credentials and SSL/TLS settings for the connection.

Make sure that you have properly configured the server nodes if you are using authentication or a secure connection.

Here is an example on how to start a new thin client instance:

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClient()
{
  IgniteClientConfiguration cfg;
  
  //Endpoints list format is "<host>[port[..range]][,...]"
  cfg.SetEndPoints("127.0.0.1:11110,example.com:1234..1240");
  
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client!");
}

Authentication

User credentials must be provided if authentication is enabled on the server.

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClientWithAuth()
{
  IgniteClientConfiguration cfg;
  cfg.SetEndPoints("127.0.0.1:10800");
  
  // Use your own credentials here.
  cfg.SetUser("ignite");
  cfg.SetPassword("ignite");
  
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client with auth!");
}
<bean  class="org.apache.ignite.configuration.IgniteConfiguration">

    <property name="authenticationEnabled" value="true"/>

    <property name="persistentStoreConfiguration">
        <bean class="org.apache.ignite.configuration.PersistentStoreConfiguration"/>
    </property>
  
    <property name="clientConnectorConfiguration">
        <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
            <property name="host" value="127.0.0.1"/>
            <property name="port" value="10800"/>
            <property name="portRange" value="10"/>
        </bean>
    </property>
  
</bean>

Performance Considerations

Thin client is not a part of the cluster topology. Therefore, it has limited information about the cluster and its data distribution. Because of this fact and additional network delays, latency of a single operation of thin client can be worse than that of a thick client. Some steps are taken to improve thin clients latency, such as Best Effort Affinity; however, we recommend to use bulk operations (e.g. GetAll(), SetAll()) for the best performance in terms of throughput over the operations on a single key-value.

Best Effort Affinity

Ignite C++ thin client tries to send data requests to proper nodes in the cluster to avoid additional network delays and provide the best throughput and latency. Therefore, C++ thin client retrieves data affinity mapping for every cache from a random node picked from the endpoints list the first time a CacheClient instance is created.

Since thin client is not a part of the cluster topology, it is not guaranteed that this mapping will always be up-to-date. To refresh the mapping, you can use the CacheClient::RefreshAffinityMapping method. Note that this method is required if the cluster topology has been updated.

Make sure that you list all cluster nodes' addresses in the configuration. If a cluster node address is not in the list, the client will not connect or send requests to it.

Here is an example:

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClientWithAuth()
{
  IgniteClientConfiguration cfg;
  cfg.SetEndPoints("127.0.0.1:10800");
    
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client with auth!");
  
  cache.RefreshAffinityMapping();
  
  // Getting
  std::string val = cacheClient.Gett(42);
}

Thin Client APIs

Thin client offers a subset of full Ignite C++ APIs. It is evolving and we plan to support most APIs in both thick and thin clients in the future.